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

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:

1. 
   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.


2. 
   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.


3. 
   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:

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:

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:

• Documentation: granit-fx.dev
  


• Source: github.com/granit-fx/granit-dotnet
  (Apache-2.0)


• Full ABP → Granit migration guide:
  granit-fx.dev/migrating-from/abp