Upgrade readiness guidance for ABP Microservice solution (9.3.x → latest) – best-practice alignment check #10834

3 Answer(s)

• 

  0

  AI-Bot created 2 months ago

  Support Team ABP Agent

  • Recommended upgrade path (9.3.x → latest) for ABP Microservice + Angular + separated Auth Server

    1. Upgrade backend first, then Angular (keep the system runnable at each step).
    2. Follow ABP’s version-by-version migration guides. Practically, don’t jump “in one big bang” without applying each major version’s migration notes (especially around auth, EF Core, and Angular template/build changes).
    3. Start by applying the official guide for v9.x → v10.0 (since you’re on 9.3.x, this is your first major breakpoint).
       • Use the migration guide(s) as the canonical checklist for code/config changes before moving to the next major.

  • Areas that commonly need attention in this kind of upgrade (microservices + Angular + separated Auth Server)

    • NuGet/NPM alignment: ensure all ABP packages (server + client) are aligned to the exact same target ABP version (a very common source of runtime/DI issues in Angular and module init issues in .NET).
    • Angular builder / template changes: newer ABP Angular templates have moved to newer Angular build systems; expect config differences compared to 9.3.x (workspace config, builders, etc.). Plan time for resolving Angular build & dependency tree issues and regenerating proxies.
    • LeptonX: theme package versions must match the ABP Angular package generation you’re upgrading to (mismatches frequently show up as “blank layout”, menu/render issues, or missing providers).
    • Auth Server (OpenIddict) compatibility:
      • Validate token issuance & validation end-to-end (gateway + all microservices).
      • Validate client configs, CORS/redirect URIs, and any custom claims/resources/scopes you added.
    • EF Core migrations / DbMigrator:
      • Run migrations in a staging copy and verify each service database and the Auth Server database (if separate).
      • Validate seed data changes (permissions, OpenIddict apps, etc.) still run correctly.
    • Distributed events / inbox-outbox (if used): ensure any schema/entity changes introduced by newer ABP versions are migrated correctly and that consumers can still deserialize/handle events.
    • Background jobs: verify your background job provider (Hangfire/Quartz/etc.) and storage schema compatibility and that workers can start cleanly.
    • Multi-tenancy & permission checks: smoke-test tenant switching, tenant-specific connection strings, and permission-protected endpoints.

  • What to validate first in non-production (minimum “upgrade readiness” test plan)

    1. Bring up the whole stack in staging (auth server + gateways + all services + Angular).
    2. Run DbMigrator (or your migration pipeline) and confirm no pending migrations remain.
    3. Validate login + token refresh + logout flows from Angular and from any service-to-service flows.
    4. Validate proxy generation and basic CRUD calls through gateway.
    5. Run a distributed event happy-path test (publish in one service, consume in another).
    6. Run a background job happy-path test.
    7. Run tenant smoke tests (host + a tenant).

  • Practical upgrade checklist (order of operations)

    1. Create a staging environment and restore DB backups there.
    2. Upgrade .NET/NuGet packages across all services (and shared projects) to the target ABP version, applying each major version migration guide changes as you go.
    3. Run all services + Auth Server, fix startup/config/auth issues.
    4. Run EF Core migrations for each service DB (and auth DB) and verify seeding.
    5. Upgrade Angular packages to the matching ABP Angular version (and matching LeptonX packages).
    6. Regenerate Angular proxies (and any module-federation shared libs that depend on generated contracts).
    7. Execute smoke tests + automated tests in staging.
    8. Production rollout plan:
       • deploy binaries first (or blue/green), then apply DB migrations in a controlled step
       • verify auth/token flows immediately
       • keep rollback artifacts (previous containers/packages + DB rollback strategy/backup).

  • Best-practice alignment / “drift” review

    • I can’t review your repository via the tools available in this chat. If you want an alignment review, the ABP team typically needs direct access in a support channel. For non-technical access/licensing and private sharing arrangements, please use the contact form below.

  Links (validated):

  • https://abp.io/docs/latest/release-info/migration-guides
  • https://abp.io/docs/10.0/release-info/migration-guides/abp-10-0
  • https://abp.io/docs/latest/solution-templates/microservice
  • https://abp.io/docs/latest/cli
  • https://abp.io/contact

  ---

  This response was generated by AI. If it didn’t solve your problem, feel free to post a new answer — our support team will jump in to help you soon.

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  mt.developer created 2 months ago

  I need your input on high-level review of our solution structure and key customizations (we can share the repository / relevant modules privately) point since the AI did not answer it

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  maliming created one month ago

  Support Team Fullstack Developer

  Hi,

  You can upgrade from 9.3.x directly to the latest stable (currently 10.6.0) in one step, there is no need to install intermediate versions. What matters is applying the migration guides for each version in order (10.0 → 10.6) while you do it: https://abp.io/docs/latest/release-info/migration-guides

  The 10.0 guide is the biggest one for you: .NET 9 → .NET 10, EF Core 10 and OpenIddict 6 → 7. The others (10.1 - 10.6) are smaller, but a few of them matter for a microservice solution.

  Things that will actually need attention in your setup:

  Backend

  • Move all services, gateways and the DbMigrator projects to .NET 10 (TargetFramework, Dockerfiles, CI images, SDK).
  • OpenIddict 7 changes the OpenIddictToken entity, and the inbox/outbox IncomingEventRecord entity also changed in 10.0. Add a new EF Core migration for each affected DbContext / service database after the package upgrade and remove the ones that come out empty. The OpenIddict migration lands in your auth server database.
  • Identity module: 10.1 adds password history / passkey entities, and in 10.2 you need to add public DbSet<UserInvitation> UserInvitations { get; set; } to your Identity DbContext. Both need migrations.
  • The permission integration endpoint (integration-api/permission-management/permissions/is-granted) changed from GET to POST in 10.3, and there is no GET fallback. Cross-service permission checks use this endpoint, so a 9.3 service calling a 10.x service (or the reverse) will fail. Don't do a service-by-service rollout — upgrade everything in one go, within a maintenance window or as a blue/green switch, so old and new instances don't call each other.
  • If you have custom Swagger filters in the gateways or services, Swashbuckle v10 (Microsoft.OpenApi 2.x) changed the filter signatures, see the 10.1 guide.
  • ABP modules internally use Mapperly now. Your own code can stay on the supported AutoMapper integration — Volo.Abp.AutoMapper is still there and pins the free AutoMapper 14. Migrating your own mappings to Mapperly is optional, see the AutoMapper section in the 10.0 guide: https://abp.io/docs/latest/release-info/migration-guides/abp-10-0
  • Behavior changes to re-test rather than code changes: email/SMS 2FA codes are single-use since 10.4, identity token providers keep only the latest token valid since 10.5, and authenticated client_credentials requests now forward the incoming access token to downstream services in 10.6. Re-test login, 2FA, password reset and machine-to-machine flows.
  • On the auth server side, keep your signing/encryption certificates and Data Protection keys as they are during the upgrade, and verify that tokens issued before the upgrade still refresh and log out correctly afterwards.

  Angular

  • The target is Angular 22 with TypeScript ~6.0.0 (10.1 moved to Angular 21, 10.6 to 22). Apply the 10.1 guide changes (provideZoneChangeDetection(), tsconfig updates), add the @angular/aria package from 10.2, then follow the Angular 22 guide: https://abp.io/docs/latest/release-info/migration-guides/abp-10-6-angular-22
  • With Module Federation, the host, all remotes and shared libraries must be rebuilt against the same Angular / @abp/* / @volo/* / LeptonX versions — check your shared/singleton version constraints in the federation config. Plan most of your UI effort here.
  • LeptonX packages go from 4.3.x to 5.6.0 together with the ABP packages.
  • Regenerate the client proxies after the backend is upgraded (the 10.3 and 10.6 changes affect generated proxies).

  For the solution review: create a private GitHub repository with your solution (or the relevant modules) and invite https://github.com/maliming — remove license codes, connection strings and other secrets first. We'll do a high-level pass over the structure and key customizations (module dependencies, EF Core configuration, shared contracts, auth server and gateway customizations) and point out upgrade blockers and any major drift from the recommended microservice patterns. If GitHub isn't an option, a zip via wetransfer to liming.ma@volosoft.com also works.

  Suggested order for the upgrade itself:

  1. Restore production backups into a staging environment (isolated from production infrastructure — message broker, cache, email/SMS).
  2. Upgrade ABP Studio / CLI first, then update the ABP NuGet/NPM packages to 10.6.0 and the matching LeptonX 5.6.0 / Angular 22 versions, fixing build errors with the guides above.
  3. Add EF Core migrations per service, review the generated SQL, then run the DbMigrator and verify seeding.
  4. Upgrade Angular/LeptonX, rebuild the federation libraries, regenerate proxies.
  5. Smoke test: login/refresh/logout, 2FA, CRUD through the gateways, one distributed event round trip, one background job, host and tenant logins with tenant-specific data.
  6. Production: take DB backups right before the rollout, upgrade all services in one controlled step (maintenance window or blue/green), and run migrations as an explicit step. Keep in mind that restoring a pre-upgrade backup after go-live loses the data written since, so treat backup-restore as the last resort and rehearse the migration in staging until you trust roll-forward.

  Thanks

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel