We migrated a .NET app from ABP Framework to Granit without downtime - here's the playbook

#webdev #dotnet #architecture #opensource

We just finished moving a 15-module .NET service from ABP Framework
to Granit — without a maintenance window, without
a code freeze, and without a parallel run-everything-twice phase. The whole
thing took about ten weeks running alongside feature work.

This post walks through the playbook: why we moved, the architecture that
made an incremental cutover possible, the one-page mapping between ABP
and Granit primitives, a real before/after of a CRUD module, and the
single technical gotcha that will trip up anyone whose ABP entities use
int or long keys.

If you want the full reference with every cross-cutting concern covered
(multi-tenancy, audit, settings, permissions, background jobs,
specifications), the canonical version lives in the
Granit migration guide. This
article is the field report.

Why we moved off ABP

Let me get this out of the way: ABP is a fine framework. We didn't
move because something was broken. We moved because four trends in our
codebase finally added up:

We had been writing Minimal API endpoints by hand for new features for two years — CrudAppService<TEntity, TDto> had stopped earning its keep on anything that wasn't pure CRUD.
Our DDD layering (Domain / Application.Contracts / Application / EntityFrameworkCore) was generating four projects per module and a lot of IObjectMapper boilerplate that nobody read.
We had adopted Wolverine for messaging and were fighting IDistributedEventBus to make it route the way we wanted.
New hires kept asking "why is there a parallel IStringLocalizer abstraction on top of the BCL one?" — and we never had a great answer.

Granit is the framework that crystallized out of those four answers: a
modular .NET 10 stack with native Wolverine, Minimal API as the
endpoint surface, BCL primitives where they suffice, and CQRS shaped as
the default rather than a workaround. The conceptual overlap with ABP
is enormous — same [DependsOn] module system, same IMultiTenant
interface name, same ISettingProvider interface name, same
AuditedEntity family — which is what made the migration tractable in
the first place.

The strangler-fig architecture

A big-bang rewrite was never on the table. We ran the new Granit host
alongside the existing ABP host, behind the same ingress, sharing the
same database and the same Keycloak issuer. The ingress decides
per-URL which host serves the request. Each module flips over
independently.

            ┌─────────────────┐
   browser ─►   Ingress (YARP)│
            └────────┬────────┘
                     │
        ┌────────────┴─────────────┐
        │                          │
   /api/legacy/*               /api/orders/*
        │                       /api/inventory/*
        ▼                          ▼
   ┌────────┐                 ┌─────────┐
   │  ABP   │                 │ Granit  │
   │  host  │                 │  host   │
   └───┬────┘                 └────┬────┘
       │                           │
       └────────┬──────────────────┘
                ▼
         ┌──────────────┐
         │ Shared DB    │
         │ Shared OIDC  │
         └──────────────┘

The shared database is the linchpin. Three rules:

Schema ownership belongs to the host that wrote the table first. EF Core migrations are generated by that host; the other side either reads via a read-only DbContext or generates its own migrations into the same __EFMigrationsHistory table.
Audit and tenant columns must keep the same shape during the cutover. ABP uses CreatorId / CreationTime; Granit uses CreatedBy / CreatedAt. We solved this with EF Core column overrides on the Granit side (HasColumnName("CreationTime")) so physical schema didn't drift until the ABP host was gone.
OIDC stays as-is. Tokens minted for the ABP host work as-is on the Granit host. No parallel user store, no token exchange, no "auth migration" sub-project.

The conceptual mapping (cheat sheet)

We carried this table around in the team Notion. The full version is
on the docs site;
here are the rows we hit most:

ABP primitive	Granit equivalent
`AbpModule` + `[DependsOn(...)]`	`GranitModule` + `[DependsOn(...)]`
`IApplicationService` / `CrudAppService<...>`	A Minimal API endpoint class with handler methods
`IRepository<TEntity, TKey>` (~30 helpers)	`DbContext` directly, or a thin custom repository
`AuditedEntity<TKey>` / `FullAuditedEntity<TKey>`	`AuditedEntity` / `FullAuditedEntity` (Id is always `Guid`)
`IMultiTenant` + `ICurrentTenant.Id`	`IMultiTenant` + `ICurrentTenant.Id`
`ISettingProvider.GetOrNullAsync(name)`	`ISettingProvider.GetOrNullAsync(name)` (same shape)
`IPermissionChecker` + `PermissionDefinitionProvider`	ASP.NET Core authorization policies (per-endpoint)
`IDistributedEventBus.PublishAsync`	Wolverine `bus.PublishAsync`
`IBackgroundJobManager.EnqueueAsync`	Wolverine `bus.ScheduleAsync`
`ISpecification<T>` / `Specification<T>`	`Granit.Persistence.Specification<T>` + inline `Spec.For<T>()`
`AuditLog` table	`AuditEntry` rows via `GranitAuditingModule`
`IObjectMapper` (AutoMapper)	Mapperly (compile-time) or manual

The pattern in this table is the headline: most ABP primitives have a
direct Granit equivalent under the same name or a near-identical
shape. The migration is rarely a re-architecture; it's mostly
namespace changes plus a few opinionated rewrites where Granit picks a
different default.

The killer before/after: CrudAppService → Minimal API

This is the diff that drove the migration. Same module — Inventory,
a CRUD aggregate with audit, validation, and four permissions — in
both stacks.

ABP, the standard shape:

[Authorize(MyAppPermissions.Inventory.Default)]
public class InventoryAppService
    : CrudAppService<InventoryItem, InventoryItemDto, Guid,
                     PagedAndSortedResultRequestDto, CreateInventoryItemDto>,
      IInventoryAppService
{
    public InventoryAppService(IRepository<InventoryItem, Guid> repository)
        : base(repository)
    {
        GetPolicyName    = MyAppPermissions.Inventory.Default;
        GetListPolicyName = MyAppPermissions.Inventory.Default;
        CreatePolicyName = MyAppPermissions.Inventory.Create;
        UpdatePolicyName = MyAppPermissions.Inventory.Edit;
        DeletePolicyName = MyAppPermissions.Inventory.Delete;
    }
}

Plus an IApplicationService interface in *.Application.Contracts,
plus DTOs split across two projects, plus a PermissionDefinitionProvider
declaring the permission tree. Five REST endpoints auto-generated, but
also five points of indirection you cannot see in this file.

Granit, the explicit shape:

public static class InventoryEndpoints
{
    public static IEndpointRouteBuilder MapGranitInventory(
        this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/inventory")
            .WithTags("Inventory")
            .RequireAuthorization("inventory.read");

        group.MapGet("/{id:guid}",   GetById);
        group.MapGet("/",            List);
        group.MapPost("/",           Create).RequireAuthorization("inventory.create");
        group.MapPut("/{id:guid}",   Update).RequireAuthorization("inventory.edit");
        group.MapDelete("/{id:guid}", Delete).RequireAuthorization("inventory.delete");

        return app;
    }

    public static async Task<Created<InventoryItemResponse>> Create(
        InventoryItemCreateRequest request,
        IInventoryRepository repo,
        ICurrentTenant currentTenant,
        CancellationToken ct)
    {
        var item = InventoryItem.Create(
            Guid.NewGuid(), currentTenant.Id,
            request.Name, request.Sku, request.Quantity, request.UnitPrice);

        await repo.AddAsync(item, ct);
        return TypedResults.Created($"/inventory/{item.Id}",
            new InventoryItemResponse(item.Id, item.Name, item.Sku,
                item.Quantity, item.UnitPrice, item.CreatedAt));
    }

    // GetById / List / Update / Delete follow the same pattern.
}

The trade-off is that you write each endpoint signature yourself —
there is no shortcut equivalent to CrudAppService, which is the whole
point of moving to explicit Minimal API. In return:

Number of projects per module: 4 → 1 (or 2 if you split persistence).
DTO ↔ entity mapping: IObjectMapper (runtime reflection) → static ToResponse method, or Mapperly (compile-time source generation).
Permissions: PermissionDefinitionProvider + [Authorize(name)] → ASP.NET Core policies declared in the module's ConfigureServices.
Validation: data annotations on DTOs → FluentValidation classes, auto-discovered by AddGranitValidatorsFromAssemblyContaining<T>().
Endpoint registration: declarative (REST auto-exposed) → explicit (you call api.MapGranitInventory() from Program.cs). This is Granit's convention across every shipped module — MapGranitAuditing(), MapGranitParties(), MapGranitBlobStorage(), etc.

You can read all five endpoint signatures in one sitting. That is the
point.

The one gotcha: Guid keys

Here is the single thing that will derail an ABP migration if you
discover it late: Granit's Entity base type fixes Id as Guid.
There is no Entity<TKey>, no AuditedAggregateRoot<int>. The framework
opinion is that every entity has a Guid (v4 or v7) for distributed
id generation, sharding, and tenant isolation.

If your ABP entities use AggregateRoot<int> or <long>, you need a
one-shot key rewrite before any module is ported — both hosts have
to agree on the key type once they read and write the same rows.

We used the deterministic UUID v5 strategy in PostgreSQL: derive each
new Guid from the existing int via uuid_generate_v5(namespace, id::text). The same input always yields the same UUID, so foreign
keys port via the same hash — no lookup table, no downtime.

-- Add new key column, backfilled with deterministic UUIDs.
ALTER TABLE inventory_items
  ADD COLUMN id_new uuid;

UPDATE inventory_items
  SET id_new = uuid_generate_v5('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11', id::text);

-- Rewrite every dependent FK the same way (one statement per FK).
ALTER TABLE inventory_movements
  ADD COLUMN inventory_item_id_new uuid;

UPDATE inventory_movements
  SET inventory_item_id_new =
    uuid_generate_v5('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11', inventory_item_id::text);

-- Swap the primary key.
ALTER TABLE inventory_items DROP CONSTRAINT inventory_items_pkey;
ALTER TABLE inventory_items DROP COLUMN id;
ALTER TABLE inventory_items RENAME COLUMN id_new TO id;
ALTER TABLE inventory_items ADD PRIMARY KEY (id);

-- Re-create each FK constraint.
ALTER TABLE inventory_movements DROP COLUMN inventory_item_id;
ALTER TABLE inventory_movements RENAME COLUMN inventory_item_id_new TO inventory_item_id;
ALTER TABLE inventory_movements
  ADD CONSTRAINT fk_inventory_movements_item
    FOREIGN KEY (inventory_item_id) REFERENCES inventory_items(id);

Critical sequencing: regenerate the ABP-side entity to Guid Id
before running the SQL. If the ABP host stays on int Id after the
rewrite, its EF Core model diverges from the physical schema and every
read throws. We discovered this during a staging dry-run and it would
have been a production incident.

The mapping-table alternative (random Guid per row, persisted in a
_key_migration table) is documented in the
full guide section.

The license footnote that wasn't a footnote

I left this for last because it doesn't fit the technical narrative, but
it ended up being the line-item that got the migration unblocked with
our legal team:

	License	What that means in practice
ABP Framework (OSS core, `abpframework/abp`)	LGPL-3.0	You can link against it from proprietary code (it's "Lesser" GPL). But modifications to the framework itself must be published under LGPL. Many enterprise SCA tools (Black Duck, FOSSA, GitHub Advanced Security) flag LGPL as "needs legal review" before merge.
ABP Commercial (Suite, LeptonX, premium modules)	Proprietary, paid per-seat	Vendor-tied, locked behind support contract.
Granit (entire OSS surface — framework, frontend, templates)	Apache-2.0	Permissive. Use, modify, fork, redistribute — in proprietary derivatives too — with zero copyleft on your app code or your framework patches. Explicit patent grant. Auto-approved by most enterprise SCA pipelines.

Our SCA pipeline (FOSSA) was the unblocker. LGPL-3.0 was flagged as
"requires legal review" on every PR that touched a transitive ABP
dependency, generating a manual ticket each time. Apache-2.0 sails
through. That alone saved us a recurring 2-3 day legal cycle per
sprint, independent of the technical wins.

If you sit in a regulated industry (finance, health, government), the
SCA-friction argument may be the only one your CFO needs to hear.

What we did not migrate

Three things in our ABP setup did not have a 1:1 Granit equivalent.
Worth flagging upfront:

ABP Suite (codegen UI). Granit has no equivalent. We replaced Suite-generated module scaffolding with the dotnet new granit-microservice template and hand-written modules where the template wasn't expressive enough.
The full generic-repository surface. IRepository<T, TKey> exposes ~30 helpers (GetPagedListAsync(skip, take, sorting), FirstOrDefaultAsync(predicate), …). Granit prefers DbSet<T> directly. We ported the four helpers we actually used as extension methods on DbSet<T> and dropped the rest. The temptation to recreate the full surface is real; resist it.
The Angular ABP UI. Our frontend is React, so this didn't bite us — but if your UI is a tightly coupled ABP Angular template, the Granit React companion is a separate migration project, not a drop-in.

The bottom line

Ten weeks, 15 modules, zero downtime, ~40% reduction in module project
count, and a codebase where new hires don't ask "why is there a
parallel abstraction on top of the BCL one?" anymore.

The full step-by-step is in the
Granit migration guide —
including every cross-cutting concern, the FAQ, and the strategy table
for which modules to port in which order.

If you're sitting on an ABP codebase and wondering whether the move is
worth it, the honest answer is: only if Granit's opinions match your
team's. Minimal API over auto-generated controllers, Wolverine over
generic event bus, BCL primitives over wrapped ones, Guid keys
everywhere, and Apache-2.0 over LGPL-3.0. If those five trade-offs
sound like wins, the migration is mechanical. If any of them sound
like regressions, stay on ABP — both frameworks are good at what
they do.

More on Granit: