Why Does My Tiered ABP App Show an Empty Menu While the User Is Still Signed In?

TL;DR: In a tiered MVC application, ABP falls back to an identity-client token when it cannot read the signed-in user's access token, so the API can return a valid but user-less response with an empty grantedPolicies dictionary. Replace the remote-service authenticator so an authenticated user can never take that fallback, then force a fresh OIDC challenge when a page request has a user cookie but no access_token.

The Symptom

The user is visibly signed in, but the application behaves as if they have no permissions:

• The navigation menu is almost empty.
• Permission-guarded buttons and partials disappear.
• An order or product grid returns no rows.
• /api/abp/application-configuration contains an empty auth.grantedPolicies dictionary.
• Signing out and back in fixes the session.

There may be no exception, 401, or 403. The web tier gets a successful response and renders it.

We initially treated this as a permission-cache problem. Logging the granted-policy count proved that it really dropped to zero, but not why. Redis remained healthy during the affected requests. We also lost time on the simplest explanation: a role with no grants produces the same UI. Check the role's permission grants before investigating the framework.

The useful comparison was the claims principal at both ends of one correlated request. The web tier had a user principal. The API tier received a valid client principal with no user subject. That moved the investigation from permission resolution to the outbound HTTP call.

Do not use token length as the test. Decode claims without logging the raw token. A user token normally has a user subject (sub), while a client-credentials token represents the application.

Why It Happens

A tiered ABP MVC UI calls the API through dynamic C# client proxies. Before a protected proxy request is sent, ABP resolves IRemoteServiceHttpClientAuthenticator.

For an MVC or Razor Pages host that depends on AbpHttpClientIdentityModelWebModule, the implementation is HttpContextIdentityModelRemoteServiceHttpClientAuthenticator. Its ABP 10.5.0 sequence is:

1. Unless RemoteServices:<name>:UseCurrentAccessToken is false, call IAbpAccessTokenProvider.GetTokenAsync().
2. If that returns a token, put it on the outgoing request and return.
3. If it returns null, call the base authenticator.

The base IdentityModelRemoteServiceHttpClientAuthenticator calls IIdentityModelAuthenticationService.TryAuthenticateAsync. It selects the remote service's IdentityClient, then the remote-service name, with ABP's identity-client configuration ultimately able to fall back to Default. The official IdentityModel Clients documentation describes that path as server-to-server authentication.

That fallback is intentional when no user exists:

page request
  -> current user's access token exists
  -> API receives user identity

background or app-to-app request
  -> no current user token exists
  -> IdentityClients supplies an application token

broken user session
  -> user cookie still authenticates
  -> access_token is missing
  -> IdentityClients supplies an application token
  -> API receives the application identity

The third branch is the trap. If the client has permission to call the endpoint but no user permissions, the HTTP request can succeed while the response contains no user-specific grants. A successful wrong-identity response is harder to diagnose than a failed request.

ASP.NET Core only stores remote access and refresh tokens in AuthenticationProperties when SaveTokens is enabled; it defaults to false to limit cookie size. ABP's tiered MVC template sets it to true. The framework's HttpContextAbpAccessTokenProvider then uses HttpContext.GetTokenAsync("access_token").

Why that token went missing is a separate investigation. Cookie size, a server-side ticket store, Data Protection configuration, and token-refresh handling are all possible places to look. The fix below does not repair token storage; it prevents a missing token from silently changing the caller's identity.

The Fix

We made the unsafe state explicit: client credentials remain valid when there is no authenticated user, but not when an authenticated user has lost their access token.

Add this class to the tiered web host:

using System.Threading.Tasks;
using Duende.IdentityModel.Client;
using Microsoft.Extensions.Logging;
using Volo.Abp.DependencyInjection;
using Volo.Abp.Http.Client;
using Volo.Abp.Http.Client.Authentication;
using Volo.Abp.Http.Client.IdentityModel.Web;
using Volo.Abp.IdentityModel;
using Volo.Abp.Users;

namespace Acme.Orders.Web;

[Dependency(ReplaceServices = true)]
[ExposeServices(
    typeof(IRemoteServiceHttpClientAuthenticator),
    typeof(HttpContextIdentityModelRemoteServiceHttpClientAuthenticator))]
public class StrictRemoteServiceHttpClientAuthenticator
    : HttpContextIdentityModelRemoteServiceHttpClientAuthenticator
{
    private readonly ICurrentUser _currentUser;
    private readonly ILogger<StrictRemoteServiceHttpClientAuthenticator> _logger;

    public StrictRemoteServiceHttpClientAuthenticator(
        IIdentityModelAuthenticationService identityModelAuthenticationService,
        IAbpAccessTokenProvider accessTokenProvider,
        ICurrentUser currentUser,
        ILogger<StrictRemoteServiceHttpClientAuthenticator> logger)
        : base(identityModelAuthenticationService, accessTokenProvider)
    {
        _currentUser = currentUser;
        _logger = logger;
    }

    public override async Task Authenticate(
        RemoteServiceHttpClientAuthenticateContext context)
    {
        if (context.RemoteService.GetUseCurrentAccessToken() != false)
        {
            var accessToken = await AccessTokenProvider.GetTokenAsync();

            if (accessToken is not null)
            {
                context.Request.SetBearerToken(accessToken);
                return;
            }

            if (_currentUser.IsAuthenticated)
            {
                _logger.LogError(
                    "Blocked identity-client fallback for authenticated user {UserId}. " +
                    "RemoteService={RemoteService}, Path={Path}",
                    _currentUser.Id,
                    context.RemoteServiceName,
                    context.Request.RequestUri?.AbsolutePath);

                // Send no bearer token. A protected API now answers 401 instead
                // of successfully running under the application's identity.
                return;
            }
        }

        // No current user, or UseCurrentAccessToken is explicitly false:
        // preserve ABP's app-to-app identity-client behavior.
        await base.Authenticate(context);
    }
}

[Dependency(ReplaceServices = true)] replaces existing descriptors, while [ExposeServices] makes the two resolution surfaces explicit. The interface is what ABP's client proxy resolves. Exposing the framework concrete type as well prevents application code that injects that type from bypassing the replacement.

Failing loudly protects the API call, but a user should not remain in a broken session. Add page-only middleware that signs out the cookie and uses the application's configured default challenge scheme:

using System;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Http.Extensions;
using Microsoft.Extensions.Logging;

namespace Acme.Orders.Web;

public sealed class EnsureAccessTokenMiddleware
{
    private const string RecoveryCookie = ".Orders.AccessTokenRecovery";

    private static readonly PathString[] ExcludedPrefixes =
    [
        "/api",
        "/Abp",
        "/connect",
        "/hangfire",
        "/health",
        "/signalr",
        "/swagger",
        "/_"
    ];

    private readonly RequestDelegate _next;
    private readonly ILogger<EnsureAccessTokenMiddleware> _logger;

    public EnsureAccessTokenMiddleware(
        RequestDelegate next,
        ILogger<EnsureAccessTokenMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        if (context.User.Identity?.IsAuthenticated == true &&
            IsPageRequest(context))
        {
            var accessToken = await context.GetTokenAsync("access_token");

            if (string.IsNullOrEmpty(accessToken))
            {
                if (context.Request.Cookies.ContainsKey(RecoveryCookie))
                {
                    context.Response.Cookies.Delete(RecoveryCookie);
                    context.Response.StatusCode =
                        StatusCodes.Status500InternalServerError;
                    context.Response.ContentType = "text/plain";
                    await context.Response.WriteAsync(
                        "The sign-in session could not be recovered.");
                    return;
                }

                _logger.LogWarning(
                    "Authenticated page request has no access_token. Path={Path}",
                    context.Request.Path);

                context.Response.Cookies.Append(
                    RecoveryCookie,
                    "1",
                    new CookieOptions
                    {
                        HttpOnly = true,
                        Secure = context.Request.IsHttps,
                        SameSite = SameSiteMode.Lax,
                        IsEssential = true,
                        MaxAge = TimeSpan.FromMinutes(2)
                    });

                var returnUrl = context.Request.GetEncodedPathAndQuery();

                await context.SignOutAsync();
                await context.ChallengeAsync(
                    new AuthenticationProperties { RedirectUri = returnUrl });
                return;
            }

            if (context.Request.Cookies.ContainsKey(RecoveryCookie))
            {
                context.Response.Cookies.Delete(RecoveryCookie);
            }
        }

        await _next(context);
    }

    private static bool IsPageRequest(HttpContext context)
    {
        if (!HttpMethods.IsGet(context.Request.Method) ||
            !context.Request.Headers.Accept.Any(
                value => value?.Contains(
                    "text/html",
                    StringComparison.OrdinalIgnoreCase) == true))
        {
            return false;
        }

        var path = context.Request.Path;

        if (ExcludedPrefixes.Any(prefix => path.StartsWithSegments(prefix)))
        {
            return false;
        }

        return string.IsNullOrEmpty(Path.GetExtension(path.Value));
    }
}

Use the default schemes rather than hard-coding them. The ABP 10.5 tiered MVC template registers "Cookies" as DefaultScheme and "oidc" as DefaultChallengeScheme; OpenIdConnectDefaults.AuthenticationScheme has a different value.

The web module must already depend on AbpHttpClientIdentityModelWebModule. Register the middleware after authentication populates HttpContext.User and before authorization consumes it:

using Microsoft.AspNetCore.Builder;
using Volo.Abp;
using Volo.Abp.AspNetCore.Mvc;
using Volo.Abp.Http.Client.IdentityModel.Web;
using Volo.Abp.Modularity;

namespace Acme.Orders.Web;

[DependsOn(
    typeof(AbpAspNetCoreMvcModule),
    typeof(AbpHttpClientIdentityModelWebModule))]
public class OrdersWebModule : AbpModule
{
    public override void OnApplicationInitialization(
        ApplicationInitializationContext context)
    {
        var app = context.GetApplicationBuilder();

        // Keep the rest of your generated ABP pipeline in its existing order.
        app.UseRouting();
        app.UseAuthentication();

        app.UseMiddleware<EnsureAccessTokenMiddleware>();

        // Keep UseMultiTenancy() and UseDynamicClaims() here when enabled.
        app.UseAuthorization();
        app.UseConfiguredEndpoints();
    }
}

In an existing generated module, add only the UseMiddleware line at the shown location; do not remove its localization, correlation, static-asset, multi-tenancy, dynamic-claims, Swagger, logging, or endpoint configuration.

Gotchas

• Do not disable identity-client authentication globally. Background workers and app-to-app calls have no current user and legitimately need it. UseCurrentAccessToken = false must also retain its documented meaning.
• Middleware order is load-bearing. Before UseAuthentication, there is no populated user to inspect. After UseAuthorization, the broken principal may already have produced an authorization result.
• Restrict the challenge to browser page navigations. Challenging API, SignalR, health, Swagger, dashboard, framework, or static-file requests turns a clear authentication failure into redirects in places that cannot handle them. Extend the exclusions for your routes.
• Keep a loop guard. If the OIDC round-trip returns another token-less ticket, repeatedly challenging hides the underlying fault and can overload the auth server.
• Do not log access tokens, cookie values, client secrets, or full claims. Log the subject type, selected claim names, remote-service name, path, and correlation ID.
• This behavior is unchanged in the 10.6.0 source. ABP 10.6 does change HttpContextAbpAccessTokenProvider to test HttpContext.User.Identity.IsAuthenticated directly. A separate ABP 10 issue affects forwarding an incoming client principal's bearer token; that produces a downstream 401 and is not this missing-user-token failure.

How to Verify It Worked

First verify the diagnosis without changing production state:

1. Correlate one web request with its API request.
2. On the web tier, record whether ICurrentUser.IsAuthenticated is true and whether GetTokenAsync("access_token") returned a value. Do not record the value.
3. On the API tier, classify the principal as user, client, or anonymous from claims. Alert when a user-facing endpoint receives a client principal.

Then reproduce in a non-production tiered application. Sign in, re-issue the local authentication ticket without the access_token in its AuthenticationProperties, and request a permission-guarded page.

Before the change, the API receives a client token when an IdentityClients entry is configured, and the UI can render an empty permission map. After the change, the page middleware initiates one OIDC round-trip. If recovery is bypassed, the strict authenticator sends no bearer token and the protected API returns 401; it never receives the application's client identity for that user request.

Add a counter to the "Blocked identity-client fallback" event. Its healthy steady-state value is zero. A non-zero value means the guard worked and the separate token-storage investigation still has work to do.

Finally, keep a regression test around the decision table:

| Current user | Current token | Expected result | |---|---|---| | Authenticated | Present | Send the user token | | Authenticated | Missing | Do not acquire an identity-client token | | Not authenticated | Missing | Preserve identity-client authentication | | Any | UseCurrentAccessToken = false | Preserve identity-client authentication |

Scope and Caveats

This is for server-rendered tiered MVC or Razor Pages hosts using Volo.Abp.Http.Client.IdentityModel.Web. Blazor WebAssembly has a different authenticator and token-provider model.

The guard assumes user-facing API endpoints require authentication. An anonymous endpoint can still accept the no-token request, so endpoints whose output is user-specific must remain protected.

Most importantly, this is containment, not root-cause repair. Once the silent fallback is blocked, investigate why an authenticated ticket can exist without its access token. Check SaveTokens, cookie or ticket-store persistence, token refresh, Data Protection consistency across instances, and deployment timing. At larger scale, prefer a durable server-side ticket store over growing authentication cookies, but treat the store as security-sensitive infrastructure.

References

• ABP dynamic C# client proxies
• ABP IdentityModel Clients
• ABP 10.5.0 HttpContextIdentityModelRemoteServiceHttpClientAuthenticator source
• ABP 10.5.0 IdentityModelRemoteServiceHttpClientAuthenticator source
• ABP support explanation of MVC/Razor remote-service authentication
• ABP support: a different cause of empty application configuration
• ABP 10 token-forwarding regression for client principals
• Microsoft: RemoteAuthenticationOptions.SaveTokens
• Microsoft: GetTokenAsync
• Microsoft: ASP.NET Core authentication overview

About the Author

Kori Francis

CTO at Clinical Support Systems, working on production .NET and ABP Framework systems.

How I Use a Custom AI Skill to Upgrade a Large ABP Solution 🧭

TL;DR: I created a project-specific AI skill that treats an ABP upgrade as a complete engineering workflow—not merely a package update. It inventories the current solution, creates recovery points, applies the upgrade, resolves known breaking changes, validates the result, and records new lessons for the next upgrade.

Introduction

Upgrading a small application can be as simple as changing a few package versions and rebuilding. Upgrading a mature ABP solution is different.

My solution contains custom ABP service replacements, Entity Framework Core migrations, NuGet and npm dependencies, authentication, Redis, background processing, multiple user interfaces, and production-specific integrations. A framework upgrade can affect any of those areas. More importantly, a successful compilation does not prove that authentication, billing, localization, caching, or database behavior still works.

I wanted my coding agent to understand that wider context every time I asked it to perform an upgrade. Repeating a large prompt from memory was unreliable, so I captured the workflow in a custom skill. You can call yours anything; the reusable example included with this article is named upgrade-abp-solution.

The skill gives the agent:

• A repeatable upgrade process
• Project-specific validation requirements
• PowerShell helpers for inventory, backup, and verification
• References for migration and namespace changes
• A durable log of problems encountered in previous upgrades
• An explicit rollback path

This article explains how the skill is structured, how I use it, and why the most valuable part is not the automation—it is the memory the workflow builds over time.

Why abp update Is Only One Step

The ABP CLI does a useful job of updating ABP-related dependencies:

abp update --version 10.5.0

However, an update command cannot answer solution-specific questions such as:

• Do custom classes still match constructors in ABP base classes?
• Has an implemented ABP interface gained a new member?
• Does the new ABP version require an EF Core migration?
• Are directly pinned packages now downgrading transitive dependencies?
• Is the LeptonX version line different from the main ABP version?
• Did a cached value become incompatible with the new application?
• Do login, two-factor authentication, password reset, and token flows still behave correctly?
• Can the solution be restored if a generated migration is unsafe?

My skill therefore treats abp update as an implementation detail inside a larger process:

Inspect → Protect → Research → Update → Compile → Migrate → Validate → Learn

That change in perspective matters. The goal is not to make package files say the new version. The goal is to move the entire solution to the new version with evidence that it remains safe to ship.

The Anatomy of the Skill

The skill is deliberately small enough to inspect and maintain:

upgrade-abp-solution/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── encountered-issues.md
│   └── migration-checklist.md
└── scripts/
    ├── Get-AbpInventory.ps1
    ├── New-PreUpgradeSnapshot.ps1
    └── Test-AbpUpgrade.ps1

Each part has a distinct responsibility.

You can browse or copy the complete sample upgrade-abp-solution skill included with this article. It is generic and has no dependencies on my solution.

SKILL.md: The Operating Procedure

SKILL.md is the entry point. Its description tells the agent when the skill applies, while its body describes the ordered workflow.

At a high level, the instructions require the agent to:

1. Review problems from earlier upgrades.
2. Back up the database and create a Git recovery point.
3. Identify the current and target versions.
4. Read the applicable migration guidance.
5. Update the ABP CLI and solution dependencies.
6. Update the .NET SDK and target frameworks when required.
7. Restore and compile before touching the database.
8. Generate and manually review EF Core migrations.
9. Run automated and application-level validation.
10. Add newly discovered issues to the knowledge log.

The ordering is intentional. For example, generating a migration before resolving all compilation errors produces noise rather than useful evidence. Likewise, an upgrade should not begin until the recovery path is known.

references/migration-checklist.md: The Stable Checklist

The migration checklist contains the things I want checked on every upgrade:

• Git and database recovery points
• ABP and .NET version alignment
• Official migration guidance
• NuGet restore and full-solution compilation
• EF Core migration review
• Unit and integration tests
• Authentication and CRUD smoke tests
• Redis and deployment configuration

It also groups recurring problems by area: Entity Framework Core, authorization, localization, caching, background jobs, and ABP system tables.

This file represents stable knowledge. It changes occasionally as the architecture evolves, but it is not rewritten for every upgrade.

Migration References: Fast Triage for Compile Errors

Framework upgrades frequently move types, add async APIs, or change module contracts. The migration checklist and encountered-issues log provide focused places to capture those changes and search patterns.

When the build reports a missing type, the skill directs the agent to:

1. Search the current ABP source for the type.
2. Read the migration guide for the target version.
3. Determine whether the type moved, its package was split, or its API was replaced.
4. Apply bulk edits only after confirming the correct replacement.

That sequence avoids a common failure mode: guessing a namespace that compiles but represents the wrong abstraction.

references/encountered-issues.md: The Compounding Asset

The issue log is the part I value most. After every upgrade, the agent records:

• Source and target versions
• The exact error or symptom
• The solution that worked
• Relevant files
• Time spent
• Runtime concerns to retest
• Advice for the next upgrade

This converts one-off debugging into reusable operational knowledge.

For example, the log now knows that:

• Visual Studio can lock project files while abp update is running.
• A failing ABP CLI discovery step may justify a controlled manual package bump.
• Custom implementations of ABP base classes and interfaces deserve early attention.
• Direct dependency pins can become downgrade errors after transitive requirements move.
• LeptonX can follow a different version line from the main ABP packages.
• A green build does not resolve a test process that hangs after the test runner starts.

The next upgrade begins with those lessons already in context.

The Three Helper Scripts

The scripts turn repetitive checks into consistent evidence. They do not replace engineering judgment; they make it easier to apply that judgment to the right information.

1. Inventory the Current State

Get-AbpInventory.ps1 scans the solution and reports:

• Resolved Volo.Abp, Volo.CmsKit, Volo.Docs, and Volo.Blogging packages
• The installed ABP CLI version
• The active .NET SDK
• Target frameworks found across project files

I can run it from the solution root:

.\scripts\Get-AbpInventory.ps1 -SolutionDir "D:\Projects\MySolution"

This provides a baseline before any file changes occur. It can also reveal version drift that was already present before the upgrade.

2. Create a Recovery Point

New-PreUpgradeSnapshot.ps1 records the state needed to understand or reverse the code-side upgrade:

.\scripts\New-PreUpgradeSnapshot.ps1 `
    -SolutionDir "D:\Projects\MySolution" `
    -OutputDir "D:\Backups\abp-upgrades"

The script:

• Warns about uncommitted changes
• Saves the current package list
• Copies central build and SDK configuration
• Records the current commit
• Creates a timestamped Git restore branch
• Writes restore instructions alongside the backup

It intentionally reminds me that the database backup is a separate operation. A Git branch can restore code; it cannot restore a database after a destructive migration.

3. Validate the Result

Test-AbpUpgrade.ps1 provides a repeatable first validation pass:

.\scripts\Test-AbpUpgrade.ps1 `
    -SolutionDir "D:\Projects\MySolution" `
    -Detailed

It checks:

• Whether the solution builds without restoring again
• Whether obsolete API warnings appeared
• Whether unit tests pass
• Whether ABP package versions are consistent
• Whether expected configuration files are present
• Whether EF Core migrations exist
• Whether known breaking-change patterns remain
• Whether deployment files may still reference an older .NET version

Warnings are deliberately distinct from failures. A warning means the script cannot prove something automatically; it does not mean the concern can be ignored.

For example, finding a migrations directory is not the same as proving the model is current. I still run an explicit drift check:

dotnet ef migrations has-pending-model-changes `
    --project src\MySolution.EntityFrameworkCore `
    --startup-project src\MySolution.DbMigrator

My End-to-End Upgrade Workflow

Here is how the skill guides an actual upgrade.

Phase 1: Preflight

First, the agent reads the issue log and applicable migration guidance. It inventories the current package graph, SDK, target frameworks, frontend packages, and explicit dependency pins.

It also identifies solution-specific risk areas before editing anything:

• ABP base classes that have been subclassed
• ABP interfaces implemented by custom infrastructure
• Replaced application services
• Custom DbContext interfaces
• Authentication and OpenIddict customization
• Custom event bus implementations
• Packages pinned to work around earlier vulnerabilities or incompatibilities

This produces a risk map for the upgrade rather than waiting for the compiler to discover everything.

Phase 2: Protection

The working tree must be understood and a restore point must exist. I back up the database separately, then run the pre-upgrade script.

The key question is simple:

If the package update or migration goes wrong, can I return both the code and the data to a known state?

If the answer is uncertain, the upgrade does not proceed.

Phase 3: Dependency Update

The preferred path is the ABP updater:

dotnet tool update -g Volo.Abp.Cli
abp update --version X.Y.Z

The skill still expects the result to be inspected. An updater may change the primary ABP packages while leaving:

• npm packages on another version
• lock files stale
• direct NuGet pins incompatible
• container or CI SDK versions unchanged

If the CLI cannot complete, the issue log contains a bounded fallback: update the relevant packages manually, refresh lock files, and let restore surface inconsistencies. The fallback is controlled and reviewable, not a blind search-and-replace across every version string.

Phase 4: Restore and Compile

The next gate is:

dotnet restore
dotnet build --no-restore

Restore failures and compile failures are treated as different classes of problem.

Restore commonly exposes:

• A package version that does not exist
• A direct package pin below a new transitive lower bound
• Mixed ABP versions
• An unreachable or slow package source

Compilation commonly exposes:

• New constructor dependencies in ABP base classes
• New interface members
• Changed override signatures
• Moved namespaces
• New DbSet requirements
• Changes to custom infrastructure contracts

Separating these stages keeps the diagnosis precise.

Phase 5: Database Migration

Only after the solution compiles does the workflow check for model changes:

dotnet ef migrations add Upgraded_To_Abp_X_Y `
    --project src\MySolution.EntityFrameworkCore `
    --startup-project src\MySolution.DbMigrator

The generated migration is reviewed like production code. I specifically look for:

• Dropped columns or tables
• Destructive type or length changes
• Unexpected modifications to ABP system tables
• Changes that conflict with custom mappings
• Provider-specific changes that do not apply to my database

An empty migration is removed. A dangerous migration is corrected or the upgrade is paused; it is never accepted simply because it was generated by a tool.

Phase 6: Validation

The automated validation script is only the first layer. The skill also calls for focused runtime checks:

• Application startup
• Login and logout
• Two-factor authentication and password reset
• Basic create, read, update, and delete operations
• Tenant switching, when applicable
• English and French localization
• Audit logging
• Redis serialization and cache behavior
• Background workers
• Critical business integrations

The exact list should reflect the solution. In my case, billing and external healthcare integrations deserve explicit checks because they are more important than a generic home-page smoke test.

Phase 7: Record What Was Learned

Finally, the agent adds new findings to encountered-issues.md.

This is not optional housekeeping. It closes the loop:

Previous upgrades inform this upgrade
             ↓
     A new issue is solved
             ↓
The solution is added to the skill
             ↓
 Future upgrades start smarter

Without this step, the skill is a static checklist. With it, the skill becomes a project-specific engineering memory.

Examples of Lessons That Paid Off

The upgrade log has already changed how later upgrades are performed.

Close Development Tools Before Updating

One upgrade produced confusing IOException failures because Visual Studio held project files open. The package changes mostly succeeded, leaving the solution in a partially updated state.

That experience became a preflight instruction: close Visual Studio before running the updater. A later upgrade avoided the problem entirely.

Do Not Spend Unlimited Time Fighting the Preferred Tool

During another upgrade, package discovery repeatedly timed out. The skill now recommends a time-bounded decision: try the CLI first, but move to a controlled manual bump when the failure is clearly environmental and repeatable.

This retains a preferred path without turning it into dogma.

Check Custom ABP Extension Points Early

Custom base-class overrides and interface implementations are frequent compile-break candidates because they mirror ABP contracts closely.

Past upgrades have required:

• Passing new dependencies to base constructors
• Implementing newly added interface methods
• Updating a custom event bus for string-based event contracts
• Adding a newly required identity DbSet

The skill now inspects those seams early rather than treating each error as an unrelated surprise.

Verify Behavior Even When There Are No Compile Breaks

One upgrade compiled cleanly and required no EF migration, but it introduced an identity token behavior change worth retesting. The build could not prove whether the application's login, two-factor, password-reset, and account-linking experiences still met expectations.

That lesson reinforces the central principle of the skill: compatibility includes behavior, not only APIs.

What the Skill Does Not Automate

I intentionally keep several decisions human-reviewed:

• Approving destructive database migrations
• Choosing when a failed updater should be replaced with a manual update
• Deciding whether package-version differences are legitimate
• Evaluating business-critical runtime workflows
• Clearing production caches or authentication data
• Deploying the upgraded solution

Commands such as flushing Redis or truncating OpenIddict tables can have serious operational consequences. They may be useful recovery options, but they should never run automatically merely because an upgrade occurred.

The skill makes these risks visible and supplies context. It does not remove ownership of the decision.

Design Principles for Your Own Upgrade Skill

If you want to build a similar skill for your ABP solution, I recommend the following principles.

Start with Your Architecture

Generic migration guidance is useful, but the skill becomes valuable when it knows your extension points, infrastructure, deployment model, and critical user journeys.

Separate Procedure, References, and Executable Checks

Keep the main skill concise. Put stable checklists and historical details in reference files, and put deterministic operations in scripts. This makes each layer easier to review.

Prefer Evidence-Producing Automation

A good helper script should answer a question:

• What versions are installed?
• Can I recover the previous state?
• Does the solution compile?
• Are package versions inconsistent?
• Is the EF Core model current?

Avoid automation whose only output is “done.”

Make Rollback Part of the Happy Path

Rollback planning should happen before the update, not after an error. Record the Git commit, create a restore branch, save dependency state, and back up the database.

Treat Warnings as Unproven Conditions

Not every check can be binary. A warning should clearly identify what still needs review and why automation could not settle it.

Update the Skill After Every Upgrade

The knowledge log is what gives the skill compounding returns. Record exact errors and proven solutions while they are fresh.

Summary

My custom ABP upgrade skill turns a risky, memory-driven maintenance task into a repeatable workflow:

• ✅ It inventories the full technology stack before changes begin.
• ✅ It creates code recovery points and requires a separate database backup.
• ✅ It combines official migration guidance with project-specific knowledge.
• ✅ It distinguishes dependency, compilation, schema, and runtime validation.
• ✅ It remembers real failures so future upgrades avoid the same traps.
• ✅ It keeps destructive and business-critical decisions under deliberate review.

The skill does not make framework upgrades effortless, and that is not the goal. It makes them explainable, recoverable, and progressively more predictable.

For a large ABP solution, that is a much more useful kind of automation.

References

• ABP Framework migration guides
• ABP Framework release notes
• ABP Framework source code
• EF Core migrations overview
• EF Core breaking changes

About the Author

Kori Francis
ABP Framework developer with experience building and operating large .NET solutions, cloud deployments, and project-specific AI engineering workflows.

Connect with me:

• 🐦 Twitter: @kfrancis
• 💼 LinkedIn: Kori Francis

Have you built a project-specific workflow for framework upgrades? I would be interested to hear which checks and lessons have saved your team the most time.

Tags: #ABPFramework #DotNet #AI #Automation #EntityFrameworkCore #PowerShell

Professional Email Delivery for ABP Applications with Postmark Integration 📧

TL;DR: Learn how to integrate Postmark - a premium transactional email service - into your ABP applications using the CommunityAbp.Emailing.Postmark module. Get superior deliverability, beautiful templates, and detailed analytics while maintaining ABP's standard email sending interface.

Introduction

Email delivery is critical for any modern application, yet many developers struggle with poor deliverability, spam issues, and complex template management. While services like SendGrid dominate the market through volume, Postmark has carved out a reputation as the developer-friendly choice for transactional emails with exceptional deliverability rates.

In this article, you'll discover how to integrate Postmark into your ABP applications using a community-built module that leverages ABP's ExtraProperties system for advanced templating capabilities. You'll learn why Postmark might be a better choice than alternatives, and how to implement professional email delivery with minimal code changes.

What is Postmark?

Postmark is a transactional email delivery service built specifically for developers and product teams. Postmark provides a full 45 days of both message events and full content rendering to all accounts at no charge by default, unlike many competitors that charge extra for extended logging.

Key Postmark Advantages

Superior Deliverability: They achieved a remarkable delivery rate of 93.8%! One of the highest we have ever seen. Postmark consistently outperforms competitors in inbox placement.

Developer Experience: Trying out @postmarkapp for my next react app blog and wow they have much better dev. experience than @SendGrid. Very clear & step-by-step.

Speed: Password reset emails delivered by @postmarkapp arrive in gmail in 1 second (vs 64 seconds for SendGrid)

Focus on Transactional Email: Unlike SendGrid which tries to be everything to everyone, Postmark specializes exclusively in transactional emails (password resets, confirmations, receipts, notifications).

Postmark vs. Popular Alternatives

| Feature | Postmark | SendGrid | Mailgun | Amazon SES | |---------|----------|----------|---------|------------| | Primary Focus | Transactional only | Marketing + Transactional | Mixed | Infrastructure service | | Deliverability | 93.8% | Variable | Mixed reviews | Depends on configuration | | Developer Experience | Excellent | Complex | Good | Technical | | Setup Complexity | Simple | Moderate | Moderate | Complex | | Template Editor | Built-in + API | Built-in | Limited | None | | Log Retention | 45 days free | 3 days (30 days paid) | 3 days | Manual setup | | Support Quality | Consistently excellent | Variable by plan | Mixed | Enterprise only | | Pricing (10K emails) | $15/month | ~$15/month | $35/month | ~$1/month* |

*Amazon SES requires additional infrastructure costs

Why Choose Postmark?

Issues with missing emails and inconsistent deliverability results are the main reasons why senders are moving away from Mailgun—and we're proud to see that those who switch to Postmark see better, more reliable delivery.

Choose Postmark when you need:

• Reliable transactional emails that consistently reach inboxes
• Developer-friendly APIs with excellent documentation
• Built-in template management without external tools
• Superior support that actually helps solve problems
• Detailed analytics without additional cost

Prerequisites

Before implementing Postmark in your ABP application:

• [ ] ABP Framework 8.0+ application
• [ ] .NET 8+ SDK
• [ ] Postmark account with API key
• [ ] Basic understanding of ABP's email system
• [ ] (Optional) Postmark templates created

The CommunityAbp.Emailing.Postmark Module

The CommunityAbp.Emailing.Postmark module provides seamless integration between ABP Framework and Postmark, extending ABP's standard IEmailSender interface while adding support for advanced features like templated emails.

Key Features

• Drop-in replacement for ABP's default email sender
• Template support using Postmark's powerful template system
• ExtraProperties integration for passing complex template data
• Automatic fallback when Postmark is disabled
• Full compatibility with existing ABP email code

Installation and Setup

Step 1: Install the NuGet Package

Install the module into your ABP Domain project:

Install-Package CommunityAbp.Emailing.Postmark

Or using the .NET CLI:

dotnet add package CommunityAbp.Emailing.Postmark

Step 2: Add Module Dependency

Add the module dependency to your Domain module:

[DependsOn(typeof(AbpPostmarkModule))]
public class YourProjectDomainModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        var configuration = context.Services.GetConfiguration();
        
        // Configure Postmark options
        Configure<AbpPostmarkOptions>(options =>
        {
            options.UsePostmark = configuration.GetValue("Postmark:Enabled", false);
            options.ApiKey = configuration.GetValue("Postmark:ApiKey", string.Empty);
        });
    }
}

Step 3: Configuration

Add Postmark configuration to your appsettings.json:

{
  "Postmark": {
    "Enabled": true,
    "ApiKey": "your-postmark-server-api-token-here"
  }
}

Security Note: Store your API key securely using:

• Azure Key Vault for production
• User Secrets for development
• Environment variables for containers

# Development with User Secrets
dotnet user-secrets set "Postmark:ApiKey" "your-api-key-here"

Basic Usage

The beauty of this integration is that it requires zero changes to your existing email code. The module transparently replaces ABP's default email sender:

// Your existing ABP email code continues to work unchanged
public class OrderService : ApplicationService
{
    private readonly IEmailSender _emailSender;
    
    public OrderService(IEmailSender emailSender)
    {
        _emailSender = emailSender;
    }
    
    public async Task SendOrderConfirmationAsync(Order order)
    {
        // This automatically uses Postmark when enabled
        await _emailSender.SendAsync(
            to: order.CustomerEmail,
            subject: "Order Confirmation #" + order.OrderNumber,
            body: BuildOrderEmailBody(order)
        );
    }
}

Advanced Usage: Postmark Templates

Postmark's real power comes from its template system. Templates allow you to:

• Separate design from code - Designers manage templates in Postmark's editor
• Consistent branding - Reuse layouts across all emails
• Dynamic content - Inject variables and complex objects
• A/B testing - Test different template versions
• Localization - Create templates for different languages

Understanding Postmark Templates

Postmark templates use a simple variable syntax:

<!-- Template HTML -->
<h1>Welcome, {{name}}!</h1>
<p>Your order #{{order.number}} for {{order.total}} has been confirmed.</p>
<p>Shipping to: {{customer.address.street}}, {{customer.address.city}}</p>

Templates support:

• Simple variables: {{name}}, {{email}}
• Nested objects: {{order.total}}, {{customer.address.city}}
• Arrays: {{#each items}}{{name}} - {{price}}{{/each}}
• Conditionals: {{#if isVip}}VIP benefits apply{{/if}}

Creating Templates

You can create templates via:

1. Postmark Dashboard - Visual editor with preview
2. API - Programmatic template management
3. Template Management - Version control and deployment

Here's a sample welcome email template:

{
  "Name": "User Welcome",
  "Subject": "Welcome to {{company_name}}, {{user_name}}!",
  "HtmlBody": "
    <h1>Welcome {{user_name}}!</h1>
    <p>Thanks for joining {{company_name}}. Get started:</p>
    <ol>
      <li><a href='https://github.com/kfrancis/my-abp-articles/blob/main/articles/abp-postmark/{{setup_url}}'>Complete your profile</a></li>
      <li><a href='{{docs_url}}'>Read our getting started guide</a></li>
      <li><a href='{{support_url}}'>Contact support if you need help</a></li>
    </ol>
  ",
  "TextBody": "
    Welcome {{user_name}}!
    
    Thanks for joining {{company_name}}. Get started:
    1. Complete your profile: {{setup_url}}
    2. Read our guide: {{docs_url}}  
    3. Contact support: {{support_url}}
  ",
  "TemplateType": "Standard"
}

Using Templates with ABP ExtraProperties

The module leverages ABP's ExtraProperties system to pass template data to Postmark. This approach maintains clean separation between your business logic and email templates.

Step 1: Create Template Model

public class WelcomeEmailService : ApplicationService
{
    private readonly IEmailSender _emailSender;
    
    public WelcomeEmailService(IEmailSender emailSender)
    {
        _emailSender = emailSender;
    }
    
    public async Task SendWelcomeEmailAsync(User user, string companyName)
    {
        // Build template model with all required data
        var templateModel = new Dictionary<string, object?>
        {
            { "user_name", user.Name },
            { "user_email", user.Email },
            { "company_name", companyName },
            { "setup_url", "https://yourapp.com/setup" },
            { "docs_url", "https://yourapp.com/docs" },
            { "support_url", "https://yourapp.com/support" },
            { "account_created_date", user.CreationTime.ToString("MMMM dd, yyyy") }
        };
        
        // Create ExtraProperties with template information
        var extraProperties = new Dictionary<string, object?>
        {
            { AbpPostmarkConsts.PostmarkTemplateId, 34989179L }, // Your template ID
            { AbpPostmarkConsts.TemplateModel, templateModel }
        };
        
        // Send using template - subject and body are ignored when using templates
        await _emailSender.SendAsync(
            to: user.Email,
            subject: null, // Template defines subject
            body: null,    // Template defines body
            additionalEmailSendingArgs: new AdditionalEmailSendingArgs
            {
                ExtraProperties = new ExtraPropertyDictionary(extraProperties)
            }
        );
    }
}

Step 2: Complex Template Data

For more complex scenarios, you can pass nested objects and arrays:

public async Task SendOrderSummaryAsync(Order order)
{
    var templateModel = new Dictionary<string, object?>
    {
        { "order_number", order.Number },
        { "order_date", order.CreationTime.ToString("MMMM dd, yyyy") },
        { "total_amount", order.TotalAmount.ToString("C") },
        { "customer", new {
            name = order.Customer.Name,
            email = order.Customer.Email,
            address = new {
                street = order.ShippingAddress.Street,
                city = order.ShippingAddress.City,
                state = order.ShippingAddress.State,
                zip = order.ShippingAddress.ZipCode
            }
        }},
        { "items", order.Items.Select(item => new {
            name = item.Product.Name,
            quantity = item.Quantity,
            price = item.UnitPrice.ToString("C"),
            total = (item.Quantity * item.UnitPrice).ToString("C")
        }).ToList() },
        { "shipping_method", order.ShippingMethod },
        { "tracking_url", $"https://shipping.com/track/{order.TrackingNumber}" }
    };
    
    var extraProperties = new Dictionary<string, object?>
    {
        { AbpPostmarkConsts.PostmarkTemplateId, 87654321L }, // Order summary template
        { AbpPostmarkConsts.TemplateModel, templateModel }
    };
    
    await _emailSender.SendAsync(
        to: order.Customer.Email,
        subject: null,
        body: null,
        additionalEmailSendingArgs: new AdditionalEmailSendingArgs
        {
            ExtraProperties = new ExtraPropertyDictionary(extraProperties)
        }
    );
}

Template ID vs. Template Alias

You can reference templates by ID or alias:

// Using Template ID (numeric)
{ AbpPostmarkConsts.PostmarkTemplateId, 34989179L }

// Using Template Alias (string) - more maintainable
{ AbpPostmarkConsts.PostmarkTemplateAlias, "welcome-email-v2" }

Best Practice: Use template aliases in code for better maintainability. Template IDs change when you create new template versions, but aliases remain constant.

Real-World Implementation Example

E-Commerce Order Confirmation System

Here's a complete example of a professional order confirmation system:

public class OrderEmailService : DomainService
{
    private readonly IEmailSender _emailSender;
    private readonly IRepository<Order, Guid> _orderRepository;
    private readonly ISettingProvider _settingProvider;
    
    public OrderEmailService(
        IEmailSender emailSender,
        IRepository<Order, Guid> orderRepository,
        ISettingProvider settingProvider)
    {
        _emailSender = emailSender;
        _orderRepository = orderRepository;
        _settingProvider = settingProvider;
    }
    
    public async Task SendOrderConfirmationAsync(Guid orderId)
    {
        var order = await _orderRepository.GetAsync(orderId, includeDetails: true);
        var companyInfo = await GetCompanyInfoAsync();
        
        var templateModel = new Dictionary<string, object?>
        {
            // Order details
            { "order_number", order.Number },
            { "order_date", order.CreationTime.ToString("MMMM dd, yyyy") },
            { "subtotal", order.SubtotalAmount.ToString("C") },
            { "tax_amount", order.TaxAmount.ToString("C") },
            { "shipping_cost", order.ShippingCost.ToString("C") },
            { "total_amount", order.TotalAmount.ToString("C") },
            
            // Customer information
            { "customer_name", order.Customer.FullName },
            { "customer_email", order.Customer.Email },
            
            // Shipping details
            { "shipping_address", new {
                name = order.ShippingAddress.FullName,
                street1 = order.ShippingAddress.Street,
                street2 = order.ShippingAddress.Street2,
                city = order.ShippingAddress.City,
                state = order.ShippingAddress.State,
                zip = order.ShippingAddress.ZipCode,
                country = order.ShippingAddress.Country
            }},
            
            // Order items
            { "items", order.Items.Select(item => new {
                name = item.Product.Name,
                sku = item.Product.Sku,
                quantity = item.Quantity,
                unit_price = item.UnitPrice.ToString("C"),
                total_price = (item.Quantity * item.UnitPrice).ToString("C"),
                image_url = item.Product.ImageUrl
            }).ToList() },
            
            // Company information
            { "company_name", companyInfo.Name },
            { "company_address", companyInfo.Address },
            { "support_email", companyInfo.SupportEmail },
            { "support_phone", companyInfo.SupportPhone },
            
            // Action URLs
            { "order_status_url", $"{companyInfo.BaseUrl}/orders/{order.Number}" },
            { "account_url", $"{companyInfo.BaseUrl}/account" },
            
            // Estimated delivery
            { "estimated_delivery", order.EstimatedDeliveryDate?.ToString("MMMM dd, yyyy") }
        };
        
        var extraProperties = new Dictionary<string, object?>
        {
            { AbpPostmarkConsts.PostmarkTemplateAlias, "order-confirmation" },
            { AbpPostmarkConsts.TemplateModel, templateModel }
        };
        
        await _emailSender.SendAsync(
            to: order.Customer.Email,
            subject: null, // Template defines: "Order Confirmation #{{order_number}}"
            body: null,
            additionalEmailSendingArgs: new AdditionalEmailSendingArgs
            {
                ExtraProperties = new ExtraPropertyDictionary(extraProperties)
            }
        );
    }
    
    private async Task<CompanyInfo> GetCompanyInfoAsync()
    {
        return new CompanyInfo
        {
            Name = await _settingProvider.GetOrNullAsync("Company.Name"),
            Address = await _settingProvider.GetOrNullAsync("Company.Address"),
            SupportEmail = await _settingProvider.GetOrNullAsync("Company.SupportEmail"),
            SupportPhone = await _settingProvider.GetOrNullAsync("Company.SupportPhone"),
            BaseUrl = await _settingProvider.GetOrNullAsync("Company.BaseUrl")
        };
    }
}

Integration with ABP Features

Multi-Tenancy Support

The module automatically handles multi-tenancy:

public class TenantEmailService : ApplicationService
{
    public async Task SendTenantWelcomeAsync(Tenant tenant, User user)
    {
        var templateModel = new Dictionary<string, object?>
        {
            { "user_name", user.Name },
            { "tenant_name", tenant.Name },
            { "tenant_url", $"https://{tenant.Name}.yourapp.com" }
        };
        
        // Template automatically uses tenant-specific settings
        await _emailSender.SendAsync(
            to: user.Email,
            subject: null,
            body: null,
            additionalEmailSendingArgs: new AdditionalEmailSendingArgs
            {
                ExtraProperties = new ExtraPropertyDictionary(new Dictionary<string, object?>
                {
                    { AbpPostmarkConsts.PostmarkTemplateAlias, "tenant-welcome" },
                    { AbpPostmarkConsts.TemplateModel, templateModel }
                })
            }
        );
    }
}

Background Jobs Integration

For high-volume email sending, integrate with ABP's background job system:

public class SendTemplatedEmailJob : AsyncBackgroundJob<SendTemplatedEmailArgs>, ITransientDependency
{
    private readonly IEmailSender _emailSender;
    
    public SendTemplatedEmailJob(IEmailSender emailSender)
    {
        _emailSender = emailSender;
    }
    
    public override async Task ExecuteAsync(SendTemplatedEmailArgs args)
    {
        var extraProperties = new Dictionary<string, object?>
        {
            { AbpPostmarkConsts.PostmarkTemplateAlias, args.TemplateAlias },
            { AbpPostmarkConsts.TemplateModel, args.TemplateModel }
        };
        
        await _emailSender.SendAsync(
            to: args.ToEmail,
            subject: null,
            body: null,
            additionalEmailSendingArgs: new AdditionalEmailSendingArgs
            {
                ExtraProperties = new ExtraPropertyDictionary(extraProperties)
            }
        );
    }
}

// Usage
public class OrderService : ApplicationService
{
    private readonly IBackgroundJobManager _backgroundJobManager;
    
    public async Task CompleteOrderAsync(Guid orderId)
    {
        // Process order...
        
        // Queue email to be sent in background
        await _backgroundJobManager.EnqueueAsync(new SendTemplatedEmailArgs
        {
            ToEmail = order.Customer.Email,
            TemplateAlias = "order-confirmation",
            TemplateModel = BuildOrderTemplateModel(order)
        });
    }
}

Configuration Options

Advanced Configuration

Configure<AbpPostmarkOptions>(options =>
{
    options.UsePostmark = true;
    options.ApiKey = configuration["Postmark:ApiKey"];
    
    // Optional: Configure additional Postmark client options
    options.PostmarkClientOptions = new PostmarkClientOptions
    {
        ApiToken = configuration["Postmark:ApiKey"],
        RequestTimeout = TimeSpan.FromSeconds(30),
        ApiUrl = "https://api.postmarkapp.com/" // Default value
    };
});

Environment-Specific Settings

{
  "Postmark": {
    "Enabled": true,
    "ApiKey": "your-production-api-key"
  }
}

// appsettings.Development.json
{
  "Postmark": {
    "Enabled": false,  // Use SMTP for development
    "ApiKey": "your-test-api-key"
  }
}

Testing and Development

Local Testing with Papercut

For local development without sending real emails, use Papercut SMTP:

// appsettings.Development.json
{
  "Postmark": {
    "Enabled": false  // Falls back to ABP's SMTP sender
  },
  "Settings": {
    "Abp.Mailing.Smtp.Host": "localhost",
    "Abp.Mailing.Smtp.Port": "25",
    "Abp.Mailing.DefaultFromAddress": "noreply@yourapp.com"
  }
}

Postmark Sandbox Mode

Postmark provides a sandbox mode for testing:

Configure<AbpPostmarkOptions>(options =>
{
    options.ApiKey = "POSTMARK_API_TEST"; // Special test token
    options.UsePostmark = true;
});

With the test token, emails are processed but not actually delivered, allowing safe testing of templates and integration.

Troubleshooting

Common Issues

Issue 1: Emails not sending

• Symptoms: No emails received, no error messages
• Solution: Check that Postmark:Enabled is true and API key is valid

// Add logging to verify configuration
public override void ConfigureServices(ServiceConfigurationContext context)
{
    var configuration = context.Services.GetConfiguration();
    var enabled = configuration.GetValue("Postmark:Enabled", false);
    var apiKey = configuration.GetValue("Postmark:ApiKey", string.Empty);
    
    Log.Information("Postmark Configuration - Enabled: {Enabled}, HasApiKey: {HasApiKey}", 
        enabled, !string.IsNullOrWhiteSpace(apiKey));
    
    Configure<AbpPostmarkOptions>(options =>
    {
        options.UsePostmark = enabled;
        options.ApiKey = apiKey;
    });
}

Issue 2: Template not found

• Error: "The template 'xyz' is not valid or was not found"
• Solution: Verify template ID/alias exists in your Postmark server

Issue 3: Template variables not rendering

• Symptoms: Emails show {{variable_name}} instead of values
• Solution: Check template model property names match template variables exactly

// Template uses: {{user_name}}
// Model must have: { "user_name", "John Doe" }
// NOT: { "userName", "John Doe" } or { "UserName", "John Doe" }

Best Practices

Template Management

• Use template aliases instead of IDs for better maintainability
• Version your templates (e.g., "welcome-email-v2") when making changes
• Test templates with sample data before deploying
• Keep templates in source control using Postmark's API

Performance Optimization

• Use background jobs for non-critical emails
• Batch template data preparation when sending multiple emails
• Cache company/system information used across templates
• Implement email preferences to reduce unnecessary sends

Security Considerations

• Store API keys securely (Key Vault, environment variables)
• Validate email addresses before sending
• Implement rate limiting for user-generated emails
• Use template aliases to prevent template ID enumeration

Monitoring and Analytics

Postmark provides detailed analytics out of the box:

• Delivery rates and bounce tracking
• Open and click tracking for engagement metrics
• 45-day message retention for debugging
• Real-time webhook notifications for delivery events
• Spam complaint monitoring

Access analytics via:

• Postmark Dashboard - Visual reports and graphs
• API endpoints - Programmatic access to stats
• Webhook integration - Real-time event notifications

Summary

You've successfully learned how to integrate professional email delivery into your ABP applications using Postmark:

• ✅ Superior deliverability compared to alternatives like SendGrid
• ✅ Template-based email system with dynamic content support
• ✅ ABP ExtraProperties integration for clean template data passing
• ✅ Zero changes to existing ABP email code required
• ✅ Professional email templates with consistent branding
• ✅ Detailed analytics and monitoring built-in

The CommunityAbp.Emailing.Postmark module provides a seamless bridge between ABP Framework and Postmark's professional email delivery platform, giving you enterprise-grade email capabilities without the complexity.

Next Steps

To further enhance your email system:

• Explore Postmark's webhook system for delivery tracking
• Implement email preference management for users
• Create automated email sequences using ABP background jobs
• Set up monitoring and alerting for email delivery issues
• Consider implementing A/B testing for email templates

References

• Postmark Developer Documentation
• Official Postmark .NET Client
• Postmark Templates API
• ABP Framework Email Documentation
• CommunityAbp.Emailing.Postmark Repository

Source Code

The complete CommunityAbp.Emailing.Postmark module source code is available on GitHub: https://github.com/Clinical-Support-Systems/CommunityAbp.Emailing.Postmark

About the Author

Kori Francis
ABP Framework developer with expertise in cloud deployments and .NET Aspire orchestration.

Connect with me:

• 🐦 Twitter: @kfrancis
• 💼 LinkedIn: Kori Francis

Community Projects:

• Password Autorization for Hangfire
• Postmark Integration for AspNetZero
• Postmark Integration for ABP
• ABP Diagnostics Logging
• WIP General Notifications for ABP

Found this solution helpful? Share it with your team! Have questions or improvements? Let's discuss in the comments below.

Tags: #ABPFramework #Postmark #Email #TransactionalEmail #Templates #Integration #DotNet

Universal Redis Configuration for ABP Applications with .NET Aspire Support 🚀

TL;DR: Learn how to configure Redis in ABP applications so they work seamlessly whether running standalone, with .NET Aspire orchestration, or deployed to Azure - all with a single, unified configuration approach.

Introduction

When building ABP applications with .NET Aspire support, one common challenge is making Redis configuration work across different scenarios: local development without Aspire, Aspire orchestration, and cloud deployments. The official ABP Aspire sample works great with Aspire, but breaks when you want to run your application standalone or deploy it to Azure.

In this article, you'll learn how to create a universal Redis configuration that automatically adapts to your deployment scenario, eliminating the need for environment-specific code changes.

The Problem

The official ABP Aspire sample demonstrates Redis integration that only works when using Aspire orchestration:

// From the official sample - only works with Aspire
builder.AddRedisClient("redis");

This approach has several limitations:

• ❌ Fails when running standalone - No Redis connection without Aspire
• ❌ Deployment complexity - Requires different configurations for different environments
• ❌ Azure deployment issues - Doesn't handle Azure Redis connection strings properly
• ❌ Developer friction - Forces developers to use Aspire even for simple local testing

Prerequisites

Before implementing this solution, ensure you have:

• [ ] ABP Framework 8.0+ application
• [ ] .NET 8+ SDK
• [ ] Basic understanding of ABP modules and configuration
• [ ] Redis server (local, containerized, or cloud-based)
• [ ] (Optional) .NET Aspire for orchestration

The Solution: Universal Redis Configuration

Step 1: Smart Redis Client Registration

First, let's modify the Program.cs to intelligently detect and register Redis based on available configuration:

// Program.cs - Smart Redis client registration
using Serilog;

var builder = WebApplication.CreateBuilder(args);

// Make Aspire Redis client optional. Only register if any supported configuration value is present.
var configuration = builder.Configuration;
var redisConn =
    configuration["Redis:Configuration"]
    ?? configuration["ConnectionStrings:redis"]
    ?? configuration["ConnectionStrings:Redis"]
    ?? configuration["Aspire:StackExchange:Redis:ConnectionString"]
    ?? Environment.GetEnvironmentVariable("ConnectionStrings__redis")
    ?? Environment.GetEnvironmentVariable("ConnectionStrings__Redis")
    ?? Environment.GetEnvironmentVariable("REDIS_CONNECTION")
    ?? Environment.GetEnvironmentVariable("REDIS_URL");

if (!string.IsNullOrWhiteSpace(redisConn))
{
    builder.AddRedisClient("redis", settings =>
    {
        settings.ConnectionString = redisConn;
    });
    Log.Information("Redis client registered with connection: {ConnectionHint}", 
        redisConn.Substring(0, Math.Min(20, redisConn.Length)) + "...");
}
else
{
    Log.Information("Redis connection not found in configuration. Skipping Aspire Redis client registration.");
}

// Continue with normal ABP application setup
await builder.AddApplicationAsync<YourWebModule>();
var app = builder.Build();
await app.InitializeApplicationAsync();
await app.RunAsync();

Step 2: Configuration Normalization in ABP Module

Next, update your web module's PreConfigureServices method to normalize Redis configuration:

// YourWebModule.cs
public override void PreConfigureServices(ServiceConfigurationContext context)
{
    var hostingEnvironment = context.Services.GetHostingEnvironment();
    var configuration = context.Services.GetConfiguration();
    
    // Normalize Redis configuration so ABP Redis modules rely on a single key: Redis:Configuration
    NormalizeRedisConfiguration(configuration);
    
    // ... other pre-configuration
}

private static void NormalizeRedisConfiguration(IConfiguration configuration)
{
    // If Redis:Configuration is already set, we're good to go
    if (!string.IsNullOrWhiteSpace(configuration["Redis:Configuration"]))
    {
        return;
    }

    // Fallback chain in priority order:
    // 1. ConnectionStrings:Redis / ConnectionStrings:redis (standard .NET / Azure / Aspire)
    // 2. Environment variables
    // 3. Legacy environment variable names
    var redisResolved =
        configuration["ConnectionStrings:Redis"]
        ?? configuration["ConnectionStrings:redis"]
        ?? Environment.GetEnvironmentVariable("ConnectionStrings__Redis")
        ?? Environment.GetEnvironmentVariable("ConnectionStrings__redis")
        ?? Environment.GetEnvironmentVariable("REDIS_CONNECTION")
        ?? Environment.GetEnvironmentVariable("REDIS_URL");

    if (!string.IsNullOrWhiteSpace(redisResolved))
    {
        // Set the unified key that ABP modules expect
        configuration["Redis:Configuration"] = redisResolved;
        
        Log.Information("Redis configuration normalized from fallback source");
    }
    else
    {
        Log.Warning("No Redis configuration found in any supported location");
    }
}

Configuration Examples for Different Scenarios

Scenario 1: Local Development (Standalone)

appsettings.Development.json:

{
  "ConnectionStrings": {
    "redis": "localhost:6379"
  }
}

Scenario 2: .NET Aspire Orchestration

appsettings.json (Aspire will inject the connection):

{
  "ConnectionStrings": {
    "redis": ""
  }
}

AppHost/Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.AddRedis("redis");

builder.AddProject<Projects.YourApp_Web>("webfrontend")
    .WithReference(redis);

builder.Build().Run();

Scenario 3: Azure Deployment

Azure App Service Configuration or appsettings.Production.json:

{
  "ConnectionStrings": {
    "Redis": "your-azure-redis.redis.cache.windows.net:6380,password=your-key,ssl=True"
  }
}

Scenario 4: Docker/Container Deployment

Environment Variables:

ConnectionStrings__Redis=redis-container:6379
# or
REDIS_CONNECTION=redis-container:6379
# or  
REDIS_URL=redis://redis-container:6379

Advanced Configuration Options

Custom Redis Configuration Class

For more complex scenarios, create a dedicated configuration class:

public class UniversalRedisOptions
{
    public const string SectionName = "UniversalRedis";
    
    public string ConnectionString { get; set; }
    public bool EnableAspireIntegration { get; set; } = true;
    public bool FailIfNotConfigured { get; set; } = false;
    public string[] FallbackSources { get; set; } = 
    {
        "Redis:Configuration",
        "ConnectionStrings:Redis",
        "ConnectionStrings:redis"
    };
}

Then register and use it:

public override void PreConfigureServices(ServiceConfigurationContext context)
{
    var configuration = context.Services.GetConfiguration();
    
    Configure<UniversalRedisOptions>(configuration.GetSection(UniversalRedisOptions.SectionName));
    
    var redisOptions = configuration.GetSection(UniversalRedisOptions.SectionName)
        .Get<UniversalRedisOptions>() ?? new UniversalRedisOptions();
        
    NormalizeRedisConfiguration(configuration, redisOptions);
}

Troubleshooting

Common Issues

Issue 1: Redis connection fails in standalone mode

• Symptoms: Application starts but Redis-dependent features don't work
• Cause: No Redis configuration found
• Solution: Verify one of the supported configuration keys is set

# Check your configuration
dotnet user-secrets list
# or check environment variables
printenv | grep -i redis

Issue 2: Aspire orchestration not working

• Error Message: "Unable to resolve service for type 'IConnectionMultiplexer'"
• Solution: Ensure the Redis service is properly referenced in your AppHost project

// In AppHost/Program.cs
var redis = builder.AddRedis("redis");
builder.AddProject<Projects.YourApp_Web>("webfrontend")
    .WithReference(redis); // ← This line is crucial

Issue 3: Azure deployment Redis SSL issues

• Error: SSL/TLS connection errors
• Solution: Ensure your Azure Redis connection string includes SSL settings

{
  "ConnectionStrings": {
    "Redis": "your-cache.redis.cache.windows.net:6380,password=key,ssl=True,abortConnect=False"
  }
}

Debug Logging

Add this to see which Redis configuration is being used:

public override void PreConfigureServices(ServiceConfigurationContext context)
{
    var configuration = context.Services.GetConfiguration();
    
    // Log all potential Redis configuration sources for debugging
    var sources = new Dictionary<string, string>
    {
        ["Redis:Configuration"] = configuration["Redis:Configuration"],
        ["ConnectionStrings:Redis"] = configuration["ConnectionStrings:Redis"], 
        ["ConnectionStrings:redis"] = configuration["ConnectionStrings:redis"],
        ["ENV ConnectionStrings__Redis"] = Environment.GetEnvironmentVariable("ConnectionStrings__Redis"),
        ["ENV REDIS_CONNECTION"] = Environment.GetEnvironmentVariable("REDIS_CONNECTION")
    };
    
    foreach (var (key, value) in sources.Where(s => !string.IsNullOrWhiteSpace(s.Value)))
    {
        Log.Information("Found Redis config source: {Source} = {Value}", key, 
            value.Substring(0, Math.Min(30, value.Length)) + "...");
    }
    
    NormalizeRedisConfiguration(configuration);
}

Best Practices

Performance Considerations

• Connection pooling: The unified approach maintains single connection pool across scenarios
• Startup time: Configuration normalization happens once during startup
• Memory usage: No additional overhead compared to standard ABP Redis usage

Security Best Practices

• Connection strings: Store Redis passwords in secure configuration (Key Vault, user secrets)
• SSL/TLS: Always use SSL in production environments
• Network security: Ensure Redis is not publicly accessible

{
  "ConnectionStrings": {
    "Redis": "your-cache.redis.cache.windows.net:6380,password={from-keyvault},ssl=True"
  }
}

Multi-Environment Configuration

Use configuration transformations for different environments:

// appsettings.json (base)
{
  "ConnectionStrings": {
    "redis": "localhost:6379"
  }
}

// appsettings.Production.json (override)
{
  "ConnectionStrings": {
    "Redis": "{will-be-set-by-deployment}"
  }
}

Real-World Example

E-Commerce Application Scenario

Imagine you're building an e-commerce ABP application that uses Redis for:

• Session storage
• Distributed caching
• SignalR backplane
• Rate limiting

With the universal configuration approach:

// Works in all scenarios without code changes
public class ProductCacheService : ITransientDependency
{
    private readonly IDistributedCache _cache;
    
    public ProductCacheService(IDistributedCache cache)
    {
        _cache = cache; // ABP automatically uses Redis when configured
    }
    
    public async Task<ProductDto> GetCachedProductAsync(Guid productId)
    {
        // This works whether Redis comes from:
        // - Local Redis instance
        // - Aspire orchestration  
        // - Azure Redis Cache
        // - Container deployment
        return await _cache.GetAsync<ProductDto>($"product:{productId}");
    }
}

Integration with ABP Features

Distributed Cache Integration

The universal Redis configuration automatically works with ABP's distributed caching:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var configuration = context.Services.GetConfiguration();
    
    // ABP automatically uses Redis when Redis:Configuration is set
    Configure<AbpDistributedCacheOptions>(options =>
    {
        options.KeyPrefix = "MyApp:";
        options.GlobalCacheEntryOptions.SlidingExpiration = TimeSpan.FromMinutes(20);
    });
}

SignalR Integration

public override void ConfigureServices(ServiceConfigurationContext context)
{
    context.Services.AddSignalR()
        .AddStackExchangeRedis(); // Uses the same Redis connection
}

Comparison with Official Sample

| Aspect | Official ABP Sample | Universal Configuration | |--------|-------------------|------------------------| | Aspire Support | ✅ Full support | ✅ Full support | | Standalone Running | ❌ Requires changes | ✅ Works out of box | | Azure Deployment | ❌ Manual configuration | ✅ Automatic detection | | Docker Deployment | ❌ Environment-specific | ✅ Environment variables | | Developer Experience | ⚠️ Context switching needed | ✅ Seamless across scenarios | | Configuration Complexity | ⚠️ Multiple approaches | ✅ Single unified approach |

Summary

You've successfully implemented a universal Redis configuration for ABP applications that:

• ✅ Works with .NET Aspire orchestration - Full Aspire integration when available
• ✅ Supports standalone execution - No dependency on Aspire for local development
• ✅ Handles Azure deployments - Automatic detection of Azure Redis connection strings
• ✅ Supports containerized deployments - Environment variable configuration
• ✅ Maintains single codebase - No environment-specific code changes needed
• ✅ Follows ABP conventions - Uses standard Redis:Configuration key internally

This approach eliminates the friction between development, orchestration, and deployment scenarios while maintaining the full benefits of .NET Aspire when available.

Next Steps

To further enhance your ABP + Aspire setup:

• Implement similar patterns for other services (databases, message queues)
• Add health checks for Redis connectivity
• Explore ABP's distributed event bus with Redis
• Consider implementing Redis Sentinel for high availability

References

• ABP Framework Redis Integration
• .NET Aspire Redis Component
• Official ABP Aspire Sample
• ABP Distributed Caching

About the Author

Kori Francis
ABP Framework developer with expertise in cloud deployments and .NET Aspire orchestration.

Connect with me:

• 🐦 Twitter: @kfrancis
• 💼 LinkedIn: Kori Francis

Community Projects:

• Password Autorization for Hangfire
• Postmark Integration for AspNetZero
• Postmark Integration for ABP
• ABP Diagnostics Logging
• WIP General Notifications for ABP

Found this solution helpful? Share it with your team! Have questions or improvements? Let's discuss in the comments below.

Tags: #ABPFramework #NETAspire #Redis #Configuration #Deployment #BestPractices

Introduction

ABP comes with a WPF template now, but it's a minimal example and doesn't include implementation within a solution nor testing. That's what we'll be discussing in this article.

Creating the solution

If you already have a project, you can skip this section.

To begin, start by creating a solution using abp new Acme.BookStore. This will create the initial setup, including the tiered layers and the base testing projects we'll need later.

Next, we'll want to create a new solution (somewhere else) using the WPF template by running abp new Acme.BookStore.Wpf -t wpf. When that's complete, move the Acme.BookStore.Wpf into your full solution. It should look like this:

Setting up the Wpf project

First, you need to add project references to the *.Application and *.EntityFrameworkCore projects. That'll allow this app to interact with the system.

Second, modify the *Module.cs class and add the Application and EntityFrameworkCore modules as dependencies for this module, like so:

[DependsOn(typeof(AbpAutofacModule),
    typeof(BookStoreApplicationModule),                          // <<- add
    typeof(BookStoreEntityFrameworkCoreModule))]                 // <<- add
public class BookStoreWpfModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure<AbpAuditingOptions>(options => options.IsEnabled = false);
        Configure<AbpBackgroundJobOptions>(options => options.IsJobExecutionEnabled = BackgroundJobConsts.IsEnabled);
        Configure<AbpBackgroundWorkerOptions>(options => options.IsEnabled = BackgroundJobConsts.IsEnabled);
    }
}

Creating the test project

Go ahead and open the test solution folder and create a new project. It should basically be a copy of the *.Web.Tests project but change Web to Wpf

The test project should reference the following packages:

• Microsoft.NET.Test.Sdk
• Abp.TestBase
• Volo.Abp.TestBase
• Shouldly
• xunit.runner.visualstudio
• Xunit.StaFact

The test project should reference the following solution projects:

• The *.Application.Tests project
• The *.Wpf app project

Next, we'll need to create the module and wpf test base classes.

Module Class

namespace Acme.BookStore;

[DependsOn(
    typeof(BookStoreWpfModule),
    typeof(BookStoreApplicationTestModule)
)]
public class BookStoreWpfTestModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {

    }

    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        ConfigureLocalizationServices(context.Services);
    }

    private static void ConfigureLocalizationServices(IServiceCollection services)
    {
        var cultures = new List<CultureInfo> { new CultureInfo("en"), new CultureInfo("tr") };
        services.Configure<RequestLocalizationOptions>(options =>
        {
            options.DefaultRequestCulture = new RequestCulture("en");
            options.SupportedCultures = cultures;
            options.SupportedUICultures = cultures;
        });

        services.Configure<AbpLocalizationOptions>(options =>
        {
            options.Resources
                .Get<BookStoreResource>()
                .AddBaseTypes(
                    typeof(AbpValidationResource),
                    typeof(AbpUiResource)
                );
        });
    }
}

The test base class that all tests will inherit.

public abstract class BookStoreWpfTestBase : BookStoreTestBase<BookStoreWpfTestModule>
{
    /// <summary>
    /// Shortcut for adding an NSubstitute.For a type and including the reference as a singleton
    /// </summary>
    /// <typeparam name="T">The interface to substitute</typeparam>
    /// <param name="backingStore">The local backing variable</param>
    /// <param name="services">The service collection to add the singleton to</param>
    public static void AddTestSubstitution<T>(ref T backingStore, IServiceCollection services)
        where T : class
    {
        backingStore = Substitute.For<T>();
        services.AddSingleton(backingStore);
    }
}

That should be all you need to start creating tests, however there are a few caveats.

1. Testing WPF requires special threading to be used, which is where the Xunit.StaFact package comes in (details) but mainly the only difference when writing tests is that you use [UIFact] instead of [Fact] and the package will handle running the tests on an STA thread with the context synchronized.
2. You're going to want to abstract the Dispatcher pretty quickly. In a WPF app, the dispatcher will be Application.Current.Dispatcher however you don't get access to that when running tests so do the following:

Dispatcher Abstraction

In the WPF app, implement the types you see I've done here including the WpfDispatcher which you'll use within the app to abstract to Application.Current.Dispatcher

Then, in your view models you can just inject IDispatcher dispatcher to run anything on the dispatcher.

In the test project, you can just implement a SimpleDispatcher which runs the code directly:

/// <summary>
/// A basic <see cref="IDispatcher"/> which simply runs the given code.
/// </summary>
public class SimpleDispatcher : IDispatcher, ISingletonDependency
{
    /// <inheritdoc/>
    public DispatcherType DispatcherType { get; }

    /// <summary>
    /// Creates a new <see cref="SimpleDispatcher"/> with the specified flags.
    /// </summary>
    /// <param name="dispatcherType">A set of <see cref="DispatcherType"/> flags indicating whether this <see cref="IDispatcher"/> manages special kinds of threads, which can (and should) be utilized in scenarios such as updating UI elements from code.</param>
    public SimpleDispatcher(DispatcherType dispatcherType = DispatcherType.Main)
    {
        DispatcherType = dispatcherType;
    }

    /// <inheritdoc/>
    public async Task RunAsync(Action execute)
    {
        execute();
    }

    /// <inheritdoc/>
    public async Task<T> RunAsync<T>(Func<T> execute)
    {
        return execute();
    }

    /// <inheritdoc/>
    public async Task RunAsync(Func<Task> execute)
    {
        await execute();
    }

    /// <inheritdoc/>
    public async Task<T> RunAsync<T>(Func<Task<T>> execute)
    {
        return await execute();
    }

    public void Run(Action execute)
    {
        execute();
    }
}

You can then create tests that look like the following:

public class MainWindow_Tests : BookStoreWpfTestBase
{
    private readonly ILoggerFactory _loggerFactory;
    private readonly IStringLocalizer<BookStoreResource> _localizer;
    private ISnackbarService _snackbarService;
    private ICurrentTenant _fakeCurrentTenant;
    private readonly IDispatcher _dispatcher;
    private MainWindowViewModel _viewModel;

    public MainWindow_Tests()
    {
        _loggerFactory = GetRequiredService<ILoggerFactory>();
        _localizer = GetRequiredService<IStringLocalizer<BookStoreResource>>();
        _snackbarService = GetRequiredService<ISnackbarService>();
        _fakeCurrentTenant = GetRequiredService<ICurrentTenant>();
        _dispatcher = GetRequiredService<IDispatcher>();
        _viewModel = new();
    }

    protected override void AfterAddApplication(IServiceCollection services)
    {
        AddTestSubstitution(ref _fakeCurrentTenant, services);
        AddTestSubstitution(ref _snackbarService, services);
    }

    private void GivenEmptyViewModel()
    {
        _viewModel = new MainWindowViewModel(_dispatcher, _loggerFactory, _localizer, _snackbarService);
    }

    [UIFact]
    public void CanInstantiate()
    {
        GivenEmptyViewModel();

        _viewModel.ShouldSatisfyAllConditions(
            vm => vm.ShouldNotBeNull(),
            vm => vm.IsBusy.ShouldBeFalse(),
            vm => vm.IsNotBusy.ShouldBeTrue()
        );
    }
}

MVVM Setup

I've approached this article and the accompanying sample with MVVM in mind, so in that regard I prefer to utilize the Refactored.MvvmHelpers as a sort of super light boilerplate reduction, in particular the BaseViewModel though to make it work a little easier here I'm going to be inheriting it and adding some of the AspNetZero mobile bits:

public abstract class AppViewModel : BaseViewModel, ITransientDependency
{
    private readonly ILogger<AppViewModel> _logger;
    private readonly IStringLocalizer<BookStoreResource> _localizer;

    public IStringLocalizer<BookStoreResource> L => _localizer;

    public List<IDispatcher> Dispatchers { get; }

    protected AppViewModel(ILogger<AppViewModel> logger, IStringLocalizer<BookStoreResource> localizer, IDispatcher dispatcher)
        : this()
    {
        _logger = logger;
        _localizer = localizer;

        Dispatchers = new List<IDispatcher> { dispatcher };
    }

    protected AppViewModel()
    {

    }

    public virtual async Task InitializeAsync(object navigationData)
    {
        await Task.FromResult(false);
    }

    public object GetPropertyValue(string propertyName)
    {
        return GetType().GetProperty(propertyName).GetValue(this, null);
    }

    public T GetPropertyValue<T>(string propertyName)
    {
        return (T)Convert.ChangeType(GetPropertyValue(propertyName), typeof(T));
    }

    public bool LogException(Exception ex, bool shouldCatch = false, bool shouldDisplay = false)
    {
        if (ex == null) return shouldCatch;

        _logger?.LogException(ex.Demystify());
        if (shouldDisplay)
        {
            //Dispatcher.CurrentDispatcher.Invoke(() =>
            //{
            //    _ = Task.Run(() => _dialogCoordinator.ShowMessageAsync(this, _localizer?["Error"] ?? "Error", (_localizer?["Failed"] ?? "Failed") + $": {ex.ToStringDemystified()}"));
            //});
        }

        return shouldCatch;
    }

    public async Task SetBusyAsync(Func<Task> func, string loadingMessage = null, bool showException = true)
    {
        IsBusy = true;
        try
        {
            await func();
        }
        catch (Exception ex) when (LogException(ex, true, showException))
        {
        }
        finally
        {
            IsBusy = false;
        }
    }
}

An example of a view model for a dialog might be something like this then:

public partial class BookDetailViewModel : AppViewModel
{
    private readonly Func<Task> _closeAction;

    public BookDetailViewModel()
        : base()
    {
        Title = nameof(BookDetailViewModel);
    }

    public BookDetailViewModel(ILogger<AppViewModel> logger,
                               IStringLocalizer<BookStoreResource> localizer,
                               IDispatcher dispatcher,
                               Func<Task> closeAction = null)
        : base(logger, localizer, dispatcher)
    {
        _closeAction = closeAction;
    }

    [ICommand]
    public async Task CloseAsync()
    {
        if (_closeAction != null)
        {
            await _closeAction();
        }
    }
}

I'm also using the CommunityToolkit.Mvvm to further reduce the need to write all the command code.

Code

The code for this article and project is available here: https://github.com/kfrancis/abp-wpf where you can see the app looks like this:

Introduction

Hi, in this step by step article, we will see how we can integrate the Telerik UI for ASP.NET Core (Kendo) components with our Abp MVC app.

Creating the Solution

ABP Framework offers startup templates to get into business faster.

In this article, I will create a new startup template with EF Core as a database provider and MVC for UI framework. But if you already have a project with MVC UI, you don't need to create a new startup template, you can directly implement the following steps to your existing project.

If you already have a project with the MVC UI, you can skip this section.

• Before starting to development, we will create a solution named TelerikComponents (or whatever you want). We will create a new startup template with EF Core as a database provider and MVC for UI framework by using ABP CLI:

abp new TelerikComponents --ui mvc --database-provider ef

• Our project boilerplate will be ready after the download is finished. Then, we can open the solution in the Visual Studio (or any other IDE) and run the TelerikComponents.DbMigrator to create the database and seed initial data (which creates the admin user, admin role, permissions, etc.). I prefer changing the db connection string in the DbMigrator project to (localdb)\\mssqllocaldb to be able to just run right away.

"ConnectionStrings": {
    "Default": "Server=(localdb)\\mssqllocaldb;Database=TelerikComponents;Trusted_Connection=True"
  },

• After the database and initial data created,
• Run the TelerikComponents.Web project to see our UI working.

Default login credentials for admin: username is admin and password is 1q2w3E*

Implementation

Pre-requisite

• First thing we need to do is downloading the Progress Control Panel to get Telerik Kendo components on our development machine.

• If you are using Telerik UI for ASP.NET Core components for the first time or you don't have an active license you can click here to download free trial.

You can find the more installation details from here.

Step 1 (Configuration)

• We need to install the Telerik.UI.for.AspNet.Core NuGet package to our web project (*.Web). We need to choose the Telerik feed package source to see the package.
• If you're using the trial, install Telerik.UI.for.AspNet.Core.Trial package via NuGet.

• In package.json, add the kendo script component as a dependency. This will get the scripts in your node_modules directory. A note, the npm package from Telerik needs to be transpiled to be able to be used so we're basically following their npm+webpack documentation here with a few adjustments for abp.io setup:

{
    {
        "version": "1.0.0",
        "name": "my-app",
        "private": true,
        "main": "main.js",
        "devDependencies": {
        "webpack": "^5.26.3",
        "webpack-cli": "^4.5.0"
        },
        "dependencies": {
        "@volo/abp.aspnetcore.mvc.ui.theme.lepton": "^4.2.2",
        "@volo/account": "^4.2.2",
        "@volo/audit-logging": "^4.2.2",
        "@volo/identity": "^4.2.2",
        "@volo/saas": "^4.2.2",
        "@progress/kendo-theme-bootstrap": "4.33.0",
        "@progress/kendo-ui": "2021.1.225",
        "css-loader": "^5.1.3",
        "expose-loader": "^2.0.0",
        "style-loader": "^2.0.0"
        },
        "scripts": {
        "build": "webpack"
        }
    }
}

Create a main.js in the root directory, this is what webpack will use to know what to include in the transpiled js bundle.

import $ from 'jquery';
window.jQuery = $; window.$ = $;

import "@progress/kendo-ui";
import "@progress/kendo-ui/js/kendo.aspnetmvc";
import "@progress/kendo-ui/js/kendo.timezones";
import "@progress/kendo-theme-bootstrap/dist/all.css";

Finally, add a webpack.config.js file to the root directory of your web project with the following content:

"use strict"
{
    const path = require('path');
    const webpack = require('webpack');

    module.exports = {
        entry: './main.js',
        output: {
            filename: 'kendo-bundle.js',
            path: path.resolve(__dirname, 'wwwroot/libs/kendo/dist')
        },
        module: {
            rules: [
                {
                    test: /\.css$/,
                    use: [{ loader: 'style-loader' }, { loader: 'css-loader' }]
                },
                {
                    test: /jquery.+\.js$/,
                    use: [{
                        loader: 'expose-loader',
                        options: 'jQuery'
                    }, {
                        loader: 'expose-loader',
                        options: '$'
                    }]
                }
            ]
        },
        externals: {
            jquery: 'jQuery'
        }
    }
}

What this will do is create a single js file that contains all of kendo, transpiled so you don't get 'module' errors. The use of expose-loader, externals jquery and the jquery rules are all there so that abp.io scripts, the way jquery is added and how kendo's js generally includes jquery doesn't conflict with each other.

• In the abp.resourcemapping.js file, add the necessary entries that look like the following:

module.exports = {
    aliases: {
    },
    mappings: {
        "@node_modules/@progress/kendo-ui/css/**/*": "@libs/kendo/css",
        "@node_modules/@progress/kendo-ui/js/**/*": "@libs/kendo/js"
    }
};

This will ensure the scripts and styles we need are packed up and in the right place for the next steps.

• Run yarn (to get the package)

• Run gulp (to execute the mapping)

• Run npm build (to execute the conversion of the js from Telerik into something usable here)

• In the TelerikComponents.Web project, under /Bundling, create a new directory we'll call Kendo- i.e. /Bundling/Kendo

• In /Bundling/Kendo, create the class file KendoScriptContributer.cs with the following content:

namespace TelerikComponents.Web.Bundling
{
    [DependsOn(
        typeof(JQueryScriptContributor)
        )]
    public class KendoScriptContributor : BundleContributor
    {
        public override void ConfigureBundle(BundleConfigurationContext context)
        {
            context.Files.AddIfNotContains("/libs/kendo/dist/kendo-bundle.js"); // This is the output of our webpack step
        }
    }
}

• In /Bundling/Kendo, create the class file KendoStyleContributer.cs with the following content:

namespace TelerikComponents.Web.Bundling
{
  public class KendoStyleContributor : BundleContributor
  {
      public override void ConfigureBundle(BundleConfigurationContext context)
      {
          context.Files.AddIfNotContains("/libs/kendo/css/web/kendo.common-bootstrap.min.css");
          context.Files.AddIfNotContains("/libs/kendo/css/web/kendo.bootstrap-v4.min.css");
      }
  }
}

• In the TelerikComponents.Web project, under /Components, create a new directory we'll call Kendo - i.e. /Components/Kendo
• Create a Default.cshtml with the following content:

@using TelerikComponents.Web.Bundling.Kendo 
@addTagHelper *, Volo.Abp.AspNetCore.Mvc.UI.Bundling

<!-- Kendo -->
<abp-script type="typeof(KendoScriptContributor)" />

• Create a KendoViewComponent.cs with the following content:

public class KendoViewComponent : AbpViewComponent
{
    public IViewComponentResult Invoke()
    {
        return View("/Components/Kendo/Default.cshtml");
    }
}

• In /Pages/_ViewImports.cshtml add the tag helper:

@using Kendo.Mvc.UI
@addTagHelper "*, Kendo.Mvc"

• Finally, in your TelerikComponentsWebModule.cs file - let's add the following bits:
  • In ConfigureServices, add ConfigureKendo(context.Services);. The method implementation looks simply like this:

private void ConfigureKendo(IServiceCollection services)
{
    services.AddKendo();
}

• Find the area Configure<AbpBundlingOptions> and after the Global add, also add our style contributor .AddContributors(typeof(KendoStyleContributor)):

Configure<AbpBundlingOptions>(options =>
{
    options
        .StyleBundles
        .Get(StandardBundles.Styles.Global)
        .AddContributors(typeof(KendoStyleContributor)); // add this
});

If you don't see this section, add it to ConfigureServices(). * Add a new configure to setup a layout hook, where we add the kendo scripts to the bottom of the page:

Configure<AbpLayoutHookOptions>(options =>
{
    options.Add(
        LayoutHooks.Head.Last, //The hook name
        typeof(KendoViewComponent) //The component to add
    );
});

Step 2 - Checking the Setup

If we've done everything right, then we should now be able to use the components. On any page, you should now be able to use either the tag helpers or razor syntax:

<kendo-numerictextbox name="currency" format="c" min="0"
      enable="true" max="100" value="30">
</kendo-numerictextbox>

@(Html.Kendo().NumericTextBox()
      .Name("currency")
      .Format("c")
      .Min(0) // Set the min value of the NumericTextBox.
      .Max(100) // Set the min value of the NumericTextBox.
      .Value(30) // Set the value of the NumericTextBox.
)

Done!