Requires .NET 11 and EF Core 11. Verified against EF Core 11.0.0-rc.1.26425.128.

A help center has a few thousand articles in SQL Server. Users type what went wrong in their own words — "login keeps timing out" — and the search returns nothing, because the article that answers them is titled "session expires too quickly" and shares no words with the query.

The usual fix is to put a vector database next to the application: pick one, sync the rows into it, keep the two stores consistent, and accept a second system to operate, back up, and secure. That is a lot of infrastructure for one feature, and the articles are already sitting in SQL Server.

SQL Server 2025 added a vector type, distance functions, and DiskANN vector indexes. EF Core 10 made the storage side usable from .NET. EF Core 11 adds the remaining query-side building blocks: approximate search over a vector index, full-text search table-valued functions, and translation for .NET 11's new FullJoin operator.

This article follows that help center from the first embedding to a working hybrid search, adding each feature at the point where the previous step stops being enough.

Storing Embeddings Next to the Articles

Add a SqlVector<float> property and specify how many dimensions the column holds. The dimension count is mandatory; leaving it out fails model validation.

public class Article
{
    public int Id { get; set; }
    public string Title { get; set; } = null!;
    public string Content { get; set; } = null!;

    [Column(TypeName = "vector(1536)")]
    public SqlVector<float> Embedding { get; set; }
}

Generating the embedding happens outside the database. Microsoft.Extensions.AI provides a provider-agnostic IEmbeddingGenerator<string, Embedding<float>>, so which model produces the vector stays a configuration decision:

IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator = /* your provider */;

article.Embedding = new SqlVector<float>(
    await embeddingGenerator.GenerateVectorAsync(article.Content));

await context.SaveChangesAsync();

The user's query goes through the same generator. That is not optional: distances are only meaningful between vectors from the same model, and a different dimension count will not fit the vector(1536) column at all.

Keeping the vectors in the same database removes the sync problem between two stores, but the embedding is still derived data with a lifecycle. Regenerate it whenever the source text changes, or the search keeps matching the old wording. Version the model and dimension count, because switching models means backfilling every row. And long articles usually need chunking rather than one vector for the whole Content.

var query = new SqlVector<float>(
    await embeddingGenerator.GenerateVectorAsync(queryText));

Searching by Meaning

With embeddings stored, the first working version of the search is an OrderBy on distance:

var hits = await context.Articles
    .OrderBy(a => EF.Functions.VectorDistance("cosine", a.Embedding, query))
    .Select(a => new { a.Id, a.Title })
    .Take(5)
    .ToListAsync();

SELECT TOP(@p) [a].[Id], [a].[Title]
FROM [Articles] AS [a]
ORDER BY VECTOR_DISTANCE('cosine', [a].[Embedding], @query)

This is exact k-nearest-neighbor search. Every row is compared, so it returns the true nearest neighbors for the chosen metric. "login keeps timing out" now finds "session expires too quickly", and the help center ships.

The supported metrics are cosine, euclidean, and dot. Cosine is common for text embeddings, but use whichever the model's documentation recommends, and note whether it expects normalized vectors.

This is also where a lot of applications stop. Exact search stays reasonable up to roughly 50,000 vectors — or any table size, as long as a WHERE clause narrows the candidates first — and it is all stable EF Core 10 API.

When the Scan Becomes the Bottleneck

The help center grows. Every search now computes a distance for every row, and the scan shows up in traces.

Vector indexes exist to avoid that. SQL Server uses DiskANN, a graph index built for vectors that do not fit in memory, and a search walks a small part of the graph instead of the whole table.

The trade-off is in the name: approximate nearest neighbor search can miss a true neighbor. That is usually acceptable for ranking, where a different item somewhere in the top-k changes nothing a user would notice — but it is worth measuring recall on your own corpus rather than assuming it.

Configure the index in the model:

modelBuilder.Entity<Article>()
    .HasVectorIndex(a => a.Embedding)
    .HasMetric("cosine")
    .HasType("DiskANN");

HasMetric is required, and the metric configured here must match the one passed at query time or the index is not used. A vector index also covers exactly one column.

Note that the second argument to HasVectorIndex is the index name, not the metric — the documentation currently passes "cosine" there. Written that way the index is called "cosine", no metric is set, and model validation fails.

Getting the Index Created at All

Deploying that index is harder than it looks. A vector index cannot be created on a table with fewer than 100 non-null vectors, and creating it too early fails with Msg 42266.

UseSeeding runs after the whole migration batch, so you cannot rely on it to prepare data for a later migration in the same update. Split the work into explicit ordered steps instead: create the table, write at least 100 non-null vectors with a data migration, then create the index in the migration after that.

Three more constraints are worth knowing before you design the deployment. The table must have a clustered primary key — and SQL Server 2025 is stricter than the limitations page reads: error 42217 asks for that key to be a single 4 byte INT column. Azure SQL Database, which carries the newer index version, accepted bigint and uniqueidentifier keys when I tried it, so this one is worth testing on your own target rather than assuming either way. TRUNCATE TABLE is blocked while a vector index exists. And vector indexes cannot be deployed through DacPac or BACPAC, because the import creates schema before loading data and therefore hits the 100-row rule — drop the index before exporting and recreate it after the import.

Querying the Index

var hits = await context.Articles
    .VectorSearch(a => a.Embedding, query, "cosine")
    .OrderBy(r => r.Distance)
    .Take(5)
    .WithApproximate()
    .ToListAsync();

SELECT TOP(@p1) WITH APPROXIMATE [a].[Id], [a].[Content], [a].[Title], [v].[Distance]
FROM VECTOR_SEARCH(
    TABLE = [Articles] AS [a],
    COLUMN = [Embedding],
    SIMILAR_TO = @p,
    METRIC = 'cosine'
) AS [v]
ORDER BY [v].[Distance]

VectorSearch() returns IQueryable<VectorSearchResult<T>>, which carries both the entity (Value) and the computed Distance. WithApproximate() must come after Take() — it is what turns TOP(n) into TOP(n) WITH APPROXIMATE. On the latest index version, a Where() placed before Take() is applied inside the search, so filters narrow the candidate set rather than trimming results afterwards.

The failure mode to guard against is forgetting WithApproximate(). On a platform that accepts the generated syntax at all — see the next section — the query still compiles, still runs, and still returns correct results, by scanning every row with the index unused. EF only warns in the log, so turn that warning into an error while developing:

options.UseSqlServer(connectionString)
    .ConfigureWarnings(w => w.Throw(SqlServerEventId.VectorSearchWithoutApproximateIndexWarning));

Where This Actually Runs

Before committing to that path, check that it runs on your target at all. The new approximate-search APIs — VectorSearch(), WithApproximate() and the vector index builder — carry [Experimental("EF9105")], so your code does not compile until the diagnostic is acknowledged with <NoWarn>$(NoWarn);EF9105</NoWarn>. VectorDistance(), FreeTextTable(), ContainsTable() and the full-text modelling APIs are not marked.

The attribute itself only affects compilation. What decides whether a query runs is the server product, its region, and the version of the vector index.

| Capability | SQL Server 2025 container 17.0.5005.3 | Azure SQL Database | |---|---|---| | vector column, SqlVector<float> | ✅ | ✅ | | EF.Functions.VectorDistance() | ✅ | ✅ | | CREATE VECTOR INDEX from a migration | ✅ | ✅ | | VectorSearch() + WithApproximate() | ❌ | ✅ | | Full-text search | ❌ not installed in the image | ✅ | | PREVIEW_FEATURES required for indexes and VECTOR_SEARCH | ✅ | ❌ |

The SQL Server 2025 column reports one tested build, the stock mcr.microsoft.com/mssql/server:2025-latest image. Full-text search is missing because that image does not ship the component, not because SQL Server 2025 lacks it.

On SQL Server 2025, CREATE VECTOR INDEX and VECTOR_SEARCH are documented as preview features that need the database scoped configuration turned on first:

ALTER DATABASE SCOPED CONFIGURATION SET PREVIEW_FEATURES = ON;

Azure SQL Database does not require it.

Even with that enabled, the generated query is rejected on the tested 17.0.5005.3 build with Incorrect syntax near 'APPROXIMATE'. Dropping WithApproximate() gives a more informative failure, Incorrect syntax near 'TOP_N', even though the generated SQL contains no TOP_N anywhere.

That build requires TOP_N inside the function call, which is the older calling convention:

SELECT TOP(3) t.Id, s.distance
FROM VECTOR_SEARCH(TABLE = Articles AS t, COLUMN = Embedding, SIMILAR_TO = @qv,
                   METRIC = 'cosine', TOP_N = 3) AS s
ORDER BY s.distance;

That form runs. The server supports approximate search; it speaks the older dialect, and EF generates only the newer one, with no compatibility switch. On Azure SQL Database — and on SQL database in Microsoft Fabric, which also carries the latest index version — the EF query runs unchanged.

The two index versions differ in behaviour, not only in syntax. On the older version the table becomes read-only once the index exists. ALLOW_STALE_VECTOR_INDEX lifts that on Azure SQL Database and SQL database in Microsoft Fabric, but that database scoped configuration does not exist on SQL Server 2025, so on the build tested here there is no way back to a writable table. WHERE predicates are also applied after retrieval rather than during it, so TOP_N has to be widened by hand to survive filtering. The iterative filtering described above belongs to the latest index version.

Two more environment notes. As of September 2026, Azure SQL Database vector search is live in North Europe and UK South only, so check region availability before planning around it. And SERVERPROPERTY('IsFullTextInstalled') returns 0 on mcr.microsoft.com/mssql/server:2025-latest, so full-text search needs a derived image that installs mssql-server-fts.

The Embeddings Come Back Empty

A bug report arrives: an admin edits an article's title, saves, and the search stops finding it — or a background job that re-reads embeddings gets nothing.

EF Core 11 excludes vector columns from the SELECT list by default when materializing entities:

SELECT TOP(@p) [a].[Id], [a].[Content], [a].[Title]
FROM [Articles] AS [a]
ORDER BY [a].[Id]

There is no [Embedding], and the property comes back with a length of zero even though every row has a value.

The reasoning is sound. A 1,536-dimensional float vector is 6 KB per row, and embeddings are written rarely and searched against constantly but almost never read back. In a minimal benchmark, Microsoft measured roughly a 9x throughput improvement locally from not shipping them over the wire, and 22x against a remote Azure SQL database.

Vectors still work in WHERE and ORDER BY. Reading one requires an explicit projection:

var embeddings = await context.Articles
    .Select(a => new { a.Id, a.Embedding })
    .ToListAsync();

So the title edit is safe: saving a tracked entity leaves the stored embedding untouched. That is correct here because the vector is generated from Content alone. The sample that ships with this article embeds the title as well, and there the same edit does leave a stale vector behind — which input feeds the embedding decides whether an edit invalidates it. What breaks is code that reads Embedding from a tracked entity: it gets an empty vector, and ordinary property access returns it without any warning. Check context.Entry(article).Property(a => a.Embedding).IsLoaded when it matters, or project the property explicitly.

Exact Terms Still Fail

The next complaint is different. Users searching for an error number, a plan name, or a specific setting get articles that are thematically close and factually wrong. Vector search finds meaning and misses precision — that is what it is for.

EF Core has translated EF.Functions.FreeText() and EF.Functions.Contains() for years, but those are predicates: they filter without ranking, which is no help when you need a merged ordering later. EF Core 11 adds the table-valued versions, which return SQL Server's relevance score:

var hits = await context.Articles
    .FreeTextTable<Article, int>("session expires too quickly", topN: 20)
    .Join(context.Articles, fts => fts.Key, a => a.Id, (fts, a) => new { a.Title, fts.Rank })
    .OrderByDescending(x => x.Rank)
    .ToListAsync();

FullTextSearchResult<TKey> exposes only Key and Rank, so the join back to the table is explicit, and both generic type arguments must be supplied explicitly because TKey cannot be inferred. ContainsTable() has the same shape but takes a search condition ("nebula OR quasar", NEAR, prefix terms) instead of free text.

The catalog and index can be configured in the model as of EF Core 11:

modelBuilder.HasFullTextCatalog("ftCatalog");

modelBuilder.Entity<Article>()
    .HasFullTextIndex(a => new { a.Title, a.Content })
    .UseKeyIndex("PK_Articles")
    .UseCatalog("ftCatalog");

UseKeyIndex has to name a unique, single-column, non-nullable index — SQL Server uses it as the full-text key, which is what FullTextSearchResult<TKey>.Key returns.

That configuration has a side effect in the table definition rather than the index. HasFullTextIndex is built on HasIndex, so EF applies its ordinary index key size limit to the string properties involved, and a Content property that should map to nvarchar(max) comes out as nvarchar(450) — truncating the column you most wanted to search. Set the column type explicitly to keep the full length:

modelBuilder.Entity<Article>()
    .Property(a => a.Content)
    .HasColumnType("nvarchar(max)");

One more thing that looks like a bug in tests: full-text population is asynchronous. In a 120-row sample it took about 20 seconds to become searchable after CREATE FULLTEXT INDEX, so a seed routine that queries immediately gets an empty result. Wait until the indexed row count catches up:

SELECT OBJECTPROPERTYEX(OBJECT_ID('Articles'), 'TableFulltextItemCount');

Give that loop an interval and a timeout, and check TableFulltextFailCount as well — rows that fail indexing never arrive, so waiting for the count to reach the table total can hang forever. The catalog-level FULLTEXTCATALOGPROPERTY('ftCatalog', 'PopulateStatus') is the more obvious check, but Microsoft has marked that property for removal and advises against polling it in a tight loop.

Merging the Two Rankings

Now the help center has two searches that each fail differently, and neither one alone is the product. They have to be merged.

The standard merge is Reciprocal Rank Fusion: each document scores 1 / (k + position) for every list it appears in, where k is a smoothing constant, and the scores are summed. With suitable parameters, a document that both retrievers rank moderately well can beat one that a single retriever ranks first.

Evaluating a fusion needs a corpus where the two retrievers disagree. The one used here has 120 documents, a query text of nebula quasar, and an astronomy query vector: 12 documents match on both sides, 24 are semantically on topic but share no query words, 12 are lexical false friends — dessert menu items named Nebula and Quasar, embedded in a cooking topic — and 72 are unrelated. That corpus, and the console probe that produced every measurement below, are in the sample repository: maliming/efcore11-vector-hybrid-search.

Each retriever on its own:

FreeTextTable    Deep sky survey 4 (484), 9 (447), 6 (269), 8 (269), 2 (189), …
VectorSearch     Observation log 26 (0.0112), 34 (0.0125), 18 (0.0134), 32 (0.0145), …

Both lists lead with one group each: full-text with documents the corpus makes match on both sides, vector search with the semantic-only ones. Neither puts a doubly-corroborated document first.

The Documented Single-Query Shape

The documentation builds the fusion as a single query, joining the two retrievers with .NET 11's FullJoin and computing the score in the projection. As observed on 11.0.0-rc.1.26425.128, that shape has three practical problems. Re-check the first two against GA before building on them.

The first stops the build. The sample compares vs == null, but VectorSearchResult<T> is a readonly struct, so that is CS0019. Projecting the vector side to a reference type first — .Select(r => new { Article = r.Value, r.Distance }) — fixes it.

The second is materialization. Once the fused score is computed in the projection, reading back a result set that contains rows matched on one side only throws InvalidOperationException: Nullable object must have a value.

Projecting the same entity and nullable scalars without that score expression works, so it is the fused projection that breaks rather than the full join itself.

The third is the score, and it is wrong in two separate ways.

It inverts the full-text ranking. SQL Server's RANK is higher-is-better, so feeding it into 1 / (k + Rank) gives the least relevant keyword matches the highest score. In the measured run, a document with RANK 119 scored above one with RANK 140.

It also turns vector membership into a flat bonus. Cosine distances sit near zero, so with the documented k of 20 the vector term is about 1 / 20 = 0.05 for anything in the vector list, while the entire full-text term spans roughly 0.002 to 0.007 across the ranks in this run. Simply appearing in the vector results is worth seven to twenty-five times more than any difference in keyword relevance.

Neither side uses rank positions, which is what RRF is defined over.

Fusing on Rank Positions

Fetching the two ranked lists separately and applying RRF in memory avoids all three:

const int candidateCount = 20;
const int rrfK = 60; // the constant from the original RRF paper

var lexical = await context.Articles
    .FreeTextTable<Article, int>(queryText, topN: candidateCount)
    .Join(context.Articles, fts => fts.Key, a => a.Id, (fts, a) => new { a.Id, a.Title, fts.Rank })
    .OrderByDescending(x => x.Rank)
    .ThenBy(x => x.Id)
    .ToListAsync();

var semantic = await context.Articles
    .OrderBy(a => EF.Functions.VectorDistance("cosine", a.Embedding, queryVector))
    .ThenBy(a => a.Id)
    .Select(a => new { a.Id, a.Title })
    .Take(candidateCount)
    .ToListAsync();

var lexicalPosition = lexical.Select((x, i) => (x.Id, Position: i + 1)).ToDictionary(x => x.Id, x => x.Position);
var semanticPosition = semantic.Select((x, i) => (x.Id, Position: i + 1)).ToDictionary(x => x.Id, x => x.Position);

var titles = lexical.Select(x => (x.Id, x.Title))
    .Concat(semantic.Select(x => (x.Id, x.Title)))
    .DistinctBy(x => x.Id)
    .ToDictionary(x => x.Id, x => x.Title);

var fused = titles.Keys
    .Select(id => new
    {
        Id = id,
        Title = titles[id],
        LexicalPosition = lexicalPosition.TryGetValue(id, out var l) ? l : (int?)null,
        SemanticPosition = semanticPosition.TryGetValue(id, out var s) ? s : (int?)null,
        Score = (lexicalPosition.TryGetValue(id, out var lp) ? 1.0 / (rrfK + lp) : 0.0)
              + (semanticPosition.TryGetValue(id, out var sp) ? 1.0 / (rrfK + sp) : 0.0)
    })
    .OrderByDescending(x => x.Score)
    .ThenBy(x => x.Id)
    .Take(10)
    .ToList();

The ThenBy calls matter at both levels. Full-text ranks tie often — two documents above share RANK 269 — and the positions those lists produce are what the score is built from, so an unstable input order moves the final score. Ties in the score itself are just as common: two pairs below land on exactly 0.01639 and 0.01613.

The semantic list here comes from VectorDistance(), which keeps the whole pipeline on stable API and runs on any SQL Server 2025 instance. On Azure SQL Database in a supported region, swap that one query for the indexed version and nothing else changes:

var semantic = await context.Articles
    .VectorSearch(a => a.Embedding, queryVector, "cosine")
    .OrderBy(r => r.Distance)
    .Take(candidateCount)
    .WithApproximate()
    .Select(r => new { r.Value.Id, r.Value.Title, r.Distance })
    .ToListAsync();

// VECTOR_SEARCH accepts a single ascending ordering on the distance, so the tie-break the
// exact query does in SQL has to happen here instead.
semantic = [.. semantic.OrderBy(x => x.Distance).ThenBy(x => x.Id)];

That last line is not decoration: VECTOR_SEARCH only takes one ordering key, so the approximate path cannot express the tie-break in SQL and has to apply it after the rows come back. Against this corpus both versions produce the same fused ranking, which is what you would hope for at 120 documents — the approximate path earns its keep at a scale where the exact scan hurts, not by changing the answer.

Two round trips instead of one, and the fusion itself is a dictionary lookup over at most 2 * candidateCount rows:

title                  lexical#  semantic#     score
Deep sky survey 8             4          5   0.03101
Deep sky survey 1             7         12   0.02881
Deep sky survey 10           10          9   0.02878
Deep sky survey 5             9         16   0.02765
Deep sky survey 3             8         19   0.02736
Deep sky survey 4             1          -   0.01639
Observation log 26            -          1   0.01639
Deep sky survey 9             2          -   0.01613
Observation log 34            -          2   0.01613
Deep sky survey 6             3          -   0.01587

Deep sky survey 8 is ranked 4th by keywords and 5th by vectors — first by neither — and wins outright because both retrievers agree on it.

That ordering is a parameter choice, not a universal truth. With rrfK = 60 and candidateCount = 20, the worst possible two-list score is 2 / (60 + 20) = 0.025 and the best possible one-list score is 1 / (60 + 1) = 0.0164, so anything both retrievers return outranks anything only one of them found. For the help center that pushes keyword-only false positives down — but it would push down a correct error number just as hard, if the vector side happened to miss it. When exact identifiers matter, lower rrfK, widen the candidate lists, or add an explicit boost for exact matches.

The companion web application in that same repository puts all three strategies on one page. It ships the help center corpus from the opening — 32 articles, a separate set from the 120 documents used for the measurements above:

The opening query behaves as described. Semantic search returns Session expires too quickly first — a title that shares no words with the query. Keyword search mixes in Sign in sheet export template — a reporting article about attendance sheets — and a billing article about declined cards. The fused list puts four authentication articles on top and drops both false friends below them. Session expires too quickly, which only the vector side found, lands at 8: the trade-off from the paragraph above, on this sample corpus.

Clicking a result expands it:

Came back with the entity: no is the earlier section made visible — loading the article never fetched its 1,536 floats, and the values in the panel come from a second query that projects the property explicitly.

What to Ship

Following that path end to end, the version worth deploying is smaller than the feature list suggests.

Store embeddings in a vector column and search with VectorDistance(). That API is stable, exact, runs on any SQL Server 2025 instance, and is fast enough for tens of thousands of candidate articles. Add a full-text index when exact terms matter, and fuse the two ranked lists on positions in application code. Both halves are non-experimental, and the fusion works with either vector retriever.

Reach for VectorSearch() and a vector index when profiling shows the scan is actually the bottleneck, and only on Azure SQL Database or SQL database in Microsoft Fabric in a region that supports it. Treat that path as preview on both sides.

Summary

EF Core 11 lets you build semantic, lexical, and hybrid search on SQL Server without a separate vector database. Start with exact search, add full-text search when exact terms matter, and use approximate search only when scale justifies its preview constraints. And remember that vector columns are no longer loaded by default when materializing entities.

References

• What's New in EF Core 11
• Vector search in the SQL Server EF Core Provider
• Full-text search in the SQL Server EF Core Provider
• Vector search and vector indexes in the SQL Database Engine
• VECTOR_SEARCH (Transact-SQL)
• CREATE VECTOR INDEX (Transact-SQL)
• Azure SQL Database feature availability by region
• Microsoft.Extensions.AI
• Sample code for this article — the web application and the measurement probe
• Reciprocal Rank Fusion outperforms Condorcet and individual rank learning methods — the original RRF paper

With ABP 10.5.0, new Blazor projects can now use MudBlazor (Material Design) as an alternative to the long-standing default, Blazorise (Bootstrap 5). Framework, themes (LeptonX / LeptonX Lite / Basic), modules, solution templates, ABP Studio, and ABP Suite all support both libraries side by side. The 10.5.0 packages are live on nuget.org.

Why add another Blazor UI library?

Blazorise has been ABP's default Blazor UI library for years and remains the default and is fully supported — existing Blazorise projects can keep moving at their own pace, and upgrading to 10.5.0 does not change anything for them.

We added MudBlazor because one Blazor UI choice cannot fit every team:

• Design language — Bootstrap and Material Design serve different audiences, and forcing a single choice does not fit every team
• Open-source preference — MudBlazor is MIT-licensed, which works well for teams that want an open-source frontend component stack without extra component-library licensing or compliance overhead
• Ecosystem fit — Material Design third-party components (charts, rich text editors, data visualization, and so on) tend to integrate more naturally with a MudBlazor project

For new projects you can start with MudBlazor right away. Existing Blazorise projects do not need to be rewritten just to switch UI libraries.

Who should consider MudBlazor?

• Teams that want the frontend component stack fully open source with no licensing to manage (individual developers, open-source community projects, education / learning settings)
• Organizations with internal third-party dependency or supply-chain compliance requirements that prefer MIT-licensed components
• New Blazor projects that want to start with Material Design
• Teams already comfortable with the MudBlazor ecosystem (charts, rich text, rich UI components)

What the MudBlazor option covers

Framework core

Volo.Abp.MudBlazorUI provides the MudBlazor implementation of ABP's UI service abstractions, so code written against IUiMessageService / IUiNotificationService / IUiPageProgressService runs unchanged in a MudBlazor project. Key building blocks:

• MudBlazorUiMessageService — Info / Success / Warn / Error / Confirm rendered through MudDialog
• MudBlazorUiNotificationService — toast notifications via MudSnackbar
• MudBlazorUiPageProgressService — top progress bar via MudProgressLinear
• AbpMudCrudPageBase<...> — the MudBlazor counterpart to Blazorise's AbpCrudPageBase
• AbpMudExtensibleDataGrid<TItem> — a MudDataGrid wrapper integrated with Object Extension and time-zone conversion
• UiMessageAlert / UiNotificationAlert / PageAlert — page-level alert and notification containers

Theming is split across three hosts — Blazor Server, WebAssembly, and MauiBlazor — each shipped with matching bundling contributors and modules that wire MudBlazor's JS and CSS into the ABP bundle system.

Three themes

• LeptonX MudBlazor
• LeptonX Lite MudBlazor
• Basic Theme MudBlazor

Each theme's layout adopts MudBlazor components such as MudAppBar, MudDrawer, MudNavLink, and MudMenu, while keeping the theme's original color palette, dim / light / system modes, and RTL support.

LeptonX rendered with MudBlazor

LeptonX Lite rendered with MudBlazor

Basic Theme rendered with MudBlazor

The LeptonX themes reuse the same lpx-* CSS classes across both UI libraries, so the overall information architecture, page layout, and theme experience stay consistent with the Blazorise version. Individual controls follow each UI library's own conventions.

The same LeptonX theme — MudBlazor on the left, Blazorise on the right

Module coverage

Open-source modules in abpframework/abp that ship with a MudBlazor implementation:

• Account
• Identity — Users / Roles / OUs / ClaimTypes
• Permission Management — parent/child permissions with MudTreeView and tri-state MudCheckBox
• Setting Management — grouped settings with MudTabs (including theme switching)
• Tenant Management
• Feature Management

Additional MudBlazor implementations available on the Pro side, for example:

• Identity Pro — extra management around Sessions, SecurityLogs, and more
• OpenIddict Pro — Application / Scope management
• Saas — Tenant / Edition management with a connection-string dialog
• Audit Logging — MudDataGrid with a detail MudDialog
• Language Management / Text Template Management
• File Management / Chat / CMS Kit Pro
• AI Management / GDPR / Payment, and more

Identity user management built on AbpMudExtensibleDataGrid

Permission Management uses MudTreeView and tri-state MudCheckBox for parent/child permissions

Saas module: tenant list with a "New tenant" dialog that includes connection-string editing

Component mapping at a glance

If you already know Blazorise, here are the most common mappings:

| Blazorise | MudBlazor | |-----------|-----------| | TextEdit @bind-Text | MudTextField @bind-Value | | Select / SelectItem | MudSelect / MudSelectItem | | DataGrid | MudDataGrid (wrapped by ABP as AbpMudExtensibleDataGrid) | | Modal Show()/Hide() | MudDialog ShowAsync()/CloseAsync() | | Validations | MudForm + built-in validation | | Row / Column ColumnSize.Is6 | MudGrid / MudItem xs="12" sm="6" | | Bootstrap Icons bi-* | Icons.Material.Filled.* |

A full mapping table with razor examples lives in the ABP Blazor UI documentation.

Supported Blazor project types

ABP's MudBlazor support covers the Blazor project types you can create and run directly:

• Blazor Server (-u blazor-server)
• Blazor WebAssembly (-u blazor)
• Blazor WebApp (-u blazor-webapp, including InteractiveAuto)

ABP Suite

ABP Suite detects the solution's UI library and generates the matching CRUD page automatically:

public partial class Books : AbpMudCrudPageBase<IBookAppService, BookDto, Guid, GetBookListInput, CreateUpdateBookDto>
{
    private MudDialog _createDialog;
    private MudForm _createFormRef;
}

The razor templates also split by UI library — Blazorise uses <DataGrid> + <Modal> + <Validations>, MudBlazor uses <MudDataGrid> + <MudDialog> + <MudForm>.

Choosing between Blazorise and MudBlazor

Both UI libraries are production-ready and neither is strictly better. Common factors:

• Familiarity — teams comfortable with Bootstrap tend to stay on Blazorise; teams comfortable with Material Design pick MudBlazor
• Design system — Bootstrap-style products lean toward Blazorise, Material Design products lean toward MudBlazor
• Ecosystem — existing Bootstrap component libraries or design assets fit Blazorise; Material Design third-party components fit MudBlazor more naturally
• Existing projects — keep maintaining live Blazorise projects as they are; if you want to try MudBlazor, start a new project with it
• Licensing — the two UI libraries have different license terms, so check each library's official license page before making a choice (Blazorise / MudBlazor)

Do not mix the two libraries within a single project — the choice is per solution, not per file.

Creating a MudBlazor project in ABP Studio

ABP Studio (recommended)

Open ABP Studio → New Solution → pick a template → in the UI configuration step, select Blazor UI library = MudBlazor. Everything else works the same as a Blazorise project. After Build & Run you land on a MudBlazor-styled application.

New Solution wizard: pick MudBlazor for the Blazor UI library

Studio Build & Run brings up a MudBlazor + LeptonX dashboard in the embedded browser

CLI

# Blazorise (default; --blazor-ui-library can be omitted)
abp new MyApp -u blazor

# MudBlazor
abp new MyApp -u blazor --blazor-ui-library mudblazor

# Tiered + WebApp + LeptonX + MudBlazor
abp new MyApp -t app --tiered -u blazor-webapp --blazor-ui-library mudblazor --theme leptonx

# Microservice + MudBlazor + Blazor Server
abp new MyApp -t microservice -u blazor-server --blazor-ui-library mudblazor

# Reusable Module + MudBlazor
abp new My.Module -t module -u blazor --blazor-ui-library mudblazor

Run abp new --help for the full option list.

Suite-generated MudBlazor CRUD pages are covered in the ABP Suite section above.

Try it out

abp new MyMudApp -u blazor-server --blazor-ui-library mudblazor --theme leptonx

Documentation:

• Forms & Validation (MudBlazor)
• LeptonX with MudBlazor
• Basic Theme MudBlazor variant
• Page Header (MudBlazor)

FAQ

I'm already using Blazorise — will upgrading to 10.5.0 break my project? No. Blazorise stays the default, and package paths, type names, and namespaces are fully compatible. Follow the standard ABP upgrade flow.

Can I use Blazorise and MudBlazor in the same project? We don't recommend it. The UI library is a project-level choice — themes, bundling, and module dependencies all switch with it. Mixing both within a single solution leads to bundle conflicts, duplicated layouts, and similar issues.

What about my custom razor pages? Your custom Razor pages are tied to the UI library they were built with, so switching libraries means rewriting those pages using the component mapping above. Template-generated pages and module-provided pages don't need to be touched.

Wrapping up

MudBlazor is now a first-class Blazor UI library in ABP. With 10.5.0 released, every related package, theme, template, Studio integration, and Suite generator is in place — you can try it out with a single abp new command.

If you hit a bug, have a suggestion, or want a particular module's MudBlazor UX prioritized, let us know via GitHub Issues or abp.io support.

References

• MudBlazor official site
• ABP Blazor UI documentation
• ABP LeptonX theme
• ABP Studio download

This feature is available since ABP 10.3.

ABP's Event Bus is a core infrastructure piece. The Local Event Bus handles in-process communication between services. The Distributed Event Bus handles cross-service communication over message brokers like RabbitMQ, Kafka, Azure Service Bus, and Rebus.

Both are fully type-safe — you define event types at compile time, register handlers via DI, and everything is wired up automatically. This works great, but it has one assumption: you know all your event types at compile time.

In practice, that assumption breaks down in several scenarios:

• You're building a plugin system where third-party modules register their own event types at runtime — you can't pre-define an IDistributedEventHandler<TEvent> for every possible plugin event
• Your system receives events from external systems (webhooks, IoT devices, partner APIs) where the event schema is defined by the external party, not by your codebase
• You're building a low-code platform where end users define event-driven workflows through a visual designer — the event names and payloads are entirely determined at runtime

ABP's Dynamic Events extend the existing IEventBus and IDistributedEventBus interfaces with string-based publishing and subscription. You can publish events by name, subscribe to events by name, and handle payloads without any compile-time type binding — all while coexisting seamlessly with the existing typed event system.

Publishing Events by Name

The most straightforward use case: publish an event using a string name and an arbitrary payload.

public class OrderAppService : ApplicationService
{
    private readonly IDistributedEventBus _eventBus;

    public OrderAppService(IDistributedEventBus eventBus)
    {
        _eventBus = eventBus;
    }

    public async Task PlaceOrderAsync(PlaceOrderInput input)
    {
        // Business logic...

        // Publish a dynamic event — no event class needed
        await _eventBus.PublishAsync(
            "OrderPlaced",
            new { OrderId = input.Id, CustomerEmail = input.Email }
        );
    }
}

The payload can be any serializable object — an anonymous type, a Dictionary<string, object>, or even an existing typed class. The event bus serializes the payload and sends it to the broker with the string name as the routing key.

What If a Typed Event Already Exists?

If the string name matches an existing typed event (via EventNameAttribute), the framework automatically converts the payload to the typed class and routes it through the typed pipeline. Both typed handlers and dynamic handlers are triggered.

[EventName("OrderPlaced")]
public class OrderPlacedEto
{
    public Guid OrderId { get; set; }
    public string CustomerEmail { get; set; }
}

// This handler will still receive the event, with auto-converted data
public class OrderEmailHandler : IDistributedEventHandler<OrderPlacedEto>
{
    public Task HandleEventAsync(OrderPlacedEto eventData)
    {
        // eventData.OrderId and eventData.CustomerEmail are populated
        return Task.CompletedTask;
    }
}

Publishing by name with new { OrderId = ..., CustomerEmail = ... } triggers this typed handler — the framework handles the serialization round-trip. This is especially useful for scenarios where a service needs to emit events without taking a dependency on the project that defines the event type.

Subscribing to Dynamic Events

Dynamic subscription lets you register event handlers at runtime, using a string event name.

The recommended approach is to use IocEventHandlerFactory, which is the same mechanism ABP uses internally for typed handlers. It creates a new DI scope for each event, resolves a fresh handler instance, calls HandleEventAsync, then disposes the scope — so the handler can use normal constructor injection without any manual scope management:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    context.Services.AddTransient<PartnerOrderHandler>();
}

public override void OnApplicationInitialization(
    ApplicationInitializationContext context)
{
    var eventBus = context.ServiceProvider
        .GetRequiredService<IDistributedEventBus>();
    var scopeFactory = context.ServiceProvider
        .GetRequiredService<IServiceScopeFactory>();

    // Subscribe to a dynamic event — no event class needed
    eventBus.Subscribe("PartnerOrderReceived",
        new IocEventHandlerFactory(scopeFactory, typeof(PartnerOrderHandler)));
}

The handler implements IDistributedEventHandler<DynamicEventData> and injects its dependencies normally:

public class PartnerOrderHandler : IDistributedEventHandler<DynamicEventData>
{
    private readonly IPartnerOrderProcessor _orderProcessor;

    public PartnerOrderHandler(IPartnerOrderProcessor orderProcessor)
    {
        _orderProcessor = orderProcessor;
    }

    public async Task HandleEventAsync(DynamicEventData eventData)
    {
        // eventData.EventName = "PartnerOrderReceived"
        // eventData.Data = the raw payload from the broker
        await _orderProcessor.ProcessAsync(eventData.EventName, eventData.Data);
    }
}

DynamicEventData is a simple POCO with two properties:

• EventName — the string name that identifies the event
• Data — the raw event data payload (the deserialized object from the broker)

Subscribe returns an IDisposable. Call Dispose() to unsubscribe the handler at runtime. For application-lifetime subscriptions, prefer module initialization (OnApplicationInitialization / OnApplicationInitializationAsync) over subscribing inside an application service.

Mixed Typed and Dynamic Handlers

Typed and dynamic handlers coexist naturally. When both are registered for the same event name, both are triggered — the framework automatically converts the data to the appropriate format for each handler.

var eventBus = context.ServiceProvider.GetRequiredService<IDistributedEventBus>();
var scopeFactory = context.ServiceProvider.GetRequiredService<IServiceScopeFactory>();

// Typed handler — receives OrderPlacedEto
eventBus.Subscribe<OrderPlacedEto, OrderEmailHandler>();

// Dynamic handler — receives DynamicEventData for the same event
eventBus.Subscribe("OrderPlaced",
    new IocEventHandlerFactory(scopeFactory, typeof(AuditLogHandler)));

When OrderPlacedEto is published (by type or by name), both handlers fire. The typed handler receives a fully deserialized OrderPlacedEto object. The dynamic handler receives a DynamicEventData wrapping the raw payload.

This enables a powerful pattern: the core business logic uses typed handlers for safety, while infrastructure concerns (auditing, logging, plugin hooks) use dynamic handlers for flexibility.

Outbox Support

Dynamic events go through the same outbox/inbox pipeline as typed events. If you have outbox configured, dynamic events benefit from the same reliability guarantees — they are stored in the outbox table within the same database transaction as your business data, then reliably delivered to the broker by the background worker.

No additional configuration is needed. The outbox works transparently for both typed and dynamic events:

// This dynamic event goes through the outbox if configured
using var uow = _unitOfWorkManager.Begin();
await _eventBus.PublishAsync(
    "OrderPlaced",
    new { OrderId = orderId },
    onUnitOfWorkComplete: true,
    useOutbox: true
);
await uow.CompleteAsync();

Local Event Bus

Dynamic events work on the local event bus too, not just the distributed bus. The API is the same:

var localEventBus = context.ServiceProvider
    .GetRequiredService<ILocalEventBus>();

// Subscribe dynamically
localEventBus.Subscribe("UserActivityTracked",
    new SingleInstanceHandlerFactory(
        new ActionEventHandler<DynamicEventData>(eventData =>
        {
            // Handle the event
            return Task.CompletedTask;
        })));

// Publish dynamically
await localEventBus.PublishAsync("UserActivityTracked", new
{
    UserId = currentUser.Id,
    Action = "PageView",
    Url = "/products/42"
});

Provider Support

Dynamic events work with all distributed event bus providers:

| Provider | Dynamic Subscribe | Dynamic Publish | |---|---|---| | LocalDistributedEventBus (default) | ✅ | ✅ | | RabbitMQ | ✅ | ✅ | | Kafka | ✅ | ✅ | | Rebus | ✅ | ✅ | | Azure Service Bus | ✅ | ✅ | | Dapr | ❌ | ❌ |

Dapr requires topic subscriptions to be declared at application startup and cannot add subscriptions at runtime. Calling Subscribe(string, ...) on the Dapr provider throws an AbpException.

Summary

IEventBus.PublishAsync(string, object) and IEventBus.Subscribe(string, handler) let you publish and subscribe to events by name at runtime — no compile-time types required. If the event name matches a typed event, the framework auto-converts the payload and triggers both typed and dynamic handlers. Dynamic events go through the same outbox/inbox pipeline as typed events, so reliability guarantees are preserved. This works across all providers except Dapr, and coexists seamlessly with the existing typed event system.

References

• Local Event Bus
• Distributed Event Bus
• RabbitMQ Integration
• Kafka Integration
• Dynamic Distributed Events Sample

This feature is available since ABP 10.3.

ABP's Background Jobs and Background Workers are two well-established infrastructure pieces. Background jobs handle fire-and-forget async tasks — sending emails, generating reports, processing orders. Background workers handle continuously running periodic tasks — syncing inventory, cleaning up expired data, pushing scheduled notifications.

This works great, but it has one assumption: you know all your job and worker types at compile time.

In practice, that assumption breaks down more often than you'd expect:

• You're building a plugin system where third-party plugins need to register their own background processing logic at runtime — you can't pre-define an IBackgroundJob<TArgs> implementation in the host project for every possible plugin
• Your system needs to execute background tasks based on external configuration (database, API responses) — the task types and parameters are entirely unknown at compile time
• Your multi-tenant SaaS platform needs different sync intervals for different tenants — some every 30 seconds, some every 5 minutes — and you need to adjust these without restarting the application
• You're building a low-code/no-code platform where end users define automation workflows through a visual designer, and those workflows need to run as background jobs or scheduled tasks — the job types and scheduling parameters are entirely determined by end users at runtime, unknowable to developers at compile time

ABP's Dynamic Background Jobs (IDynamicBackgroundJobManager) and Dynamic Background Workers (IDynamicBackgroundWorkerManager) are designed for exactly these scenarios. They let you register, enqueue, schedule, and manage background tasks by name at runtime, with no compile-time type binding required.

Dynamic Background Jobs

IDynamicBackgroundJobManager offers two usage patterns, covering different levels of runtime flexibility.

Enqueue an Existing Typed Job by Name

If you already have a typed background job (say, an EmailSendingJob registered via [BackgroundJobName("emails")]), you can enqueue it by name without referencing its args type:

public class OrderAppService : ApplicationService
{
    private readonly IDynamicBackgroundJobManager _dynamicJobManager;

    public OrderAppService(IDynamicBackgroundJobManager dynamicJobManager)
    {
        _dynamicJobManager = dynamicJobManager;
    }

    public async Task PlaceOrderAsync(PlaceOrderInput input)
    {
        // Business logic...

        // Enqueue a confirmation email — no reference to EmailSendingJobArgs needed
        await _dynamicJobManager.EnqueueAsync("emails", new
        {
            EmailAddress = input.CustomerEmail,
            Subject = "Order Confirmed",
            Body = $"Your order {input.OrderId} has been placed."
        });
    }
}

The framework looks up the typed job configuration by name, serializes the anonymous object, deserializes it into the correct args type, and feeds it through the standard typed job pipeline. The caller doesn't need to using any specific project namespace.

Register a Runtime Dynamic Handler

When you don't even have a job type — say a plugin decides at startup what processing logic to register — you can register a handler directly:

public override async Task OnApplicationInitializationAsync(
    ApplicationInitializationContext context)
{
    var dynamicJobManager = context.ServiceProvider
        .GetRequiredService<IDynamicBackgroundJobManager>();

    // A plugin registers its own processing logic at startup
    dynamicJobManager.RegisterHandler("SyncExternalCatalog", async (jobContext, ct) =>
    {
        using var doc = JsonDocument.Parse(jobContext.JsonData);
        var catalogUrl = doc.RootElement.GetProperty("url").GetString();

        var httpClient = jobContext.ServiceProvider
            .GetRequiredService<IHttpClientFactory>()
            .CreateClient();

        var catalog = await httpClient.GetStringAsync(catalogUrl, ct);
        // Process catalog data...
    });

    // Now you can enqueue jobs for this handler
    await dynamicJobManager.EnqueueAsync("SyncExternalCatalog", new
    {
        Url = "https://partner-api.example.com/catalog"
    });
}

The handler receives a context object containing JsonData (the raw JSON string) and ServiceProvider (a scoped container). Resolving dependencies from ServiceProvider is the recommended approach — avoid capturing external state in the handler closure.

There's one priority rule to keep in mind: if a name matches both a typed job and a dynamic handler, the typed job wins. Dynamic handlers never accidentally override existing typed jobs.

Dynamic jobs ultimately go through the standard typed job pipeline, so they work with every background job provider — Default, Hangfire, Quartz, RabbitMQ, TickerQ — without any provider-specific code.

Dynamic Background Workers

IDynamicBackgroundWorkerManager lets you register periodic tasks at runtime and manage their full lifecycle: add, remove, update schedule.

public override async Task OnApplicationInitializationAsync(
    ApplicationInitializationContext context)
{
    var workerManager = context.ServiceProvider
        .GetRequiredService<IDynamicBackgroundWorkerManager>();

    await workerManager.AddAsync(
        "InventorySyncWorker",
        new DynamicBackgroundWorkerSchedule
        {
            Period = 30000 // 30 seconds
        },
        async (workerContext, cancellationToken) =>
        {
            var syncService = workerContext.ServiceProvider
                .GetRequiredService<IInventorySyncAppService>();

            await syncService.SyncAsync(cancellationToken);
        }
    );
}

If you're using Hangfire or Quartz as your provider, you can use a cron expression instead of a fixed interval:

await workerManager.AddAsync(
    "DailyReportWorker",
    new DynamicBackgroundWorkerSchedule
    {
        CronExpression = "0 2 * * *" // Every day at 2:00 AM
    },
    async (workerContext, cancellationToken) =>
    {
        var reportService = workerContext.ServiceProvider
            .GetRequiredService<IReportAppService>();

        await reportService.GenerateDailyReportAsync(cancellationToken);
    }
);

Runtime Schedule Management

Adding a worker is just the beginning. The real value of dynamic workers is that the entire lifecycle is controllable at runtime:

// Check if a worker is currently registered
bool exists = workerManager.IsRegistered("InventorySyncWorker");

// A tenant upgrades their plan — speed up sync from 30s to 10s
await workerManager.UpdateScheduleAsync(
    "InventorySyncWorker",
    new DynamicBackgroundWorkerSchedule { Period = 10000 }
);

// Tenant disables the sync feature — remove the worker entirely
await workerManager.RemoveAsync("InventorySyncWorker");

UpdateScheduleAsync only changes the schedule — the handler itself stays the same. For persistent providers like Hangfire and Quartz, UpdateScheduleAsync and RemoveAsync can operate on the persistent scheduling record even after an application restart, when the handler is no longer in memory.

Stopping All Workers

When you need to stop all dynamic workers at once (e.g., as part of a graceful shutdown), call StopAllAsync:

await workerManager.StopAllAsync(cancellationToken);

All registered workers are stopped and cleaned up, and the handler registry is cleared. Calling AddAsync or UpdateScheduleAsync after this throws ObjectDisposedException — this is intentional, preventing new workers from being added during a shutdown sequence.

Provider Support

Dynamic background jobs and dynamic background workers have different levels of provider support.

Dynamic background jobs are compatible with all providers because they reuse the standard typed job pipeline:

| Provider | Supported | |---|---| | Default (In-Memory) | ✅ | | Hangfire | ✅ | | Quartz | ✅ | | RabbitMQ | ✅ | | TickerQ | ✅ |

Dynamic background workers have per-provider implementations:

| Provider | AddAsync | RemoveAsync | UpdateScheduleAsync | Period | CronExpression | |---|---|---|---|---|---| | Default (In-Memory) | ✅ | ✅ | ✅ | ✅ | ❌ | | Hangfire | ✅ | ✅ | ✅ | ✅ | ✅ | | Quartz | ✅ | ✅ | ✅ | ✅ | ✅ | | TickerQ | ❌ | ❌ | ❌ | — | — |

TickerQ uses FrozenDictionary for function registration, which requires all functions to be registered before the application starts. Runtime dynamic registration is not possible.

Restart Behavior

Dynamic handlers are stored in memory and are not persisted across application restarts. This is a deliberate design choice — handlers are code logic (delegates), and code logic is inherently not serializable.

For persistent providers (Hangfire, Quartz), this means: enqueued jobs and recurring job entries survive a restart in the database, but the handlers need to be re-registered. If a handler is not re-registered, the job executor throws an exception (background jobs) or skips the execution with a warning log (background workers).

The recommended approach is to register handlers in OnApplicationInitializationAsync, so they are automatically restored on every startup:

public override async Task OnApplicationInitializationAsync(
    ApplicationInitializationContext context)
{
    var dynamicJobManager = context.ServiceProvider
        .GetRequiredService<IDynamicBackgroundJobManager>();

    // Re-registered on every startup — persistent jobs will find their handler
    dynamicJobManager.RegisterHandler("SyncExternalCatalog", async (jobContext, ct) =>
    {
        // handler logic...
    });
}

Summary

IDynamicBackgroundJobManager lets you enqueue jobs and register handlers by name at runtime, compatible with all background job providers, no compile-time types required. IDynamicBackgroundWorkerManager lets you add, remove, and update the schedule of periodic workers at runtime — Hangfire and Quartz providers also support cron expressions. Register handlers in OnApplicationInitializationAsync to ensure automatic recovery on every startup.

References

• Background Jobs
• Background Workers
• Hangfire Background Job Manager
• Quartz Background Job Manager

Multi-tenancy is built on isolation — isolated data, isolated permissions, isolated users. ABP's default behavior has always followed this assumption: one user belongs to exactly one tenant. Clean, simple, no ambiguity. For most SaaS applications, that's exactly what you want. (The new TenantUserSharingStrategy enum formally names this default behavior Isolated.)

But isolation is the system's concern, not the user's. In practice, people's work doesn't always line up neatly with tenant boundaries.

Think about a financial consultant who works with three different companies — each one a tenant in your system. Under the Isolated model, she needs three separate accounts, three passwords. Forgot which password goes with which company? Good luck. Worse, the system sees three unrelated people — there's nothing linking those accounts to the same human being.

This comes up more often than you'd think:

• In a corporate group, an IT admin manages multiple subsidiaries, each running as its own tenant. Every day means logging out, logging back in with different credentials, over and over
• A SaaS platform's ops team needs to hop into different customer tenants to debug issues. Each time they create a throwaway account, then delete it — or just share one account and lose all audit trail
• Some users resort to email aliases (alice+company1@example.com) to work around uniqueness constraints — that's not a solution, that's a hack

The common thread here: the user's identity is global, but their working context is per-tenant. The problem isn't a technical limitation — it's that the Isolated assumption ("one user, one tenant") simply doesn't hold in these scenarios.

What's needed is not "one account per tenant" but "one account, multiple tenants."

ABP's Shared User Accounts (TenantUserSharingStrategy.Shared) does exactly this. It makes user identity global and turns tenants into workspaces that a user can join and switch between — similar to how one person can belong to multiple workspaces in Slack.

This is a commercial feature, available starting from ABP 10.2, provided by the Account.Pro and Identity.Pro modules.

Enabling the Shared Strategy

A single configuration is all it takes:

Configure<AbpMultiTenancyOptions>(options =>
{
    options.IsEnabled = true;
    options.UserSharingStrategy = TenantUserSharingStrategy.Shared;
});

The most important behavior change after switching to Shared: username and email uniqueness become global instead of per-tenant. This follows naturally — if the same account needs to be recognized across tenants, its identifiers must be unique across the entire system.

Security-related settings (2FA, account lockout, password policies, captcha, etc.) are also managed at the Host level. This makes sense too: if user identity is global, the security rules around it should be global as well.

One Account, Multiple Tenants

With the Shared strategy enabled, the day-to-day user experience changes fundamentally.

When a user is associated with only one tenant, the system recognizes it automatically and signs them in directly — the user doesn't even notice that tenants exist. When the user belongs to multiple tenants, the login flow presents a tenant selection screen after credentials are verified:

After signing into a tenant, a tenant switcher appears in the user menu — click it anytime to jump to another tenant without signing out. ABP re-issues the authentication ticket (with the new TenantId in the claims) on each switch, so the permission system is fully independent per tenant.

Users can also leave a tenant. Leaving doesn't delete the association record — it marks it as inactive. This preserves foreign key relationships with other entities. If the user is invited back later, the association is simply reactivated instead of recreated.

The same soft removal is available to a tenant admin from the user list — a Remove from tenant action that takes a user off the tenant without touching the global account. Useful for the obvious case: an employee leaves the company, the admin removes them from the tenant, but their account (and any other tenant they belong to) stays intact.

Back to our earlier scenario: the financial consultant now has one account, one password. She picks which company to work in at login, switches between them during the day. The system knows it's the same person, and the audit log can trace her actions across every tenant.

Invitations

Users don't just appear in a tenant — someone has to invite them. This is the core operation from the administrator's perspective.

A tenant admin opens the invitation dialog, enters one or more email addresses (batch invitations are supported), and can pre-assign roles — so the user gets the right permissions the moment they join, no extra setup needed:

The invited person receives an email with a link. What happens next depends on whether they already have an account.

If they already have an account, they see a confirmation page and can join the tenant with a single click:

If they don't have an account yet, the link takes them to a registration form. Once they register, they're automatically added to the tenant:

Admins can also manage pending invitations at any time — resend emails or revoke invitations.

The invitation feature is also available under the Isolated strategy, but invited users can only join a single tenant.

Setting Up a New Tenant

There's a notable shift in how new tenants are bootstrapped.

Under the Isolated model, creating a tenant typically seeds an admin user automatically. With Shared, this no longer happens — because users are global, and it doesn't make sense to create one out of thin air for a specific tenant.

Instead, you create the tenant first, then invite someone in and grant them the admin role.

This is a natural fit — the admin is just a global user who happens to hold the admin role in this particular tenant.

Where Do Newly Registered Users Go?

Under the Shared strategy, self-registration runs into an interesting problem: the system doesn't know which tenant the user wants to join. Without being signed in, tenant context is usually determined by subdomain or a tenant switcher on the login page — but for a brand-new user, those signals might not exist at all.

So ABP's approach is: don't establish any tenant association at registration time. A newly registered user doesn't belong to any tenant, and doesn't belong to the Host either — this is an entirely new state. ABP still lets these users sign in, change their password, and manage their account, but they can't access any permission-protected features within a tenant.

AbpIdentityPendingTenantUserOptions.Strategy controls what happens in this "pending" state.

CreateTenant — automatically creates a tenant for the new user. This fits the "sign up and get your own workspace" pattern, like how Slack or Notion handles registration: you register, the system spins up a workspace for you.

Configure<AbpIdentityPendingTenantUserOptions>(options =>
{
    options.Strategy = AbpIdentityPendingTenantUserStrategy.CreateTenant;
});

Inform (the default) — shows a message telling the user to contact an administrator to join a tenant. This is the right choice for invite-only platforms where users must be brought in by an existing tenant admin.

Configure<AbpIdentityPendingTenantUserOptions>(options =>
{
    options.Strategy = AbpIdentityPendingTenantUserStrategy.Inform;
});

There's also a Redirect strategy that sends the user to a custom URL for more complex flows.

See the official documentation for full configuration details.

Database Considerations

The Shared strategy introduces some mechanisms and constraints at the database level that are worth understanding.

Global Uniqueness: Enforced in Code, Not by Database Indexes

Username and email uniqueness checks must span all tenants. ABP disables the tenant filter (TenantFilter.Disable()) during validation and searches globally for conflicts.

A notable design choice here: global uniqueness is enforced at the application level, not through database unique indexes. The reason is practical — in a database-per-tenant setup, users live in separate physical databases, so a cross-database unique index simply isn't possible. Even in a shared database, soft-delete complicates unique indexes (you'd need a composite index on "username + deletion time"). So ABP handles this in application code instead.

To keep things safe under concurrency — say two tenant admins invite the same email address at the same time — ABP uses a distributed lock to serialize uniqueness validation. This means your production environment needs a distributed lock provider configured (such as Redis).

The uniqueness check goes beyond just "no duplicate usernames." ABP also checks for cross-field conflicts: a user's username can't match another user's email, and vice versa. This prevents identity confusion in edge cases.

Tenants with Separate Databases

If some of your tenants use their own database (database-per-tenant), the Shared strategy requires extra attention.

The login flow and tenant selection happen on the Host side. This means the Host database's AbpUsers table must contain records for all users — even those originally created in a tenant's separate database. ABP's approach is replication: it saves the primary user record in the Host context and creates a copy in the tenant context. In a shared-database setup, both records live in the same table; in a database-per-tenant setup, they live in different physical databases. Updates and deletes are kept in sync automatically.

If your application uses social login or passkeys, the AbpUserLogins and AbpUserPasskeys tables also need to be synced in the Host database.

Migrating from the Isolated Strategy

If you're moving an existing multi-tenant application from Isolated to Shared, ABP automatically runs a global uniqueness check when you switch the strategy and reports any conflicts.

The most common conflict: the same email address registered as separate users in different tenants. You'll need to resolve these first — merge the accounts or change one side's email — before the Shared strategy can be enabled.

Summary

ABP's Shared User Accounts addresses a real-world need in multi-tenant systems: one person working across multiple tenants.

• One configuration switch to TenantUserSharingStrategy.Shared
• User experience: pick a tenant at login, switch between tenants anytime, one password for everything
• Admin experience: invite users by email, pre-assign roles on invitation
• Database notes: configure a distributed lock provider for production; tenants with separate databases need user records replicated in the Host database

ABP takes care of global uniqueness validation, tenant association management, and login flow adaptation under the hood.

References

• Shared User Accounts
• ABP Multi-Tenancy

If you've built a confidential client with ABP's OpenIddict module, you know the drill: create an application in the management UI, set a client_id, generate a client_secret, and paste that secret into your client's appsettings.json or environment variables. It works. It's familiar. And for a lot of projects, it's perfectly fine.

But client_secret is a shared secret — and shared secrets carry an uncomfortable truth: the same value exists in two places at once. The authorization server stores a hash of it in the database, and your client stores the raw value in configuration. That means two potential leak points. Worse, the secret has no inherent identity. Anyone who obtains the string can impersonate your client and the server has no way to tell the difference.

For many teams, this tradeoff is acceptable. But certain scenarios make it hard to ignore:

• Microservice-to-microservice calls: A backend mesh of a dozen services, each with its own client_secret scattered across deployment configs and CI/CD pipelines. Rotating them across environments without missing one becomes a coordination problem.
• Multi-tenant SaaS platforms: Every tenant's client application deserves truly isolated credentials. With shared secrets, the database holds hashed copies for all tenants — a breach of that table is a breach of everyone's credentials.
• Financial-grade API (FAPI) compliance: Standards like FAPI 2.0 explicitly require asymmetric client authentication. client_secret doesn't make the cut.
• Zero-trust architectures: In a zero-trust model, identity must be cryptographically provable, not based on a string that can be copied and pasted.

The underlying problem is that a shared secret is just a password. It can be stolen, replicated, and used without leaving a trace. The fix has existed in cryptography for decades: asymmetric keys.

With asymmetric key authentication, the client generates a key pair. The public key is registered with the authorization server. The private key never leaves the client. Each time the client needs a token, it signs a short-lived JWT — called a client assertion — with the private key. The server verifies the signature using the registered public key. There is no secret on the server side that could be used to forge a request, because the private key is never transmitted or stored remotely.

This is exactly what the private_key_jwt client authentication method, defined in OpenID Connect Core, provides. ABP's OpenIddict module now supports it end-to-end: you register a JSON Web Key Set (JWKS) containing your public key through the application management UI (ABP Commercial), and your client authenticates using the corresponding private key. The key generation tooling (abp generate-jwks) ships as part of the open-source ABP CLI.

This feature is available starting from ABP Framework 10.3.

How It Works

The flow is straightforward:

1. The client holds an RSA key pair — private key (kept locally) and public key (registered on the authorization server as a JWKS).
2. On each token request, the client uses the private key to sign a JWT with a short expiry and a unique jti claim.
3. The authorization server verifies the signature against the registered public key and issues a token if it checks out.

The private key never leaves the client. Even if someone obtains the authorization server's database, there's nothing there that can be used to generate a valid client assertion.

Generating a Key Pair

ABP CLI includes a generate-jwks command that creates an RSA key pair in the right formats:

abp generate-jwks

This produces two files in the current directory:

• jwks.json — the public key in JWKS format, to be uploaded to the server
• jwks-private.pem — the private key in PKCS#8 PEM format, to be kept on the client

You can customize the output directory, key size, and signing algorithm:

abp generate-jwks --alg RS512 --key-size 4096 -o ./keys -f myapp

Supported algorithms: RS256, RS384, RS512, PS256, PS384, PS512. The default is RS256 with a 2048-bit key.

The command also prints the contents of jwks.json to the console so you can copy it directly.

Registering the JWKS in the Management UI

Open OpenIddict → Applications in the ABP admin panel and create or edit a confidential application (Client Type: Confidential).

In the Client authentication method section, you'll find the new JSON Web Key Set field.

Paste the contents of jwks.json into the JSON Web Key Set field:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "6444...",
      "alg": "RS256",
      "n": "tx...",
      "e": "AQAB"
    }
  ]
}

Save the application. It's now configured for private_key_jwt authentication. You can set either client_secret or a JWKS, or both — ABP enforces that a confidential application always has at least one credential.

Requesting a Token with the Private Key

On the client side, each token request requires building a client assertion JWT signed with the private key. Here's a complete client_credentials example:

// Discover the authorization server endpoints (including the issuer URI).
var client = new HttpClient();
var configuration = await client.GetDiscoveryDocumentAsync("https://your-auth-server/");

// Load the private key generated by `abp generate-jwks`.
using var rsaKey = RSA.Create();
rsaKey.ImportFromPem(await File.ReadAllTextAsync("jwks-private.pem"));

// Read the kid from jwks.json so it stays in sync with the server-registered public key.
string? signingKid = null;
if (File.Exists("jwks.json"))
{
    using var jwksDoc = JsonDocument.Parse(await File.ReadAllTextAsync("jwks.json"));
    if (jwksDoc.RootElement.TryGetProperty("keys", out var keysElem) &&
        keysElem.GetArrayLength() > 0 &&
        keysElem[0].TryGetProperty("kid", out var kidElem))
    {
        signingKid = kidElem.GetString();
    }
}

var signingKey = new RsaSecurityKey(rsaKey) { KeyId = signingKid };
var signingCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.RsaSha256);

// Build the client assertion JWT.
var now = DateTime.UtcNow;
var jwtHandler = new JsonWebTokenHandler();
var clientAssertionToken = jwtHandler.CreateToken(new SecurityTokenDescriptor
{
    // OpenIddict requires typ = "client-authentication+jwt" for client assertion JWTs.
    TokenType = "client-authentication+jwt",
    Issuer = "MyClientId",
    // aud must equal the authorization server's issuer URI from the discovery document,
    // not the token endpoint URL.
    Audience = configuration.Issuer,
    Subject = new ClaimsIdentity(new[]
    {
        new Claim(JwtRegisteredClaimNames.Sub, "MyClientId"),
        new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
    }),
    IssuedAt = now,
    NotBefore = now,
    Expires = now.AddMinutes(5),
    SigningCredentials = signingCredentials,
});

// Request a token using the client_credentials flow.
var tokenResponse = await client.RequestClientCredentialsTokenAsync(
    new ClientCredentialsTokenRequest
    {
        Address = configuration.TokenEndpoint,
        ClientId = "MyClientId",
        ClientCredentialStyle = ClientCredentialStyle.PostBody,
        ClientAssertion = new ClientAssertion
        {
            Type = OidcConstants.ClientAssertionTypes.JwtBearer,
            Value = clientAssertionToken,
        },
        Scope = "MyAPI",
    });

A few things worth paying attention to:

• TokenType must be "client-authentication+jwt". OpenIddict rejects client assertion JWTs that don't carry this header.
• Audience must match the authorization server's issuer URI exactly — use configuration.Issuer from the discovery document, not the token endpoint URL.
• Jti must be unique per request to prevent replay attacks.
• Keep Expires short (five minutes or less). A client assertion is a one-time proof of identity, not a long-lived credential.

This example uses IdentityModel for the token request helpers and Microsoft.IdentityModel.JsonWebTokens for JWT creation.

Key Rotation Without Downtime

One of the practical advantages of JWKS is that it can hold multiple public keys simultaneously. This makes zero-downtime key rotation straightforward:

1. Run abp generate-jwks to produce a new key pair.
2. Append the new public key to the keys array in your existing jwks.json and update the JWKS in the management UI.
3. Switch the client to sign assertions with the new private key.
4. Once the transition is complete, remove the old public key from the JWKS.

During the transition window, both the old and new public keys are registered on the server, so any in-flight requests signed with either key will still validate correctly.

Summary

To use private_key_jwt authentication in an ABP Pro application:

1. Run abp generate-jwks to generate an RSA key pair.
2. Paste the jwks.json contents into the JSON Web Key Set field in the OpenIddict application management UI.
3. On the client side, sign a short-lived client assertion JWT with the private key — making sure to set the correct typ, aud (from the discovery document), and a unique jti — then use it to request a token.

ABP handles public key storage and validation automatically. OpenIddict handles the signature verification on the token endpoint. As a developer, you only need to keep the private key file secure — there's no shared secret to synchronize between client and server.

References

• OpenID Connect Core — Client Authentication
• RFC 7523 — JWT Profile for Client Authentication
• ABP OpenIddict Module Documentation
• ABP CLI Documentation
• OpenIddict Documentation

Almost every user-facing system eventually runs into the same problem: some operations cannot be allowed to run without limits.

Sometimes it's a cost issue — sending an SMS costs money, and generating a report hammers the database. Sometimes it's security — a login endpoint with no attempt limit is an open invitation for brute-force attacks. And sometimes it's a matter of fairness — your paid plan says "up to 100 data exports per month," and you need to actually enforce that.

What all these cases have in common is that the thing being limited isn't an HTTP request — it's a business operation, performed by a specific who, doing a specific what, against a specific resource.

ASP.NET Core ships with a built-in rate limiting middleware that sits in the HTTP pipeline. It's excellent for broad API protection — throttling requests per IP to fend off bots or DDoS traffic. But it only sees HTTP requests. It can tell you how many requests came from an IP address; it cannot tell you:

• "How many verification codes has this phone number received today?" The moment the user switches networks, the counter resets — completely useless
• "How many reports has this user exported today?" Switching from mobile to desktop gives them a fresh counter
• "How many times has someone tried to log in as alice?" An attacker rotating through dozens of IPs will never hit the per-IP limit

There's another gap: some rate-limiting logic has no corresponding HTTP endpoint at all — it lives inside an application service method called by multiple endpoints, or triggered by a background job. HTTP middleware has no place to hook in.

Real-world requirements tend to look like this:

• The same phone number can receive at most 3 verification codes per hour, regardless of which device or IP the request comes from
• Each user can generate at most 2 monthly sales reports per day, because a single report query scans millions of records
• Login attempts are limited to 5 failures per username per 5 minutes, and 20 failures per IP per hour — two independent counters, both enforced simultaneously
• Free-tier users get 50 AI calls per month, paid users get 500 — this is a product-defined quota, not a security measure
• Your system integrates with an LLM provider (OpenAI, Azure OpenAI, etc.) where every call has a real dollar cost. Without per-user or per-tenant limits, a single user can exhaust your monthly budget overnight

The pattern is clear: the identity being throttled is a business identity — a user, a phone number, a resource ID — not an IP address. And the action being throttled is a business operation, not an HTTP request.

ABP's Operation Rate Limiting module is built for exactly this. It lets you enforce limits directly in your application or domain layer, with full awareness of who is doing what.

This module is used by the Account (Pro) modules internally and comes pre-installed in the latest startup templates. You must have an ABP Team or a higher license to use this module.

Defining a Policy

The model is straightforward: define a named policy in ConfigureServices, then call CheckAsync wherever you need to enforce it.

Name your policies after the business action they protect — "SendSmsCode", "GenerateReport", "CallAI". A clear name makes the intent obvious at the call site, and avoids the mystery of something like "policy1".

Configure<AbpOperationRateLimitingOptions>(options =>
{
    options.AddPolicy("SendSmsCode", policy =>
    {
        policy.WithFixedWindow(TimeSpan.FromMinutes(1), maxCount: 1)
              .PartitionByParameter();
    });
});

• WithFixedWindow sets the time window and maximum count — here, at most 1 call per minute
• PartitionByParameter means each distinct value you pass at call time (such as a phone number) gets its own independent counter

Then inject IOperationRateLimitingChecker and call CheckAsync at the top of the method you want to protect:

public class SmsAppService : ApplicationService
{
    private readonly IOperationRateLimitingChecker _rateLimitChecker;

    public SmsAppService(IOperationRateLimitingChecker rateLimitChecker)
    {
        _rateLimitChecker = rateLimitChecker;
    }

    public virtual async Task SendCodeAsync(string phoneNumber)
    {
        await _rateLimitChecker.CheckAsync("SendSmsCode", phoneNumber);

        // Limit not exceeded — proceed with sending the SMS
    }
}

CheckAsync checks the current usage against the limit and throws AbpOperationRateLimitingException (HTTP 429) if the limit is already exceeded. If the check passes, it then increments the counter and proceeds. ABP's exception pipeline catches this automatically and returns a standard error response. Put CheckAsync first — the rate limit check is the gate, and everything else only runs if it passes.

Declarative Usage with [OperationRateLimiting]

The explicit CheckAsync approach is useful when you need fine-grained control — for example, when you want to check the limit conditionally, or when the parameter value comes from somewhere other than a method argument. But for the common case where you simply want to enforce a policy on every invocation of a specific method, there's a cleaner way: the [OperationRateLimiting] attribute.

public class SmsAppService : ApplicationService
{
    [OperationRateLimiting("SendSmsCode")]
    public virtual async Task SendCodeAsync([RateLimitingParameter] string phoneNumber)
    {
        // Rate limit is enforced automatically — no manual CheckAsync needed.
        await _smsSender.SendAsync(phoneNumber, GenerateCode());
    }
}

The attribute works on both Application Service methods (via ABP's interceptor) and MVC Controller actions (via an action filter). No manual injection of IOperationRateLimitingChecker required.

Providing the Partition Key

When using the attribute, the partition key is resolved from the method's parameters automatically:

• Mark a parameter with [RateLimitingParameter] to use its ToString() value as the key — this is the most common case when the key is a single primitive like a phone number or email.
• Have your input DTO implement IHasOperationRateLimitingParameter and provide a GetPartitionParameter() method — useful when the key is a property buried inside a complex input object.

public class SendSmsCodeInput : IHasOperationRateLimitingParameter
{
    public string PhoneNumber { get; set; }
    public string Language { get; set; }

    public string? GetPartitionParameter() => PhoneNumber;
}

[OperationRateLimiting("SendSmsCode")]
public virtual async Task SendCodeAsync(SendSmsCodeInput input)
{
    // input.GetPartitionParameter() = input.PhoneNumber is used as the partition key.
}

If neither is provided, Parameter is null — which is perfectly valid for policies that use PartitionByCurrentUser, PartitionByClientIp, or similar partition types that don't rely on an explicit value.

// Policy uses PartitionByCurrentUser — no partition key needed.
[OperationRateLimiting("GenerateReport")]
public virtual async Task<ReportDto> GenerateMonthlyReportAsync()
{
    // Rate limit is checked per current user, automatically.
}

The resolution order is: [RateLimitingParameter] first, then IHasOperationRateLimitingParameter, then null. If the method has parameters but none is resolved, a warning is logged to help you catch the misconfiguration early.

You can also place [OperationRateLimiting] on the class itself to apply the policy to all public methods:

[OperationRateLimiting("MyServiceLimit")]
public class MyAppService : ApplicationService
{
    public virtual async Task MethodAAsync([RateLimitingParameter] string key) { ... }

    public virtual async Task MethodBAsync([RateLimitingParameter] string key) { ... }
}

A method-level attribute always takes precedence over the class-level one.

Choosing a Partition Type

The partition type controls how counters are isolated from each other — it's the most important decision when setting up a policy, because it determines what dimension you're counting across.

Getting this wrong can make your rate limiting completely ineffective. Using PartitionByClientIp for SMS verification? An attacker just needs to switch networks. Using PartitionByCurrentUser for a login endpoint? There's no current user before login, so the counter has nowhere to land.

• PartitionByParameter — uses the value you explicitly pass as the partition key. This is the most flexible option. Pass a phone number, an email address, a resource ID, or any business identifier you have at hand. It's the right choice whenever you know exactly what the "who" is.
• PartitionByCurrentUser — uses the authenticated user's ID, with no value to pass. Perfect for "each user gets N per day" scenarios where user identity is all you need.
• PartitionByClientIp — uses the client's IP address. Don't rely on this alone — it's too easy to rotate. Use it as a secondary layer alongside another partition type, as in the login example below.
• PartitionByEmail and PartitionByPhoneNumber — designed for pre-authentication flows where the user isn't logged in yet. They prefer the Parameter value you explicitly pass, and fall back to the current user's email or phone number if none is provided.
• PartitionBy — a named custom resolver that can produce any partition key you need. Register a resolver function under a unique name via options.AddPartitionKeyResolver("MyResolver", ctx => ...), then reference it by name: .PartitionBy("MyResolver"). You can also register and reference in one step: .PartitionBy("MyResolver", ctx => ...). When the built-in options don't fit, you're free to implement whatever logic makes sense: look up a resource's owner in the database, derive a key from the user's subscription tier, partition by tenant — anything that returns a string. Because the resolver is stored by name (not as an anonymous delegate), it can be serialized and managed from a UI or database.

The rule of thumb: partition by the identity of whoever's behavior you're trying to limit.

Combining Rules in One Policy

A single rule covers most cases, but sometimes you need to enforce limits across multiple dimensions simultaneously. Login protection is the textbook example: throttling by username alone doesn't stop an attacker from targeting many accounts; throttling by IP alone doesn't stop an attacker with a botnet. You need both, at the same time.

options.AddPolicy("Login", policy =>
{
    // Rule 1: at most 5 attempts per username per 5-minute window
    policy.AddRule(rule => rule
        .WithFixedWindow(TimeSpan.FromMinutes(5), maxCount: 5)
        .PartitionByParameter());

    // Rule 2: at most 20 attempts per IP per hour, counted independently
    policy.AddRule(rule => rule
        .WithFixedWindow(TimeSpan.FromHours(1), maxCount: 20)
        .PartitionByClientIp());
});

The two counters are completely independent. If alice fails 5 times, her account is locked — but other accounts from the same IP are unaffected. If an IP accumulates 20 failures, it's blocked — but alice can still be targeted from other IPs until their own counters fill up.

When multiple rules are present, the module uses a two-phase approach: it checks all rules first, and only increments counters if every rule passes. This prevents a rule from consuming quota on a request that would have been rejected by another rule anyway.

Customizing Policies from Reusable Modules

ABP modules (including your own) can ship with built-in rate limiting policies. For example, an Account module might define a "Account.SendPasswordResetCode" policy with conservative defaults that make sense for most applications. When you need different rules in your specific application, you have two options.

Complete replacement with AddPolicy: call AddPolicy with the same name and the second registration wins, replacing all rules from the module:

Configure<AbpOperationRateLimitingOptions>(options =>
{
    options.AddPolicy("Account.SendPasswordResetCode", policy =>
    {
        policy.AddRule(rule => rule
            .WithFixedWindow(TimeSpan.FromMinutes(5), maxCount: 3)
            .PartitionByEmail());
    });
});

Partial modification with ConfigurePolicy: when you only want to tweak part of a policy — change the error code, add a secondary rule, or tighten the window — use ConfigurePolicy. The builder starts pre-populated with the module's existing rules, so you only express what changes.

For example, keep the module's default rules but assign your own localized error code:

Configure<AbpOperationRateLimitingOptions>(options =>
{
    options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
    {
        policy.WithErrorCode("MyApp:PasswordResetLimit");
    });
});

Or add a secondary IP-based rule on top of what the module already defined, without touching it:

Configure<AbpOperationRateLimitingOptions>(options =>
{
    options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
    {
        policy.AddRule(rule => rule
            .WithFixedWindow(TimeSpan.FromHours(1), maxCount: 20)
            .PartitionByClientIp());
    });
});

If you want a clean slate, call ClearRules() first and then define entirely new rules — this gives you the same result as AddPolicy but makes the intent explicit:

Configure<AbpOperationRateLimitingOptions>(options =>
{
    options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
    {
        policy.ClearRules()
              .WithFixedWindow(TimeSpan.FromMinutes(10), maxCount: 5)
              .PartitionByEmail();
    });
});

ConfigurePolicy throws if the policy name doesn't exist — which catches typos at startup rather than silently doing nothing.

The general rule: use AddPolicy for full replacements, ConfigurePolicy for surgical modifications.

Beyond Just Checking

Not every scenario calls for throwing an exception. IOperationRateLimitingChecker provides three additional methods for more nuanced control.

IsAllowedAsync performs a read-only check — it returns true or false without touching any counter. The most common use case is UI pre-checking: when a user opens the "send verification code" page, check the limit first. If they've already hit it, disable the button and show a countdown immediately, rather than making them click and get an error. That's a meaningfully better experience.

var isAllowed = await _rateLimitChecker.IsAllowedAsync("SendSmsCode", phoneNumber);

GetStatusAsync also reads without incrementing, but returns richer data: RemainingCount, RetryAfter, and CurrentCount. This is what you need to build quota displays — "You have 2 exports remaining today" or "Please try again in 47 seconds" — which are far friendlier than a raw 429.

var status = await _rateLimitChecker.GetStatusAsync("SendSmsCode", phoneNumber);
// status.RemainingCount, status.RetryAfter, status.IsAllowed ...

ResetAsync clears the counter for a given policy and context. Useful in admin panels where support staff can manually unblock a user, or in test environments where you need to reset state between runs.

await _rateLimitChecker.ResetAsync("SendSmsCode", phoneNumber);

When the Limit Is Hit

When CheckAsync triggers, it throws AbpOperationRateLimitingException, which:

• Inherits from BusinessException and maps to HTTP 429 Too Many Requests
• Is handled automatically by ABP's exception pipeline
• Carries useful metadata: RetryAfterSeconds, RemainingCount, MaxCount, CurrentCount

By default, the error code sent to the client is a generic one from the module. If you want each operation to produce its own localized message — "Too many verification code requests, please wait before trying again" instead of a generic error — assign a custom error code to the policy:

options.AddPolicy("SendSmsCode", policy =>
{
    policy.WithFixedWindow(TimeSpan.FromMinutes(1), maxCount: 1)
          .PartitionByParameter()
          .WithErrorCode("App:SmsCodeLimit");
});

For details on mapping error codes to localized messages, see Exception Handling in the ABP docs.

Turning It Off in Development

Rate limiting and local development don't mix well. When you're iterating quickly and calling the same endpoint a dozen times to test something, getting blocked by a 429 every few seconds is genuinely painful. Disable the module in your development environment:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var hostEnvironment = context.Services.GetHostingEnvironment();

    Configure<AbpOperationRateLimitingOptions>(options =>
    {
        if (hostEnvironment.IsDevelopment())
        {
            options.IsEnabled = false;
        }
    });
}

Summary

ABP's Operation Rate Limiting fills the gap that ASP.NET Core's HTTP middleware can't: rate limiting with real awareness of who is doing what. Define a named policy, pick a time window, a max count, and a partition type. Then either call CheckAsync explicitly, or just add [OperationRateLimiting] to your method and let the framework handle the rest. Counter storage, distributed locking, and exception handling are all taken care of.

References

• Operation Rate Limiting (Pro)
• ASP.NET Core Rate Limiting Middleware
• Exception Handling

ABP has a built-in permission system that supports role-based access control (RBAC). You define permissions, assign them to roles, and assign roles to users — once a user logs in, they automatically have the corresponding access. This covers the vast majority of real-world scenarios and is simple, straightforward, and easy to maintain.

However, there is one class of requirements it cannot handle: different access rights for different instances of the same resource type.

Take a bookstore application as an example. You define a Books.Edit permission and assign it to an editor role, so every editor can modify every book. But reality is often more nuanced:

• A specific book should only be editable by its assigned editor
• Certain books are only visible to specific users
• Different users have different levels of access to the same book

Standard permissions cannot address this, because their granularity is the permission type, not a specific record. The traditional approach requires designing your own database tables, writing query logic, and building a management UI from scratch — all of which is costly.

ABP Framework now ships with Resource-Based Authorization to solve exactly this problem. The core idea is to bind permissions to specific resource instances rather than just resource types. For example, you can grant a user permission to edit the price of 1984 specifically, while they have no access to any other book.

More importantly, the entire permission management workflow is handled through a built-in UI dialog — no custom code needed for the management side.

How It Works

Each resource instance (e.g. a book) can have its own permission management dialog. Users who hold the ManagePermissions permission can open it and grant or revoke access for users, roles, or OAuth clients — all from the UI.

A Permissions action appears in each book's action menu:

Clicking it opens the resource permission management dialog for that specific book. You can see who currently has access and click Add permission to grant more:

The Add permission dialog lets you select a user, role, or OAuth client, then choose which permissions to grant:

After saving, the new entry appears in the list immediately.

Each entry in the list also supports Edit and Delete actions. Clicking Edit opens the update dialog where you can adjust the granted permissions:

Clicking Delete shows a confirmation prompt — confirming removes all permissions for that user, role, or OAuth client on this book:

Setting It Up

To get this working, you need to define your resource permissions and wire up the dialog.

Defining Resource Permissions

public static class BookStorePermissions
{
    public const string GroupName = "BookStore";

    public static class Books
    {
        public const string Default = GroupName + ".Books";
        public const string ManagePermissions = Default + ".ManagePermissions";

        public static class Resources
        {
            public const string Name = "Acme.BookStore.Books.Book";
            public const string View = Name + ".View";
            public const string Edit = Name + ".Edit";
            public const string Delete = Name + ".Delete";
        }
    }
}

public override void Define(IPermissionDefinitionContext context)
{
    var group = context.AddGroup(BookStorePermissions.GroupName);

    var bookPermission = group.AddPermission(BookStorePermissions.Books.Default);

    // Users with this permission can open the resource permission dialog
    bookPermission.AddChild(BookStorePermissions.Books.ManagePermissions);

    context.AddResourcePermission(
        name: BookStorePermissions.Books.Resources.View,
        resourceName: BookStorePermissions.Books.Resources.Name,
        managementPermissionName: BookStorePermissions.Books.ManagePermissions
    );

    context.AddResourcePermission(
        name: BookStorePermissions.Books.Resources.Edit,
        resourceName: BookStorePermissions.Books.Resources.Name,
        managementPermissionName: BookStorePermissions.Books.ManagePermissions
    );

    context.AddResourcePermission(
        name: BookStorePermissions.Books.Resources.Delete,
        resourceName: BookStorePermissions.Books.Resources.Name,
        managementPermissionName: BookStorePermissions.Books.ManagePermissions
    );
}

The managementPermissionName acts as a gate: only users who hold ManagePermissions will see the resource permission dialog for a book.

Wiring Up the Dialog (MVC)

Add the required script to your page and open the dialog using abp.ModalManager:

@section scripts
{
    <abp-script src="/Pages/Books/Index.js"/>
    <abp-script src="/Pages/AbpPermissionManagement/resource-permission-management-modal.js" />
}

var _permissionsModal = new abp.ModalManager({
    viewUrl: abp.appPath + 'AbpPermissionManagement/ResourcePermissionManagementModal',
    modalClass: 'ResourcePermissionManagement'
});

function openPermissionsModal(bookId, bookName) {
    _permissionsModal.open({
        resourceName: 'Acme.BookStore.Books.Book',
        resourceKey: bookId,
        resourceDisplayName: bookName
    });
}

For Blazor and Angular applications, ABP provides the equivalent ResourcePermissionManagementModal component and ResourcePermissionManagementComponent. See the Permission Management Module documentation for details.

Checking Permissions in Code

The UI manages the permission assignments; the code enforces them at runtime. In your application service, use AuthorizationService.CheckAsync to verify that the current user holds a specific permission on a given resource instance.

All ABP entities implement IKeyedObject, which the framework uses to extract the resource key automatically — so you can pass the entity object directly without building the key manually:

public virtual async Task<BookDto> GetAsync(Guid id)
{
    var book = await _bookRepository.GetAsync(id);

    // Throws AbpAuthorizationException if the current user has no View permission on this book
    await AuthorizationService.CheckAsync(book, BookStorePermissions.Books.Resources.View);

    return ObjectMapper.Map<Book, BookDto>(book);
}

public virtual async Task<BookDto> UpdateAsync(Guid id, UpdateBookDto input)
{
    var book = await _bookRepository.GetAsync(id);

    await AuthorizationService.CheckAsync(book, BookStorePermissions.Books.Resources.Edit);

    book.Name = input.Name;
    await _bookRepository.UpdateAsync(book);

    return ObjectMapper.Map<Book, BookDto>(book);
}

If you want to check a permission without throwing an exception — for example, to conditionally show or hide a button — use IsGrantedAsync instead, which returns a bool:

var canEdit = await AuthorizationService.IsGrantedAsync(book, BookStorePermissions.Books.Resources.Edit);

Don't Forget to Clean Up

Every resource permission grant is stored as a record in the database. When a book is deleted, those records are not removed automatically — orphaned permission data accumulates over time.

Make sure to clean up resource permissions whenever a resource is deleted:

public virtual async Task DeleteAsync(Guid id)
{
    await _bookRepository.DeleteAsync(id);

    // Clean up all resource permissions for this book
    await _resourcePermissionManager.DeleteAsync(
        resourceName: BookStorePermissions.Books.Resources.Name,
        resourceKey: id.ToString()
    );
}

Summary

Resource-Based Authorization fills the gap between "everyone can do this" and "only specific users can do this on specific resources." In practice, most of the work comes down to two things:

• Define resource permissions and wire up the built-in UI dialog so administrators can assign access through the interface
• Call AuthorizationService.CheckAsync in your application services to enforce those permissions at runtime

Storing permission grants, rendering the dialog, searching for users, roles, and OAuth clients — ABP handles all of that for you.

References

• Resource-Based Authorization
• Authorization
• Permission Management Module

In the last few years, AI has moved from “nice to have” to “hard to live without” for developers. At first it was just code completion and smart hints. Now it’s getting deep into how we build software: the methods, the toolchain, and even the job itself.

Here are some structured thoughts on how AI is affecting developers, based on trends and personal experience.

Every library will have AI-first docs

Future libraries and frameworks won’t just have docs for humans. They’ll also have a manual for AI:

• How to use
• Why it is designed this way
• What NOT to do
• Conventions & Best Practices

Once these rules are written in a structured way, AI can onboard to a library faster and more consistently than a junior developer.

Docs won’t just be knowledge anymore. They’ll be instructions AI can execute.

AI will be a must-have for developers

Soon, “writing code without AI” will feel as strange as “writing code without an IDE.”

• It won’t be about whether you use AI
• It’ll be about how well you use it and where

AI will become:

• A standard productivity tool
• An extension of a developer’s thinking
• A second brain

Developers who don’t use AI will fall behind in both speed and understanding.

As AI gets smarter, it replaces “time”

AI isn’t replacing developers right away. It’s replacing:

• Lots of repetitive time
• Basic development costs
• Higher output per hour

Boilerplate, CRUD, basic validation, simple logic — all of that will get swallowed fast.

It’s not people being replaced. It’s waste.

Orchestrating multiple AIs becomes real

The future isn’t “one AI does everything.” It’s more like:

• Claude writes core code
• Copilot generates and maintains unit tests
• Codex and similar tools write docs and examples
• Other AIs handle refactoring, performance analysis, security checks

The dev process itself becomes an AI orchestration system.

The developer’s role looks more like:

Architect + conductor + quality gatekeeper

Only great infrastructure gets amplified by AI

Even if AI can teach you “how to use it correctly,” it still can’t invent mature infrastructure for you.

We still rely on:

• Stable base frameworks (like ABP)
• Engineering capability proven by many projects
• Long-term maintenance and evolution

AI is an accelerator, not the foundation.

For open source, AI is actually a better companion:

• Helps understand the source code
• Helps learn design thinking
• Helps ship faster

The stronger the infrastructure, the more value AI can amplify.

Frontend feels mature; backend still evolving

From personal experience:

• AI is already very strong in frontend work (Bootstrap / UI components, layout, styling, interaction)
• Backend is still learning and improving (business boundaries, architecture trade-offs, implicit constraints)

This shows: the clearer the rules and the faster the feedback, the faster AI improves.

Writing rules for AI is productivity itself

In the ABP libraries, we’ve already written lots of rules for AI:

• Conventions
• Usage limits
• Recommended patterns

As rules grow:

• AI becomes more stable
• More predictable
• Base development work can be largely automated

Future engineering skill will be, in large part: how to design a rules system for AI.

The real advantage is better feedback loops

AI gets much stronger when there’s clear feedback:

• Tests that run fast and fail loudly
• Logs and metrics that explain behavior
• Code review that checks for edge cases and security

The teams that win are the ones who can quickly verify, correct, and learn.

About a developer’s career

Sometimes I think: I’m glad I didn’t enter the software industry just in the last few years.

If you’re just starting out, you really feel:

• The barrier is lower
• The competition is tougher

But whenever I see AI generate confident but wrong code, I’m reminded:

• The industry still has a future
• It still needs judgment, taste, and experience

There will always be people who love coding. If AI does it and we watch, that’s fine too.

Chaos everywhere, but the experience is moving fast

Big companies, platforms, tools:

• GitHub
• OpenAI
• Claude
• All kinds of IDEs / agents

New AI tools, apps, and platforms keep popping up. New concepts show up almost every week. It’s noisy, but the big picture is clear: AI keeps getting better, and the overall developer experience is improving fast.

Get ready for the AI revolution

Looking back at personal experience:

• Before: Google
• Now: ChatGPT
• Before: manual translation
• Now: fully automatic
• Before: writing unit tests by hand
• Now: AI does it all
• Before: human replies to customers
• Now: AI-assisted or even AI-led

From code completion to agents running tasks, and now deep IDE integration — the pace is shocking.

Closing

AI is not the end of software engineering. It is:

• A leap in cognition
• A restructure of how work gets done
• An upgrade of roles

What matters most isn’t how much code AI can write, but how we redefine the value of “developers” in the AI era.

.NET Conf China 2025 is an annual community event for developers, celebrating the release of .NET 10 (LTS) and the achievements of the past year in China. As an extension of .NET Conf 2025, this event brings together local tech communities, well-known companies, and open-source organizations. It has become the largest .NET online and offline conference in China, dedicated to spreading .NET technology in Chinese and fostering collaboration and exchange.

Event Highlights: Key Topics and Takeaways

This year’s conference focused on three main themes: performance improvements, AI integration, and cross-platform development. Topics covered how to achieve performance gains while maintaining engineering quality, balancing between multi-platform consistency and native capabilities, and taking generative AI from “demo-level” to “production-ready.” On the community and ecosystem side, the event showcased the .NET Foundation’s and domestic and international companies’ progress in supporting architectures like ARM, LoongArch, and RISC-V. It also highlighted best practices in DevOps, observability, and engineering toolchains, creating a complete path from ideas to implementation.

Opening Keynote

Scott Hanselman kicked off .NET Conf China 2025 with a video keynote, announcing that .NET 10 is now available on the official website. He framed the release around four pillars—AI, cloud-native, cross-platform, and performance—including integration with the Microsoft Agent Framework for building and orchestrating multi-agent systems in .NET/C#, industry-leading container and Kubernetes support with Aspire simplifying local containerized development, a richer cross-platform desktop ecosystem (.NET MAUI, Avalonia, Uno Platform), and major performance gains such as Native AOT and single-file publishing for faster startup and easier distribution across platforms.

He underscored China’s importance as .NET’s second-largest market, with roughly 13% of users, and noted that generative AI usage in China has doubled in 2025. The local community is seeing strong momentum around ML.NET, Aspire, and the C# Dev Kit in VS Code. Reflecting on his Baby Smash game written 20 years ago, which now runs cross-platform on .NET 10, he called on developers to modernize: move existing Web, WinForms, and WPF apps to the cloud, improve performance, ship as a single executable, and weave in AI capabilities.

On AI, he emphasized a human-centered stance: AI and agents should augment, not replace, developers. In the future, developers will orchestrate and govern agents, and human judgment will matter more than ever. He closed by thanking the open-source community for its many proposals and pull requests, stressing that .NET is an open-source platform built together by Microsoft and the community, and wishing everyone an inspiring conference and a joyful journey with .NET 10.

Roundtable Discussion

The roundtable discussion, titled “Empowering with AI, Breaking Through Cross-Platform Barriers, and Ecosystem Innovation,” focused on practical implementation. It explored typical paths for large models and intelligent agents in enterprises, key considerations for choosing cross-platform UI frameworks, and the evolution of these frameworks. Panelists discussed questions like: How can AI capabilities be integrated into existing business processes instead of creating an “experimental” pipeline? How should cross-platform solutions be evaluated in terms of performance, ecosystem, and team skillsets? What are the unique opportunities for domestic ecosystems in the global tech landscape? And how can community collaboration help developers quickly adopt best practices? A shared consensus emerged: in the short term, focus on running scenarios; in the long term, return to engineering fundamentals. Both toolchains and methodologies are equally important.

In-Depth Sessions

The afternoon featured four breakout sessions, covering a wide range of topics with deep dives into both foundational technologies and real-world project reviews:

• Frontend and Cross-Platform: Focused on the progress of Avalonia, Blazor, and WebAssembly, as well as the integrated experience of Aspire in multi-service applications. Speakers shared insights on reusing core logic between desktop and web, shortening cold start times with incremental compilation and resource trimming, and performance profiling and optimization in WASM scenarios.
• AI Agents and Enterprise Adoption: Discussed multi-agent orchestration, the MCP plugin ecosystem, and enterprise data compliance. From common pitfalls of “demo-level” AI to the “five-step method” for moving from POC to production, the session covered use cases like knowledge retrieval, process automation, intelligent customer service, and developer assistants, emphasizing evaluation metrics, prompt engineering, and monitoring governance.
• .NET Practices and Engineering: Focused on the latest capabilities and performance practices of EF Core, the boundaries of NativeAOT, automated testing strategies, and observability implementation. Discussions included database migration strategies, caching and concurrency control for hot paths, end-to-end tracing, and structured logging.
• Solutions and Case Studies: From Clean Architecture/DDD to AI-powered business evolution, topics included application modernization, SaaS transformation, and edge-cloud collaboration in AIoT. Speakers broke down modular governance, team collaboration, and release strategies for complex systems, putting “delivering value continuously” at the center stage.

ABP Booth Highlights: Showcases, Conversations, and Fun

The story of ABP began with a promise to create a better starting point. From the frustration of “copy-pasting boilerplate code,” we crafted a modular, opinionated framework. We chose open source and community collaboration. We founded Volosoft to turn our vision into reality with professional tools. Today, tens of thousands of developers explore the ABP framework, and thousands of teams rely on the ABP platform to deliver production-grade .NET applications faster and more securely.

At .NET Conf China 2025, we brought our “developer platform built for developers” to every visitor. Our booth demonstrations started with “a production-ready skeleton from the start”: modular layered architecture, built-in authentication and authorization systems, multi-tenancy support, audit logging, and localization—all out of the box. On the frontend and backend, ABP offers diverse options like MVC, Blazor, and Angular, enabling teams to quickly implement solutions on familiar stacks while maintaining flexibility for future evolution. We also showcased how ABP integrates with containerization, CI/CD, and observability, emphasizing “engineering built into the framework, not reinvented by every team.”

Interaction and Prizes: Sharing technology should also be warm and engaging. We hosted a QR code raffle at the booth, with prizes including ABP stickers, the book Mastering ABP Framework, and Bluetooth headphones. Multiple rounds of raffles and group photos made the interactions more memorable. Many developers shared their ABP experiences and plans for improvement right at the booth, and a few impromptu “code walkthroughs” naturally happened. The love and joy for technology were captured in every handshake and discussion.

Looking Ahead: Building the Ecosystem Together

From an open-source journey to a complete development platform for the future, we’ve always believed that developers deserve a better starting point. Around performance, intelligence, and cross-platform capabilities, we will continue investing in engineering, ecosystem collaboration, and best practice sharing. We also welcome more partners to contribute through documentation and examples, share your experiences, and submit your ideas. Together, let’s make “useful infrastructure” more stable, efficient, and business-friendly.

We look forward to exchanging ideas, sharing practices, and building the ecosystem together at the next gathering. Technology meets creativity, and the possibilities are endless. We’re on the road and waiting for you at the next event.

See you next year at .NET Conf China 2026!

Tracking what users do in your app matters for security, debugging, and business insights. Doing it by hand usually means lots of boilerplate: managing request context, logging operations, tracking entity changes, and more. It adds complexity and makes mistakes more likely.

Why Applications Need Audit Logs

Audit logs are time-ordered records that show what happened in your app.

A good audit log should capture details for every web request, including:

1. Request and Response Details

• Basic info like URL, HTTP method, browser, and HTTP status code
• Network info like client IP address and user agent
• Request parameters and response content when needed

2. Operations Performed

• Controller actions and application service method calls with parameters
• Execution time and duration for performance tracking
• Call chains and dependencies where helpful

3. Entity Changes

• Entity changes that happen during requests
• Property-level changes, with old and new values
• Change types (create, update, delete) and timestamps

4. Exception Information

• Errors and exceptions during request execution
• Exception stack traces and error context
• Clear records of failed operations

5. Request Duration

• Key metrics for measuring performance
• Finding bottlenecks and optimization opportunities
• Useful data for monitoring system health

The Challenge with Doing It by Hand

In ASP.NET Core, developers often use middleware or MVC filters for tracking. Here’s what that looks like and the common problems you’ll hit.

Using Middleware

Middleware are components in the ASP.NET Core pipeline that run during request processing.

Manual tracking typically requires:

• Writing custom middleware to intercept HTTP requests
• Extracting user info (user ID, username, IP address, and so on)
• Recording request start time and execution duration
• Handling both success and failure cases
• Saving audit data to logs or a database

Tracking Inside Business Methods

In your business code, you also need to:

• Log the start and end of important operations
• Capture errors and related context
• Link business operations to the request-level audit data
• Make sure you track all critical actions

Problems with Manual Tracking

Manual tracking has some big downsides:

Code duplication and maintenance pain: Each controller ends up repeating similar tracking logic. Changing the rules means touching many places, and it’s easy to miss some.

Consistency and reliability issues: Different people implement tracking differently. Exception paths are easy to forget. It’s hard to ensure complete coverage.

Performance and scalability concerns: Homegrown tracking can slow the app if not designed well. Tuning and extending it takes effort.

Entity change tracking is especially hard. It often requires:

• Recording original values before updates
• Comparing old and new values for each property
• Handling complex types, collections, and navigation properties
• Designing and saving change records
• Capturing data even when exceptions happen

This usually leads to:

• A lot of code in every update method
• Easy-to-miss edge cases and subtle bugs
• High maintenance when entity models change
• Extra queries and comparisons that can hurt performance
• Incomplete coverage for complex scenarios

ABP Framework’s Built-in Solution

ABP Framework includes a built-in audit logging system. It solves the problems above and adds useful features on top.

Simple Setup vs. Manual Tracking

Instead of writing lots of code, you configure it once:

// Configure audit log options in the module's ConfigureServices method
Configure<AbpAuditingOptions>(options =>
{
    options.IsEnabled = true; // Enable audit log system (default value)
    options.IsEnabledForAnonymousUsers = true; // Track anonymous users (default value)
    options.IsEnabledForGetRequests = false; // Skip GET requests (default value)
    options.AlwaysLogOnException = true; // Always log on errors (default value)
    options.HideErrors = true; // Hide audit log errors (default value)
    options.EntityHistorySelectors.AddAllEntities(); // Track all entity changes
});

// Add middleware in the module's OnApplicationInitialization method
public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    var app = context.GetApplicationBuilder();
    
    // Add audit log middleware - one line of code solves all problems!
    app.UseAuditing();
}

By contrast, manual tracking needs middleware, controller logic, exception handling, and often hundreds of lines. With ABP, a couple of lines enable it and it just works.

What You Get with ABP

Here’s how ABP removes tracking code from your application and still captures what you need.

1. Application Services: No Tracking Code

Manual approach: You’d log inside each method and still risk missing cases.

ABP approach: Tracking is automatic—no tracking code in your methods.

public class BookAppService : ApplicationService
{
    private readonly IRepository<Book, Guid> _bookRepository;
    private readonly IRepository<Author, Guid> _authorRepository;
    
    [Authorize(BookPermissions.Create)]
    public virtual async Task<BookDto> CreateAsync(CreateBookDto input)
    {
        // No need to write any tracking code!
        // ABP automatically tracks:
        // - Method calls and parameters
        // - Calling user
        // - Execution duration
        // - Any exceptions thrown
        
        var author = await _authorRepository.GetAsync(input.AuthorId);
        var book = new Book(input.Title, author, input.Price);
        
        await _bookRepository.InsertAsync(book);
        
        return ObjectMapper.Map<Book, BookDto>(book);
    }
    
    [Authorize(BookPermissions.Update)]
    public virtual async Task<BookDto> UpdateAsync(Guid id, UpdateBookDto input)
    {
        var book = await _bookRepository.GetAsync(id);
        
        // No need to write any entity change tracking code!
        // ABP automatically tracks entity changes:
        // - Which properties changed
        // - Old and new values
        // - When the change happened
        
        book.ChangeTitle(input.Title);
        book.ChangePrice(input.Price);
        
        await _bookRepository.UpdateAsync(book);
        
        return ObjectMapper.Map<Book, BookDto>(book);
    }
}

With manual code, each method might need 20–30 lines for tracking. With ABP, it’s zero—and you still get richer data.

For entity changes, ABP also saves you from writing comparison code. It handles:

• Property change detection
• Recording old and new values
• Complex types and collections
• Navigation property changes
• All with no extra code to maintain

2. Entity Change Tracking: One Line to Turn It On

Manual approach: You’d compare properties, serialize complex types, track collection changes, and write to storage.

ABP approach: Mark the entity or select entities globally.

// Enable audit log for specific entity - one line of code solves all problems!
[Audited]
public class MyEntity : Entity<Guid>
{
    public string Name { get; set; }
    public string Description { get; set; }
    
    [DisableAuditing] // Exclude sensitive data - security control
    public string InternalNotes { get; set; }
}

// Or global configuration - batch processing
Configure<AbpAuditingOptions>(options =>
{
    // Track all entities - one line of code tracks all entity changes
    options.EntityHistorySelectors.AddAllEntities();
    
    // Or use custom selector - precise control
    options.EntityHistorySelectors.Add(
        new NamedTypeSelector(
            "MySelectorName",
            type => typeof(IEntity).IsAssignableFrom(type)
        )
    );
});

3. Extension Features

Manual approach: Adding custom tracking usually spreads across many places and is hard to test.

ABP approach: Use a contributor for clean, centralized extensions.

public class MyAuditLogContributor : AuditLogContributor
{
    public override void PreContribute(AuditLogContributionContext context)
    {
        var currentUser = context.ServiceProvider.GetRequiredService<ICurrentUser>();
        
        // Easily add custom properties - manual implementation needs lots of work
        context.AuditInfo.SetProperty(
            "MyCustomClaimValue",
            currentUser.FindClaimValue("MyCustomClaim")
        );
    }
    
    public override void PostContribute(AuditLogContributionContext context)
    {
        // Add custom comments - business logic integration
        context.AuditInfo.Comments.Add("Some comment...");
    }
}

// Register contributor - one line of code enables extension features
Configure<AbpAuditingOptions>(options =>
{
    options.Contributors.Add(new MyAuditLogContributor());
});

4. Precise Control

Manual approach: You end up with complex conditional logic.

ABP approach: Use attributes for simple, precise control.

// Disable audit log for specific controller - precise control
[DisableAuditing]
public class HomeController : AbpController
{
    // Health check endpoints won't be audited - avoid meaningless logs
}

// Disable for specific action - method-level control
public class HomeController : AbpController
{
    [DisableAuditing]
    public async Task<ActionResult> Home()
    {
        // This action won't be audited - public data access
    }
    
    public async Task<ActionResult> OtherActionLogged()
    {
        // This action will be audited - important business operation
    }
}

5. Visual Management of Audit Logs

ABP also provides a UI to browse and inspect audit logs:

Manual vs. ABP: A Quick Comparison

The benefits of ABP’s audit log system compared to doing it by hand:

| Aspect | Manual Implementation | ABP Audit Logs | |--------|----------------------|----------------| | Setup Complexity | High — Write middleware, services, repository code | Low — A few lines of config, works out of the box | | Code Maintenance | High — Tracking code spread across the app | Low — Centralized, convention-based | | Consistency | Variable — Depends on discipline | Consistent — Automated and standardized | | Performance | Risky without careful tuning | Built-in optimizations and scope control | | Functionality Completeness | Basic tracking only | Comprehensive by default | | Error Handling | Easy to miss edge cases | Automatic and reliable | | Data Integrity | Manual effort required | Handled by the framework | | Extensibility | Custom work is costly | Rich extension points | | Development Efficiency | Weeks to build | Minutes to enable | | Learning Cost | Understand many details | Convention-based, low effort |

Why ABP Audit Logs Matter

ABP’s audit logging removes the boilerplate from user tracking in ASP.NET Core apps.

Core Idea

Manual tracking is error-prone and hard to maintain. ABP gives you a convention-based, automated system that works with minimal setup.

Key Benefits

ABP runs by convention, so you don’t need repetitive code. You can control behavior at the request, entity, and method levels. It automatically captures request details, operations, entity changes, and exceptions, and you can extend it with contributors when needed.

Results in Practice

| Metric | Manual Implementation | ABP Implementation | Improvement | |--------|----------------------|-------------------|-------------| | Development Time | Weeks | Minutes | 99%+ | | Lines of Code | Hundreds of lines | 2 lines of config | 99%+ | | Maintenance Cost | High | Low | Significant | | Functionality Completeness | Basic | Comprehensive | Significant | | Error Rate | Higher risk | Lower risk | Improved |

Recommendation

If you need audit logs, start with ABP’s built-in system. It reduces effort, improves consistency, and stays flexible as your app grows. You can focus on your business logic and let the framework handle the infrastructure.

References

• ABP Audit Logging
• ABP Audit Logging UI

In ABP's layered architecture, we frequently encounter two types of services that appear similar but serve distinctly different purposes: Application Services and Domain Services. Understanding the differences between them is crucial for building clear and maintainable enterprise applications.

Architectural Positioning

In ABP's layered architecture:

• Application Services reside in the application layer and are responsible for coordinating use case execution
• Domain Services reside in the domain layer and are responsible for implementing core business logic

This layered design follows Domain-Driven Design (DDD) principles, ensuring clear separation of business logic and system maintainability.

Application Services: Use Case Orchestrators

Core Responsibilities

Application Services are stateless services primarily used to implement application use cases. They act as a bridge between the presentation layer and domain layer, responsible for:

• Parameter Validation: Input validation is automatically handled by ABP using data annotations
• Authorization: Checking user permissions and access control using [Authorize] attribute or manual authorization checks via IAuthorizationService
• Transaction Management: Methods automatically run as Unit of Work (transactional by default)
• Use Case Orchestration: Organizing and coordinating multiple domain objects to complete specific business use cases
• Data Transformation: Handling conversion between DTOs and domain objects using ObjectMapper

Design Principles

1. DTO Boundaries: Application service methods should only accept and return DTOs, never directly expose domain entities
2. Use Case Oriented: Each method should correspond to a clear user use case
3. Thin Layer Design: Avoid implementing complex business logic in application services

Typical Execution Flow

A standard application service method typically follows this pattern:

[Authorize(BookPermissions.Create)] // Declarative authorization
public virtual async Task<BookDto> CreateBookAsync(CreateBookDto input) // input is automatically validated
{
    // Get related data
    var author = await _authorRepository.GetAsync(input.AuthorId);
    
    // Call domain service to execute business logic (if needed)
    // You can also use the entity constructor directly if no complex business logic is required
    var book = await _bookManager.CreateAsync(input.Title, author, input.Price);
    
    // Persist changes
    await _bookRepository.InsertAsync(book);
    
    // Return DTO
    return ObjectMapper.Map<Book, BookDto>(book);
}

Integration Services: Special kind of Application Service

It's worth mentioning that ABP also provides a special type of application service—Integration Services. They are application services marked with the [IntegrationService] attribute, designed for inter-module or inter-microservice communication.

We have a community article dedicated to integration services: Integration Services Explained — What they are, when to use them, and how they behave

Domain Services: Guardians of Business Logic

Core Responsibilities

Domain Services implement core business logic and are particularly needed when:

• Core domain logic depends on services: You need to implement logic that requires repositories or other external services
• Logic spans multiple aggregates: The business logic is related to more than one aggregate/entity and doesn't properly fit in any single aggregate
• Complex business rules: Complex domain rules that don't naturally belong in a single entity

Design Principles

1. Domain Object Interaction: Method parameters and return values should be domain objects (entities, value objects), never DTOs
2. Business Logic Focus: Focus on implementing pure business rules
3. Stateless Design: Maintain the stateless nature of services
4. State-Changing Operations Only: Domain services should only define methods that mutate data, not query methods
5. No Authorization Logic: Domain services should not perform authorization checks or depend on current user context
6. Specific Method Names: Use descriptive, business-meaningful method names (e.g., AssignToAsync) instead of generic names (e.g., UpdateAsync)

Implementation Example

public class IssueManager : DomainService
{
    private readonly IRepository<Issue, Guid> _issueRepository;
    
    public virtual async Task AssignToAsync(Issue issue, Guid userId)
    {
        // Business rule: Check user's unfinished task count
        var openIssueCount = await _issueRepository.GetCountAsync(i => i.AssignedUserId == userId && !i.IsClosed);
            
        if (openIssueCount >= 3)
        {
            throw new BusinessException("IssueTracking:ConcurrentOpenIssueLimit");
        }
        
        // Execute assignment logic
        issue.AssignedUserId = userId;
        issue.AssignedDate = Clock.Now;
    }
}

Key Differences Comparison

| Dimension | Application Services | Domain Services | |-----------|---------------------|-----------------| | Layer Position | Application Layer | Domain Layer | | Primary Responsibility | Use Case Orchestration | Business Logic Implementation | | Data Interaction | DTOs | Domain Objects | | Callers | Presentation Layer/Client Applications | Application Services/Other Domain Services | | Authorization | Responsible for permission checks | No authorization logic | | Transaction Management | Manages transaction boundaries (Unit of Work) | Participates in transactions but doesn't manage | | Current User Context | Can access current user information | Should not depend on current user context | | Return Types | Returns DTOs | Returns domain objects only | | Query Operations | Can perform query operations | Should not define GET/query methods | | Naming Convention | *AppService | *Manager or *Service |

Collaboration Patterns in Practice

In real-world development, these two types of services typically work together:

// Application Service
public class BookAppService : ApplicationService
{
    private readonly BookManager _bookManager;
    private readonly IRepository<Book> _bookRepository;
    
    [Authorize(BookPermissions.Update)]
    public virtual async Task<BookDto> UpdatePriceAsync(Guid id, decimal newPrice)
    {
        var book = await _bookRepository.GetAsync(id);

        await _bookManager.ChangePriceAsync(book, newPrice);
        
        await _bookRepository.UpdateAsync(book);
        
        return ObjectMapper.Map<Book, BookDto>(book);
    }
}

// Domain Service
public class BookManager : DomainService
{
    public virtual async Task ChangePriceAsync(Book book, decimal newPrice)
    {
        // Domain service focuses on business rules
        if (newPrice <= 0)
        {
            throw new BusinessException("Book:InvalidPrice");
        }
        
        if (book.IsDiscounted && newPrice > book.OriginalPrice)
        {
            throw new BusinessException("Book:DiscountedPriceCannotExceedOriginal");
        }

        if (book.Price == newPrice)
        {
            return;
        }

        // Additional business logic: Check if price change requires approval
        if (await RequiresApprovalAsync(book, newPrice))
        {
            throw new BusinessException("Book:PriceChangeRequiresApproval");
        }

        book.ChangePrice(newPrice);
    }
    
    private Task<bool> RequiresApprovalAsync(Book book, decimal newPrice)
    {
        // Example business rule: Large price increases require approval
        var increasePercentage = ((newPrice - book.Price) / book.Price) * 100;
        return Task.FromResult(increasePercentage > 50); // 50% increase threshold
    }
}

Best Practice Recommendations

Application Services

• Create a corresponding application service for each aggregate root
• Use clear naming conventions (e.g., IBookAppService)
• Implement standard CRUD operation methods (GetAsync, CreateAsync, UpdateAsync, DeleteAsync)
• Avoid inter-application service calls within the same module/application
• Always return DTOs, never expose domain entities directly
• Use the [Authorize] attribute for declarative authorization or manual checks via IAuthorizationService
• Methods automatically run as Unit of Work (transactional)
• Input validation is handled automatically by ABP

Domain Services

• Use the Manager suffix for naming (e.g., BookManager)
• Only define state-changing methods, avoid query methods (use repositories directly in Application Services for queries)
• Throw BusinessException with clear, unique error codes for domain validation failures
• Keep methods pure, avoid involving user context or authorization logic
• Accept and return domain objects only, never DTOs
• Use descriptive, business-meaningful method names (e.g., AssignToAsync, ChangePriceAsync)
• Do not implement interfaces unless there's a specific need for multiple implementations

Summary

Application Services and Domain Services each have their distinct roles in the ABP framework: Application Services serve as use case orchestrators, handling authorization, validation, transaction management, and DTO transformations; Domain Services focus purely on business logic implementation without any infrastructure concerns. Integration Services are a special type of Application Service designed for inter-service communication.

Correctly understanding and applying these service patterns is key to building high-quality ABP applications. Through clear separation of responsibilities, we can not only build more maintainable code but also flexibly switch between monolithic and microservice architectures—this is precisely the elegance of ABP framework design.

References

• Application Services
• Integration Services
• Domain Services

Introduction

In this article, I'll show you how to integrate and use the Hangfire Dashboard in an ABP API website.

Typically, API websites use JWT Bearer authentication, but the Hangfire Dashboard isn't compatible with JWT Bearer authentication. Therefore, we need to implement Cookies and OpenIdConnect authentication for the Hangfire Dashboard access.

Creating a New ABP Demo Project 🛠️

We'll create a new ABP Demo Tiered project that includes AuthServer, API, and Web projects.

abp new AbpHangfireDemoApp -t app --tiered

Now let's add the Hangfire Dashboard to the API project and configure it to use Cookies and OpenIdConnect authentication for accessing the dashboard.

Adding a New Hangfire Application 🔧

We need to add a new Hangfire application to the appsettings.json file in the DbMigrator project:

Note: Replace 44371 with your API project's port.

"OpenIddict": {
    "Applications": {
        //...
        "AbpHangfireDemoApp_Hangfire": {
            "ClientId": "AbpHangfireDemoApp_Hangfire",
            "RootUrl": "https://localhost:44371/"
        }
        //...
    }
}

2. Update the OpenIddictDataSeedContributor's CreateApplicationsAsync method in the Domain project to seed the new Hangfire application.

 //Hangfire Client
var hangfireClientId = configurationSection["AbpHangfireDemoApp_Hangfire:ClientId"];
if (!hangfireClientId.IsNullOrWhiteSpace())
{
    var hangfireClientRootUrl = configurationSection["AbpHangfireDemoApp_Hangfire:RootUrl"]!.EnsureEndsWith('/');

    await CreateApplicationAsync(
        applicationType: OpenIddictConstants.ApplicationTypes.Web,
        name: hangfireClientId!,
        type: OpenIddictConstants.ClientTypes.Confidential,
        consentType: OpenIddictConstants.ConsentTypes.Implicit,
        displayName: "Hangfire Application",
        secret: configurationSection["AbpHangfireDemoApp_Hangfire:ClientSecret"] ?? "1q2w3e*",
        grantTypes: new List<string> //Hybrid flow
        {
            OpenIddictConstants.GrantTypes.AuthorizationCode, OpenIddictConstants.GrantTypes.Implicit
        },
        scopes: commonScopes,
        redirectUris: new List<string> { $"{hangfireClientRootUrl}signin-oidc" },
        postLogoutRedirectUris: new List<string> { $"{hangfireClientRootUrl}signout-callback-oidc" },
        clientUri: hangfireClientRootUrl,
        logoUri: "/images/clients/aspnetcore.svg"
    );
}

3. Run the DbMigrator project to seed the new Hangfire application.

Adding Hangfire Dashboard to the API Project 📦

1. Add the following packages and modules dependencies to the API project:

<PackageReference Include="Volo.Abp.BackgroundJobs.HangFire" Version="9.2.0" />
<PackageReference Include="Volo.Abp.AspNetCore.Authentication.OpenIdConnect" Version="9.2.0" />
<PackageReference Include="Hangfire.SqlServer" Version="1.8.20" />

typeof(AbpBackgroundJobsHangfireModule),
typeof(AbpAspNetCoreAuthenticationOpenIdConnectModule)

2. Add the HangfireClientId and HangfireClientSecret to the appsettings.json file in the API project:

"AuthServer": {
    "Authority": "https://localhost:44358",
    "RequireHttpsMetadata": true,
    "MetaAddress": "https://localhost:44358",
    "SwaggerClientId": "AbpHangfireDemoApp_Swagger",
    "HangfireClientId": "AbpHangfireDemoApp_Hangfire",
    "HangfireClientSecret": "1q2w3e*"
}

3. Add the ConfigureHangfire method to the API project to configure Hangfire:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var configuration = context.Services.GetConfiguration();
    var hostingEnvironment = context.Services.GetHostingEnvironment();

    //...

    //Add Hangfire
    ConfigureHangfire(context, configuration);
    //...
}

private void ConfigureHangfire(ServiceConfigurationContext context, IConfiguration configuration)
{
    context.Services.AddHangfire(config =>
    {
        config.UseSqlServerStorage(configuration.GetConnectionString("Default"));
    });
}

4. Modify the ConfigureAuthentication method to add new Cookies and OpenIdConnect authentication schemes:

private void ConfigureAuthentication(ServiceConfigurationContext context, IConfiguration configuration)
{
    context.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddAbpJwtBearer(options =>
        {
            options.Authority = configuration["AuthServer:Authority"];
            options.RequireHttpsMetadata = configuration.GetValue<bool>("AuthServer:RequireHttpsMetadata");
            options.Audience = "AbpHangfireDemoApp";

            options.ForwardDefaultSelector = httpContext => httpContext.Request.Path.StartsWithSegments("/hangfire", StringComparison.OrdinalIgnoreCase)
                ? CookieAuthenticationDefaults.AuthenticationScheme
                : null;
        })
        .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme)
        .AddAbpOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, options =>
        {
            options.Authority = configuration["AuthServer:Authority"];
            options.RequireHttpsMetadata = Convert.ToBoolean(configuration["AuthServer:RequireHttpsMetadata"]);
            options.ResponseType = OpenIdConnectResponseType.Code;

            options.ClientId = configuration["AuthServer:HangfireClientId"];
            options.ClientSecret = configuration["AuthServer:HangfireClientSecret"];

            options.UsePkce = true;
            options.SaveTokens = true;
            options.GetClaimsFromUserInfoEndpoint = true;

            options.Scope.Add("roles");
            options.Scope.Add("email");
            options.Scope.Add("phone");
            options.Scope.Add("AbpHangfireDemoApp");

            options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        });

    //...
}

5. Add a custom middleware and UseAbpHangfireDashboard after UseAuthorization in the OnApplicationInitialization method:

//...
app.UseAuthorization();

app.Use(async (httpContext, next) =>
{
    if (httpContext.Request.Path.StartsWithSegments("/hangfire", StringComparison.OrdinalIgnoreCase))
    {
        var authenticateResult = await httpContext.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);
        if (!authenticateResult.Succeeded)
        {
            await httpContext.ChallengeAsync(
                OpenIdConnectDefaults.AuthenticationScheme,
                new AuthenticationProperties
                {
                    RedirectUri = httpContext.Request.Path + httpContext.Request.QueryString
                });
            return;
        }
    }
    await next.Invoke();
});
app.UseAbpHangfireDashboard("/hangfire", options =>
{
    options.AsyncAuthorization = new[]
    {
        new AbpHangfireAuthorizationFilter()
    };
});

//...

Perfect! 🎉 Now you can run the AuthServer and API projects and access the Hangfire Dashboard at https://localhost:44371/hangfire.

Note: Replace 44371 with your API project's port.

The first time you access the Hangfire Dashboard, you'll be redirected to the login page of the AuthServer project. After you log in, you'll be redirected back to the Hangfire Dashboard.

Key Points 🔑

1. Authentication Scheme Selection

The default authentication scheme in API websites is JWT Bearer. We've implemented Cookies and OpenIdConnect specifically for the Hangfire Dashboard.

We've configured the JwtBearerOptions's ForwardDefaultSelector to use CookieAuthenticationDefaults.AuthenticationScheme for Hangfire Dashboard requests.

This means that if the request path starts with /hangfire, the request will be authenticated using the Cookies authentication scheme; otherwise, it will use the JwtBearer authentication scheme.

options.ForwardDefaultSelector = httpContext => httpContext.Request.Path.StartsWithSegments("/hangfire", StringComparison.OrdinalIgnoreCase)
    ? CookieAuthenticationDefaults.AuthenticationScheme
    : null;

2. Custom Middleware for Authentication

We've also implemented a custom middleware to handle Cookies authentication for the Hangfire Dashboard. If the current request isn't authenticated with the Cookies authentication scheme, it will be redirected to the login page.

app.Use(async (httpContext, next) =>
{
    if (httpContext.Request.Path.StartsWithSegments("/hangfire", StringComparison.OrdinalIgnoreCase))
    {
        var authenticateResult = await httpContext.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);
        if (!authenticateResult.Succeeded)
        {
            await httpContext.ChallengeAsync(
                OpenIdConnectDefaults.AuthenticationScheme,
                new AuthenticationProperties
                {
                    RedirectUri = httpContext.Request.Path + httpContext.Request.QueryString
                });
            return;
        }
    }
    await next.Invoke();
});

References 📚

• ABP Hangfire Background Job Manager
• Use cookie authentication in ASP.NET Core

This article demonstrates how to integrate the .NET AI Chat Template into an ABP Framework application, enabling powerful AI chat capabilities in your ABP-based solution.

Step 1: Create a New ABP Project

First, let's create a new single-layer Blazor Server project named AbpAiChat using ABP Studio, You can also use the following ABP CLI command to create the project:

abp new AbpAiChat -t app-nolayers --ui-framework blazor-server --use-open-source-template

Step 2: Integrate AI Chat Template

The integration process involves copying and adapting the .NET AI Chat Template code into our ABP project. The template code is already included in our sample project, so you don't need to install it separately.

2.1 Project Structure Changes

1. Copy Blazor components to the Components folder
2. Copy AI service classes to the Services folder
3. Add required entities(IngestedDocument, IngestedRecord) to the AbpAiChatDbContext and add new migration
4. Copy frontend resources to the wwwroot folder
5. Adjust some styles to capatible with the ABP theme

2.2 Required NuGet Packages

Add the following packages to AbpAiChat.csproj:

<PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.4.3-preview.1.25230.7" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.4" />
<PackageReference Include="Microsoft.Extensions.AI" Version="9.4.3-preview.1.25230.7" />
<PackageReference Include="Microsoft.SemanticKernel.Core" Version="1.47.0" />
<PackageReference Include="PdfPig" Version="0.1.9" />
<PackageReference Include="System.Linq.Async" Version="6.0.1" />

2.3 Configure AI Services

Add the following configuration to AbpAiChatModule.cs:

private void ConfigureAi(ServiceConfigurationContext context)
{
    var credential = new ApiKeyCredential(context.Services.GetConfiguration()["GitHubToken"] ?? throw new InvalidOperationException("Missing configuration: GitHubToken. See the README for details."));
    var openAiOptions = new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://models.inference.ai.azure.com")
    };

    var ghModelsClient = new OpenAIClient(credential, openAiOptions);
    var chatClient = ghModelsClient.GetChatClient("gpt-4o-mini").AsIChatClient();
    var embeddingGenerator = ghModelsClient.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator();

    var vectorStore = new JsonVectorStore(Path.Combine(AppContext.BaseDirectory, "vector-store"));

    context.Services.AddSingleton<IVectorStore>(vectorStore);
    context.Services.AddScoped<DataIngestor>();
    context.Services.AddSingleton<SemanticSearch>();
    context.Services.AddChatClient(chatClient).UseFunctionInvocation().UseLogging();
    context.Services.AddEmbeddingGenerator(embeddingGenerator);

    context.Services.Configure<AbpAspNetCoreContentOptions>(options =>
    {
        options.ContentTypeMaps.Add(".mjs", "application/javascript");
    });
}

The ConfigureAi method is called in the ConfigureServices method of AbpAiChatModule. It sets up the AI services, including the OpenAI client, chat client, embedding generator, and vector store.

2.4 Configure GitHub Token

Add your GitHub Personal Access Token to appsettings.json:

{
    "GitHubToken": "your-github-token"
}

You can obtain your token from GitHub Personal Access Tokens.

Step 3: Add Custom AI Functionality

Let's add a custom AI function to retrieve the current user's information. Update the Chat.razor component:

chatOptions.Tools =
[
    AIFunctionFactory.Create(SearchAsync),
    AIFunctionFactory.Create(GetWeather),
    AIFunctionFactory.Create(GetCurrentUserInfo)
];

[Description("Get current user information")]
private Task<string> GetCurrentUserInfo()
{
    return Task.FromResult(CurrentUser.IsAuthenticated ?
        $"UserId: {CurrentUser.Id}, Name: {CurrentUser.UserName}, Email: {CurrentUser.Email}, Roles: {string.Join(", ", CurrentUser.Roles)}" :
        "No user information available.");
}

Step 4: Add Navigation

Add a Chat menu item in AbpAiChatMenuContributor to navigate to the AI Chat component.

Running the Application

After completing the integration, you can run the application and access the AI chat functionality. The chat interface allows you to:

• Get weather information
• Ask questions about PDF content
• Retrieve current user information
• And more!

Conclusion

This integration demonstrates how to leverage the power of AI in your ABP Framework applications. The .NET AI Chat Template provides a solid foundation for building intelligent chat interfaces, and ABP Framework makes it more powerful.

References

• ABP Single Layer Solution
• .NET AI Template Documentation
• GitHub Personal Access Tokens Guide

Source Code

• AbpAiChat Source Code

The ABP Framework provides multi-tenancy support with various ways to resolve tenant information, including: Cookie, Header, Domain, Route, and more.

This article will demonstrate how to resolve tenant information from the route.

Tenant Information in Routes

In the ABP Framework, tenant information in routes is handled by the RouteTenantResolveContributor.

Let's say your application is hosted at https://abp.io and you have a tenant named acme. You can add the {__tenant} variable to your controller or page routes like this:

[Route("{__tenant}/[Controller]")]
public class MyController : MyProjectNameController
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("Hello My Page");
    }
}

@page "{__tenant?}/mypage"
@model MyPageModel

<html>
<body>
    <h1>My Page</h1>
</body>
</html>

When you access https://abp.io/acme/my or https://abp.io/acme/mypage, ABP will automatically resolve the tenant information from the route.

Adding __tenant to Global Routes

While we've shown how to add {__tenant} to individual controllers or pages, you might want to add it globally to your entire application. Here's how to implement this:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace MyCompanyName;

public class AddTenantRouteToPages : IPageRouteModelConvention, IApplicationModelConvention
{
    public void Apply(PageRouteModel model)
    {
        var selectorCount = model.Selectors.Count;
        var selectorModels = new List<SelectorModel>();
        for (var i = 0; i < selectorCount; i++)
        {
            var selector = model.Selectors[i];
            selectorModels.Add(new SelectorModel
            {
                AttributeRouteModel = new AttributeRouteModel
                {
                    Template = AttributeRouteModel.CombineTemplates("{__tenant:regex(^[a-zA-Z0-9]+$)}", selector.AttributeRouteModel!.Template!.RemovePreFix("/"))
                }
            });
        }
        foreach (var selectorModel in selectorModels)
        {
            model.Selectors.Add(selectorModel);
        }
    }
}

public class AddTenantRouteToControllers :IApplicationModelConvention
{
    public void Apply(ApplicationModel application)
    {
        var controllers = application.Controllers;
        foreach (var controller in controllers)
        {
            var selector = controller.Selectors.FirstOrDefault();
            if (selector == null || selector.AttributeRouteModel == null)
            {
                controller.Selectors.Add(new SelectorModel
                {
                    AttributeRouteModel = new AttributeRouteModel
                    {
                        Template = AttributeRouteModel.CombineTemplates("{__tenant:regex(^[[a-zA-Z0-9]]+$)}", controller.ControllerName)
                    }
                });
                controller.Selectors.Add(new SelectorModel
                {
                    AttributeRouteModel = new AttributeRouteModel
                    {
                        Template = controller.ControllerName
                    }
                });
            }
            else
            {
                var template = selector.AttributeRouteModel?.Template;
                template = template.IsNullOrWhiteSpace() ? "{__tenant:regex(^[[a-zA-Z0-9]]+$)}" : AttributeRouteModel.CombineTemplates("{__tenant:regex(^[[a-zA-Z0-9]]+$)}", template.RemovePreFix("/"));
                controller.Selectors.Add(new SelectorModel
                {
                    AttributeRouteModel = new AttributeRouteModel
                    {
                        Template = template
                    }
                });
            }
        }
    }
}

Register the services:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    //...
    
    PostConfigure<RazorPagesOptions>(options =>
    {
        options.Conventions.Add(new AddTenantRouteToPages());
    });

    PostConfigure<MvcOptions>(options =>
    {
        options.Conventions.Add(new AddTenantRouteToControllers());
    });
    
    // Configure cookie path to prevent authentication cookie loss
    context.Services.ConfigureApplicationCookie(x =>
    {
        x.Cookie.Path = "/";
    });
    //...
}

After implementing this, you'll notice that all controllers in your Swagger UI will have the {__tenant} route added:

Handling Navigation Links

To ensure navigation links automatically include tenant information, we need to add middleware that dynamically adds the tenant to the PathBase:

public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    //...
    app.Use(async (httpContext, next) =>
    {
        var tenantMatch = Regex.Match(httpContext.Request.Path, "^/([^/.]+)(?:/.*)?$");
        if (tenantMatch.Groups.Count > 1 && !string.IsNullOrEmpty(tenantMatch.Groups[1].Value))
        {
            var tenantName = tenantMatch.Groups[1].Value;
            if (!tenantName.IsNullOrWhiteSpace())
            {
                var tenantStore = httpContext.RequestServices.GetRequiredService<ITenantStore>();
                var tenantNormalizer = httpContext.RequestServices.GetRequiredService<ITenantNormalizer>();
                var tenantInfo = await tenantStore.FindAsync(tenantNormalizer.NormalizeName(tenantName)!);
                if (tenantInfo != null)
                {
                    if (httpContext.Request.Path.StartsWithSegments(new PathString(tenantName.EnsureStartsWith('/')), out var matchedPath, out var remainingPath))
                    {
                        var originalPath = httpContext.Request.Path;
                        var originalPathBase = httpContext.Request.PathBase;
                        httpContext.Request.Path = remainingPath;
                        httpContext.Request.PathBase = originalPathBase.Add(matchedPath);
                        try
                        {
                            await next(httpContext);
                        }
                        finally
                        {
                            httpContext.Request.Path = originalPath;
                            httpContext.Request.PathBase = originalPathBase;
                        }
                        return;
                    }
                }
            }
        }

        await next(httpContext);
    });
    app.UseRouting();
    app.MapAbpStaticAssets();
    //...
}

After setting the PathBase, we need to add a custom tenant resolver to extract tenant information from the PathBase:

public class MyRouteTenantResolveContributor : RouteTenantResolveContributor
{
    public const string ContributorName = "MyRoute";

    public override string Name => ContributorName;

    protected override Task<string?> GetTenantIdOrNameFromHttpContextOrNullAsync(ITenantResolveContext context, HttpContext httpContext)
    {
        var tenantId = httpContext.GetRouteValue(context.GetAbpAspNetCoreMultiTenancyOptions().TenantKey) ?? httpContext.Request.PathBase.ToString();
        var tenantIdStr = tenantId?.ToString()?.RemovePreFix("/");
        return Task.FromResult(!tenantIdStr.IsNullOrWhiteSpace() ? Convert.ToString(tenantIdStr) : null);
    }
}

Register the MyRouteTenantResolveContributor with the ABP Framework:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    //...
    Configure<AbpTenantResolveOptions>(options =>
    {
        options.TenantResolvers.Add(new MyRouteTenantResolveContributor());
    });
    //...
}

Modifying abp.appPath

public override void ConfigureServices(ServiceConfigurationContext context)
{
    //...
    context.Services.AddOptions<AbpThemingOptions>().Configure<IServiceProvider>((options, rootServiceProvider) =>
    {
        var currentTenant = rootServiceProvider.GetRequiredService<ICurrentTenant>();
        if (!currentTenant.Name.IsNullOrWhiteSpace())
        {
            options.BaseUrl = currentTenant.Name.EnsureStartsWith('/').EnsureEndsWith('/');
        }
    });

    context.Services.RemoveAll(x => x.ServiceType == typeof(IOptions<AbpThemingOptions>));
    context.Services.Add(ServiceDescriptor.Scoped(typeof(IOptions<>), typeof(OptionsManager<>)));
    //...
}

Browser console output:

> https://localhost:44303/acme/
> abp.appPath
> '/acme/'

Summary

By following these steps, you can implement tenant resolution from routes in the ABP Framework and handle navigation links appropriately. This approach provides a clean and maintainable way to manage multi-tenancy in your application.

References

• ABP Multi-Tenancy
• Routing in ASP.NET Core
• HTML base tag

When implementing JWT Bearer authentication in an ABP(tiered) application, you might occasionally encounter errors starting with IDX. These errors are related to JWT Bearer Token validation and this article will help you understand and resolve them.

Enable JWT Bearer authentication

Your API project usually contains the following code, which enables JWT Bearer authentication and makes it as the default authentication scheme.

We simply configure the JWT's Authority and Audience properties, and it will work fine.

context.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
	.AddJwtBearer(options =>
	{
		options.Authority = "https://localhost:44301/"; //configuration["AuthServer:Authority"];
		options.Audience = "MyProjectName";
	});

AddJwtBearer and AddAbpJwtBearer will do the same thing, but AddAbpJwtBearer is recommended.

JWT authentication process

Let's take a look at how the above code works.

A JWT Token usually consists of three parts: Header, Payload, and Signature.

• Header: Contains the type and signing algorithm of the token
• Payload: Contains the claims of the token, including sub, aud, exp, iat, iss, jti, preferred_username, given_name, role, email, etc.
• Signature: The cryptographic signature of the token used to verify its authenticity

Here is an example of a JWT Token issued by AuthServer(OpenIddict):

The Header part:

The Payload part:

TokenValidationParameters

In the JwtBearerOptions, there is a TokenValidationParameters property, which is used to validate the JWT Token.

The default implementation for JWT Token validation is JsonWebTokenHandler, which comes from the Microsoft.IdentityModel.JsonWebTokens package.

We didn't set the TokenValidationParameters property in the code above, so the default values below will be used:

//...
TokenValidationParameters.ValidateAudience = true
TokenValidationParameters.ValidAudience = "MyProjectName"
TokenValidationParameters.ValidAudiences = null

TokenValidationParameters.ValidateIssuer = true
TokenValidationParameters.ValidIssuer = null
TokenValidationParameters.ValidIssuers = null
//...

JWT Bearer Token Validation Process

During JWT Bearer authentication, API website will get the token from the HTTP request and validate it.

The JsonWebTokenHandler will get the OpenID Connect metadata from the AuthServer, it will be used in the validation process, the current metadata request address is: https://localhost:44301/.well-known/openid-configuration , it is a fixed address calculated from the Authority property.

First, the token's Signature is verified using the public key obtained from OpenID Connect metadata(https://localhost:44301/.well-known/jwks).

Then, the payload is validated. The payload is a JSON object containing essential information such as the token type, expiration time, issuer, and audience etc.

Most of the validation problems we may encounter are payload validation failures, for example:

Lifetime

If the token in your request has expired, the validation will fail. You will see the exception information like IDX10230 in the log.

Audience

The ValidAudience of TokenValidationParameters is MyProjectName, the aud in the payload of the token is also MyProjectName, if the token does not contain aud or the aud does not match, the validation will fail. You may see the exception information like IDX10206, IDX10277 or IDX10208.

If the ValidateAudience of TokenValidationParameters is false, then the aud will not be validated.

Issuer

The default value of TokenValidationParameters.ValidateIssuer is true, it requires the token's payload to contain the issuer field, and it must match one of TokenValidationParameters.ValidIssuer or TokenValidationParameters.ValidIssuers.

The default value of ValidIssuer or ValidIssuers is null, it will use the issuer from the OpenID Connect metadata as the default value.

1. If the token's payload does not contain the issuer field, you may see the error IDX10211.
2. If the API website cannot get the OpenID Connect metadata from AuthServer website, the validation will fail. You may see the error IDX10204, the full exception message is: IDX10204: Unable to validate issuer. validationParameters.ValidIssuer is null or whitespace AND validationParameters.ValidIssuers is null or empty.
3. If the issuer does not match, the validation will fail. You may see the error IDX10205 in the log.

If the ValidateIssuer of TokenValidationParameters is false, then the issuer will not be validated.

Please note that OpenIddict will use the current HTTP request information as the value of issuer. If the AuthServer website is deployed behind a reverse proxy or similar deployment configurations, the issuer in the token may not be the value you expect. In this case, please specify it manually.

PreConfigure<OpenIddictServerBuilder>(serverBuilder =>
{
	serverBuilder.SetIssuer("https://localhost:44301/");
});

Troubleshooting

To troubleshoot any IDX errors during JWT authentication, you can enable detailed logging by configuring the identitymodel logs as follows:

using System.Diagnostics.Tracing;
using Microsoft.IdentityModel.Logging;

public class Program
{
    public async static Task<int> Main(string[] args)
    {
        IdentityModelEventSource.ShowPII = true;
        IdentityModelEventSource.Logger.LogLevel = EventLevel.Verbose;
        var wilsonTextLogger = newTextWriterEventListener("Logs/identitymodel.txt");
        wilsonTextLogger.EnableEvents(IdentityModelEventSource.Logger, EventLevel.Verbose);

		//...
    }
}

Additionally, you can enable OpenIddict's Verbose logs for more detailed debugging information:

var loggerConfiguration = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Warning)
    .MinimumLevel.Override("OpenIddict", LogEventLevel.Verbose)
    .Enrich.FromLogContext()
    .WriteTo.Async(c => c.File("Logs/logs.txt"))

Summary

For JWT authentication, you need to pay attention to the following key points:

1. Ensure your API website can communicate with the AuthServer properly
2. Verify that the aud claim in your token matches the expected audience
3. Confirm that the issuer claim in your token is valid and matches the configuration

You can customize the JwtBearerOptions's TokenValidationParameters to modify the validation rules to meet your actual needs.

For example, if your issuer needs to support multiple subdomains, you can use the Owl.TokenWildcardIssuerValidator library to customize the validation.

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://abp.io";
        options.Audience = "abp_io";

        options.TokenValidationParameters.IssuerValidator = TokenWildcardIssuerValidator.IssuerValidator;
        options.TokenValidationParameters.ValidIssuers = new[]
        {
            "https://{0}.abp.io"
        };
    });

References

• Configure JWT bearer authentication in ASP.NET Core
• OpenIddict
• IdentityModel
• Owl.TokenWildcardIssuerValidator

When developing multi-timezone applications, we need to handle users from different time zones and make sure they see the correct time. The system also needs to support users changing their timezone (like when traveling or moving) and make sure all time displays update correctly to show accurate time information.

All these scenarios require us to handle timezone conversions correctly in our application. The ABP framework provides a complete solution for these challenges.

In this article, we'll show you step by step how to handle multi-timezone in the ABP framework.

The content mentioned in this article will be available after the ABP 9.2 version

Timezone Settings

The ABP framework provides a setting called Abp.Timing.TimeZone for setting and getting the timezone of users, tenants, or applications. The default value is empty, which means the application will use the server's time zone. Check out the Timing documentation for more information.

ISO 8601 Date Time Format

Different countries and regions may use different time formats:

• Year-Month-Day (YYYY-MM-DD): Mainly used in China, Japan, Korea, Canada (official standard), Germany (ISO standard), ISO 8601 international standard, etc. Example: 2025-03-11
• Day-Month-Year (DD-MM-YYYY): Mainly used in UK, India, Australia, New Zealand, most European countries (like France, Germany, Italy, Spain), some South American countries, etc. Example: 11-03-2025 or 11/03/2025
• Month-Day-Year (MM-DD-YYYY): Mainly used in USA, Philippines, some parts of Canada, etc. Example: 03-11-2025 or 03/11/2025
• Day.Month.Year (DD.MM.YYYY): Mainly used in Germany, Russia, Switzerland, Hungary, Czech Republic, etc. Example: 11.03.2025

Also, different countries/regions might use different separators (like slash /, hyphen -, dot .), and some countries use different month abbreviations or full names (like March 11, 2025).

ISO 8601 uses a standard format to avoid confusion between different date formats and ensure global compatibility.

It has 4 parts:

• Date part: YYYY-MM-DD
• T as a separator
• Time part: HH:MM:SS
• Timezone part: Z or +/-HH:MM

You'll usually see formats like: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS+/-HH:MM, for example: 2025-03-11T10:30:00Z or 2025-03-11T22:30:00+03:00

When our application needs to handle multiple timezones, we usually use ISO 8601 to represent time.

Enabling Multi-Timezone Support

When we set the Kind of AbpClockOptions to DateTimeKind.Utc, the ABP framework will normalize all times. Times written to the database and returned to the frontend will be in UTC. the SupportsMultipleTimezone property will be true in the IClock service.

Configure<AbpClockOptions>(options =>
{
    options.Kind = DateTimeKind.Utc;
});

Using DateTime to Store Time

Assuming the DateTime stored in the database is 2025-03-01 10:30:00, then the time returned to the front end will be 2025-03-01T10:30:00Z. This is a time in ISO 8601 format. Because DateTime does not have timezone information, the framework will assume it is UTC time.

Using DateTimeOffset to Store Time

If you use DateTimeOffset to store time, the ABP framework will not normalize DateTimeOffset, but will return it directly to the front end.

Assuming the DateTimeOffset stored in the database is 2025-03-01 13:30:00 +03:00, then the time returned to the front end will be 2025-03-01T13:30:00+03:00. This is also a time in ISO 8601 format.

We recommend using DateTimeOffset to store time because it has timezone information.

Timezone Conversion

Converting UTC Time to User Time

The IClock service has 2 methods to convert a given UTC time to the user time:

DateTime ConvertToUserTime(utcDateTime dateTime)
DateTimeOffset ConvertToUserTime(DateTimeOffset dateTimeOffset)

If SupportsMultipleTimezone is false or dateTime.Kind is not Utc or no timezone is set, it will return the given DateTime or DateTimeOffset without any changes.

Example:

If the user's timezone is Europe/Istanbul

// 2025-03-01T05:30:00Z
var utcTime = new DateTime(2025, 3, 1, 5, 30, 0, DateTimeKind.Utc);

var userTime = Clock.ConvertToUserTime(utcTime);

// Europe/Istanbul has 3 hours difference with UTC. So, the result will be 3 hours later.
userTime.Kind.ShouldBe(DateTimeKind.Unspecified);
userTime.ToString("O").ShouldBe("2025-03-01T08:30:00");

// 2025-03-01T05:30:00Z
var utcTime = new DateTimeOffset(new DateTime(2025, 3, 1, 5, 30, 0, DateTimeKind.Utc), TimeSpan.Zero);

var userTime = Clock.ConvertToUserTime(utcTime);

// Europe/Istanbul has 3 hours difference with UTC. So, the result will be 3 hours later.
userTime.Offset.ShouldBe(TimeSpan.FromHours(3));
userTime.ToString("O").ShouldBe("2025-03-01T08:30:00.0000000+03:00");

Converting User Time to UTC

The IClock service has 1 method to convert a given user time to UTC.

DateTime ConvertToUtc(DateTime dateTime)

If SupportsMultipleTimezone is false or dateTime.Kind is Utc or no timezone is set, it will return the given DateTime without any changes.

Example:

If the user's timezone is Europe/Istanbul

// 2025-03-01T05:30:00
var userTime = new DateTime(2025, 3, 1, 5, 30, 0, DateTimeKind.Unspecified); //Same as Local

var utcTime = Clock.ConvertToUtc(userTime);

// Europe/Istanbul has 3 hours difference with UTC. So, the result will be 3 hours earlier.
utcTime.Kind.ShouldBe(DateTimeKind.Utc);
utcTime.ToString("O").ShouldBe("2025-03-01T02:30:00.0000000Z");

Handling Timezone in Different UIs

We'll use the TimeZoneApp project to demonstrate handling timezone in different UIs. It has a Meeting entity, with several time properties.

public class Meeting : AggregateRoot<Guid>
{
    public string Subject { get; set; }

    public DateTime StartTime { get; set; }

    public DateTime EndTime { get; set; }

    public DateTime ActualStartTime { get; set; }

    public DateTime? CanceledTime { get; set; }

    public DateTimeOffset ReminderTime { get; set; }

    public DateTimeOffset? FollowUpTime { get; set; }

    public string Description { get; set; }
}

TimeZoneApp project is an ABP layered architecture project, it sets a global Europe/Istanbul timezone, it contains 4 websites

• API.Host: API website, it does not have UI, it returns data in JSON format
• AuthServer: Authentication server, it uses Razor Pages as UI
• Web: Razor Pages website, it uses JavaScript to manage Meeting creation and editing and display
• Blazor: Blazor Server website, it uses Blazor to manage Meeting creation and editing and display

All 4 applications are enabled for multi-timezone support, and use the UseAbpTimeZone middleware.

Blazor WASM and Angular do not need to use the UseAbpTimeZone middleware

DateTime in API Response

In the API response, we usually use the ISO 8601 format time, as you can see, after enabling multi-timezone support, the API returns time to the front end as UTC time.

2025-03-01T09:30:00Z and 2025-03-01T12:30:00+00:00 are ISO 8601 format time.

[
  {
    "subject": "ABP Developer Guide",
    "startTime": "2025-03-01T09:30:00Z",
    "endTime": "2025-03-01T10:30:00Z",
    "actualStartTime": "2025-03-01T11:30:00Z",
    "canceledTime": null,
    "reminderTime": "2025-03-01T12:30:00+00:00",
    "followUpTime": "2025-03-01T13:30:00+00:00",
    "description": "We will discuss the ABP developer guide.",
    "id": "2af0abd3-be06-ecff-5d4c-3a1895ac7950"
  },
  {
    "subject": "ABP Training",
    "startTime": "2025-03-01T09:30:00Z",
    "endTime": "2025-03-01T10:30:00Z",
    "actualStartTime": "2025-03-01T11:30:00Z",
    "canceledTime": "2025-03-01T12:00:00Z",
    "reminderTime": "2025-03-01T12:30:00+00:00",
    "followUpTime": "2025-03-01T13:30:00+00:00",
    "description": "ABP training for the new developers.",
    "id": "290b0cb6-3e50-6324-1e79-3a1895ac795f"
  }
]

Handling Timezone in MVC/Razor Pages

In the AuthServer project, we handle time conversion in a simple way:

1. First, we get the Meeting entities from the database using IRepository<Meeting, Guid>. At this point, all DateTime values are in UTC.
2. Then, when displaying the times in the view, we use Clock.ConvertToUserTime to show them in the user's timezone.

Note: The ConvertToUserTime method will only convert times if multi-timezone support is enabled in the application.

public class IndexModel : AbpPageModel
{
    public List<Meeting>? Meetings { get; set; }

    protected IRepository<Meeting, Guid> MeetingRepository { get; }

    public IndexModel(IRepository<Meeting, Guid> meetingRepository)
    {
        MeetingRepository = meetingRepository;
    }

    public async Task OnGetAsync()
    {
        Meetings = await MeetingRepository.GetListAsync();
    }
}

<div class="container">
	<abp-row>
		<div class="table-responsive">
			<table class="table table-striped table-hover mt-3">
				<thead>
				<tr>
					<th>@L["Subject"]</th>
					<th>@L["StartTime"] / @L["EndTime"]</th>
					<th>@L["ActualStartTime"]</th>
					<th>@L["CanceledTime"]</th>
					<th>@L["ReminderTime"]</th>
					<th>@L["FollowUpTime"]</th>
					<th>@L["Description"]</th>
				</tr>
				</thead>
				<tbody>
				@foreach (var meeting in Model.Meetings)
				{
					<tr>
						<td>@meeting.Subject</td>
						<td>@Clock.ConvertToUserTime(meeting.StartTime) ➡️ @Clock.ConvertToUserTime(meeting.EndTime)</td>
						<td>@Clock.ConvertToUserTime(meeting.ActualStartTime)</td>
						<td>@(meeting.CanceledTime.HasValue ? Clock.ConvertToUserTime(meeting.CanceledTime.Value) : "N/A")</td>
						<td>@Clock.ConvertToUserTime(meeting.ReminderTime).DateTime</td>
						<td>@(meeting.FollowUpTime.HasValue ? Clock.ConvertToUserTime(meeting.FollowUpTime.Value).DateTime : "N/A")</td>
						<td>@meeting.Description</td>
					</tr>
				}
				</tbody>
			</table>
		</div>
	</abp-row>
</div>

Handling Timezone in JavaScript

In the Web project, we use JavaScript to handle timezone.

Displaying Time in UI

• timeZoneApp.meetings.meeting.getList gets all Meeting entities and displays them in DataTables
• abp.clock.normalizeToLocaleString() is the ABP JavaScript API, it converts UTC time to the current user's timezone, and then calls its toLocaleString method to format time
• dataFormat: "datetime" is the ABP DataTable extension method, it calls the abp.clock.normalizeToLocaleString method to convert and format time

If the current application is not enabled for multi-timezone support, then the abp.clock.normalizeToLocaleString method will not convert the time, it will just call the Date object's toLocaleString method.

var dataTable = $('#MeetingsTable').DataTable(
	abp.libs.datatables.normalizeConfiguration({
		serverSide: true,
		paging: true,
		order: [[1, "asc"]],
		searching: false,
		scrollX: true,
		ajax: abp.libs.datatables.createAjax(timeZoneApp.meetings.meeting.getList),
		columnDefs: [
			{
				title: l('Actions'),
				rowAction: {
					items:
						[
							{
								text: l('Edit'),
								visible: abp.auth.isGranted('TimeZoneApp.Meetings.Edit'),
								action: function (data) {
									editModal.open({ id: data.record.id });
								},
							},
							{
								text: l('Delete'),
								visible: abp.auth.isGranted('TimeZoneApp.Meetings.Delete'),
								confirmMessage: function (data) {
									return l('MeetingDeletionConfirmationMessage', data.record.subject);
								},
								action: function (data) {
									timeZoneApp.meetings.meeting
										.delete(data.record.id)
										.then(function() {
											abp.notify.info(l('SuccessfullyDeleted'));
											dataTable.ajax.reload();
										});
								}
							}
						]
				}
			},
			{
				title: l('Subject'),
				data: "subject"
			},
			{
				title: l('StartTime') + ' / ' + l('StartTime'),
				data: "startTime",
				render: function (data, type, row) {
					return abp.clock.normalizeToLocaleString(row.startTime) + ' ➡️ ' + abp.clock.normalizeToLocaleString(row.endTime);
				}
			},
			{
				title: l('ActualStartTime'),
				data: "actualStartTime",
				dataFormat: "datetime"
			},
			{
				title: l('CanceledTime'),
				data: "canceledTime",
				render: function (data, type, row) {
					return data ? abp.clock.normalizeToLocaleString(data) : 'N/A';
				}
			},
			{
				title: l('ReminderTime'),
				data: "reminderTime",
				dataFormat: "datetime"
			},
			{
				title: l('FollowUpTime'),
				data: "followUpTime",
				render: function (data, type, row) {
					return data ? abp.clock.normalizeToLocaleString(data) : 'N/A';
				}
			},
			{
				title: l('Description'),
				data: "description"
			}
		]
	})
);

Below is the screenshot of DataTables:

Creating and Editing Meeting

We use JavaScript to create and edit Meeting.

ABP's TagHelper can automatically create forms based on the model, it will generate corresponding HTML tags based on the attributes in the model. For DateTime and DateTimeOffset attributes, it will generate and initialize a DateTimePicker component.

CreateModal and EditModal :

<abp-dynamic-form abp-model="Meeting" asp-page="/Meetings/CreateModal"> 
    <abp-modal>
        <abp-modal-header title="@L["NewMeeting"].Value"></abp-modal-header>
        <abp-modal-body>
            <abp-form-content />
        </abp-modal-body>
        <abp-modal-footer buttons="@(AbpModalButtons.Cancel|AbpModalButtons.Save)"></abp-modal-footer>
    </abp-modal>
</abp-dynamic-form>

<abp-dynamic-form abp-model="Meeting" asp-page="/Meetings/EditModal">
    <abp-modal>
        <abp-modal-header title="@L["Update"].Value"></abp-modal-header>
        <abp-modal-body>
            <abp-input asp-for="Id" />
            <abp-form-content />
        </abp-modal-body>
        <abp-modal-footer buttons="@(AbpModalButtons.Cancel|AbpModalButtons.Save)"></abp-modal-footer>
    </abp-modal>
</abp-dynamic-form>

You can see that the time in the control has been converted to the current user's timezone.

When we submit the form, we need to convert the time to UTC. In the JavaScript of the Create and Edit pages, we use the handleDatepicker this jQuery extension method to handle time in the form, it internally gets the user's local time from the selector input[type="hidden"][data-hidden-datepicker], and then uses the abp.clock.normalizeToString method to convert the date field in the form to the ISO 8601 format UTC time string.

If the current application is not enabled for multi-timezone support, then the abp.clock.normalizeToString method will not convert the time, it will just convert to the ISO 8601 format time string without timezone.

var abp = abp || {};
$(function () {
    abp.modals.meetingCreate = function () {
        var initModal = function (publicApi, args) {
            var $form = publicApi.getForm();
            $form.find('button[type="submit"]').on('click', function (e) {
                $form.handleDatepicker('input[type="hidden"][data-hidden-datepicker]');
            });
        };

        return {
            initModal: initModal
        }
    };
});

The requested data is as follows:

Request URL: Meetings/EditModal
Request Method: POST
Payload:
	Id: 0803780b-3762-2af8-1c75-3a1895d59c89
	Meeting.Subject: ABP Developer Guide
	Meeting.StartTime: 2025-03-01T09:30:00.000Z
	Meeting.EndTime: 2025-03-01T10:30:00.000Z
	Meeting.ActualStartTime: 2025-03-01T11:30:00.000Z
	Meeting.CanceledTime: 
	Meeting.ReminderTime: 2025-03-01T12:30:00.000Z
	Meeting.FollowUpTime: 2025-03-01T13:30:00.000Z
	Meeting.Description: We will discuss the ABP developer guide.

In short, we use the abp.clock.normalizeToLocaleString method to display time, and use the abp.clock.normalizeToString method to modify the time to be submitted. If you submit data via ajax, please remember to use the abp.clock.normalizeToString method to convert time.

Handling Timezone in Blazor

We cannot automatically complete some work in Blazor UI, we need to inject IClock and use the ConvertToUserTime and ConvertToUtc methods to display and create/update entities.

Below is a complete Meeting page, please refer to the usage of Clock in it.

@page "/meetings"
@using Volo.Abp.Application.Dtos
@using Microsoft.Extensions.Localization
@using TimeZoneApp.Meetings
@using TimeZoneApp.Localization
@using TimeZoneApp.Permissions
@using Volo.Abp.AspNetCore.Components.Web
@inject IStringLocalizer<TimeZoneAppResource> L
@inject AbpBlazorMessageLocalizerHelper<TimeZoneAppResource> LH
@inherits AbpCrudPageBase<IMeetingAppService, MeetingDto, Guid, PagedAndSortedResultRequestDto, CreateUpdateMeetingDto>

<Card>
    <CardHeader>
        <Row Class="justify-content-between">
            <Column ColumnSize="ColumnSize.IsAuto">
                <h2>@L["Meetings"]</h2>
            </Column>
            <Column ColumnSize="ColumnSize.IsAuto">
                @if (HasCreatePermission)
                {
                    <Button Color="Color.Primary" Clicked="OpenCreateModalAsync">@L["NewMeeting"]</Button>
                }
            </Column>
        </Row>
    </CardHeader>
    <CardBody>
        <DataGrid TItem="MeetingDto"
                  Data="Entities"
                  ReadData="OnDataGridReadAsync"
                  TotalItems="TotalCount"
                  ShowPager="true"
                  PageSize="PageSize">
            <DataGridColumns>
                <DataGridEntityActionsColumn TItem="MeetingDto" @ref="@EntityActionsColumn">
                    <DisplayTemplate>
                        <EntityActions TItem="MeetingDto" EntityActionsColumn="@EntityActionsColumn">
                            <EntityAction TItem="MeetingDto"
                                          Text="@L["Edit"]"
                                          Visible=HasUpdatePermission
                                          Clicked="() => OpenEditModalAsync(context)" />
                            <EntityAction TItem="MeetingDto"
                                          Text="@L["Delete"]"
                                          Clicked="() => DeleteEntityAsync(context)"
                                          Visible=HasDeletePermission
                                          ConfirmationMessage="()=>GetDeleteConfirmationMessage(context)" />
                        </EntityActions>
                    </DisplayTemplate>
                </DataGridEntityActionsColumn>
                <DataGridColumn TItem="MeetingDto"
                                Field="@nameof(MeetingDto.Subject)"
                                Caption="@L["Subject"]"></DataGridColumn>
                <DataGridColumn TItem="MeetingDto"
                                Field="@nameof(MeetingDto.StartTime)"
                                Caption="@(L["StartTime"] + "/" + L["EndTime"])">
                    <DisplayTemplate>
                        @Clock.ConvertToUserTime(context.StartTime).ToString("yyyy-MM-dd HH:mm:ss") ➡️ @Clock.ConvertToUserTime(context.EndTime).ToString("yyyy-MM-dd HH:mm:ss")
                    </DisplayTemplate>
                </DataGridColumn>
                <DataGridColumn TItem="MeetingDto"
                                Field="@nameof(MeetingDto.ActualStartTime)"
                                Caption="@L["ActualStartTime"]">
                    <DisplayTemplate>
                        @Clock.ConvertToUserTime(context.ActualStartTime).ToString("yyyy-MM-dd HH:mm:ss")
                    </DisplayTemplate>
                </DataGridColumn>
                <DataGridColumn TItem="MeetingDto"
                                Field="@nameof(MeetingDto.CanceledTime)"
                                Caption="@L["CanceledTime"]">
                    <DisplayTemplate>
                        @(context.CanceledTime.HasValue ? Clock.ConvertToUserTime(context.CanceledTime.Value).ToString("yyyy-MM-dd HH:mm:ss") : "N/A")
                    </DisplayTemplate>
                </DataGridColumn>
                <DataGridColumn TItem="MeetingDto"
                                Field="@nameof(MeetingDto.ReminderTime)"
                                Caption="@L["ReminderTime"]">
                    <DisplayTemplate>
                        @(Clock.ConvertToUserTime(context.ReminderTime).ToString("yyyy-MM-dd HH:mm:ss") )
                          </DisplayTemplate>
                </DataGridColumn>
                <DataGridColumn TItem="MeetingDto"
                                Field="@nameof(MeetingDto.FollowUpTime)"
                                Caption="@L["FollowUpTime"]">
                    <DisplayTemplate>
                        @(context.FollowUpTime.HasValue ? Clock.ConvertToUserTime(context.FollowUpTime.Value).ToString("yyyy-MM-dd HH:mm:ss") : "N/A")
                    </DisplayTemplate>
                </DataGridColumn>
                <DataGridColumn TItem="MeetingDto"
                                Field="@nameof(MeetingDto.Description)"
                                Caption="@L["Description"]">
                </DataGridColumn>
            </DataGridColumns>
        </DataGrid>
    </CardBody>
</Card>

<Modal @ref="@CreateModal">
    <ModalContent IsCentered="true">
        <Form>
            <ModalHeader>
                <ModalTitle>@L["NewMeeting"]</ModalTitle>
                <CloseButton Clicked="CloseCreateModalAsync"/>
            </ModalHeader>
            <ModalBody>
                <Validations @ref="@CreateValidationsRef" Model="@NewEntity" ValidateOnLoad="false">
                    <Validation MessageLocalizer="@LH.Localize">
                        <Field>
                            <FieldLabel>@L["Subject"]</FieldLabel>
                            <TextEdit @bind-Text="@NewEntity.Subject">
                                <Feedback>
                                    <ValidationError/>
                                </Feedback>
                            </TextEdit>
                        </Field>
                    </Validation>
                    <Field>
                        <FieldLabel>@L["StartTime"] / @L["EndTime"]</FieldLabel>
                        <DatePicker TValue="DateTime?" @bind-Dates="SelectedDates" InputMode="DateInputMode.DateTime" SelectionMode="DateInputSelectionMode.Range" />
                    </Field>
                    <Field>
                        <FieldLabel>@L["ActualStartTime"]</FieldLabel>
                        <DateEdit TValue="DateTime" @bind-Date="NewEntity.ActualStartTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Field>
                        <FieldLabel>@L["CanceledTime"]</FieldLabel>
                        <DateEdit TValue="DateTime?" @bind-Date="NewEntity.CanceledTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Field>
                        <FieldLabel>@L["ReminderTime"]</FieldLabel>
                        <DateEdit TValue="DateTimeOffset" @bind-Date="NewEntity.ReminderTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Field>
                        <FieldLabel>@L["FollowUpTime"]</FieldLabel>
                        <DateEdit TValue="DateTimeOffset?" @bind-Date="NewEntity.FollowUpTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Validation MessageLocalizer="@LH.Localize">
                        <Field>
                            <FieldLabel>@L["Description"]</FieldLabel>
                            <TextEdit @bind-Text="@NewEntity.Description">
                                <Feedback>
                                    <ValidationError/>
                                </Feedback>
                            </TextEdit>
                        </Field>
                    </Validation>
                </Validations>
            </ModalBody>
            <ModalFooter>
                <Button Color="Color.Secondary"
                        Clicked="CloseCreateModalAsync">@L["Cancel"]</Button>
                <Button Color="Color.Primary"
                        Type="@ButtonType.Submit"
                        PreventDefaultOnSubmit="true"
                        Clicked="CreateEntityAsync">@L["Save"]</Button>
            </ModalFooter>
        </Form>
    </ModalContent>
</Modal>

<Modal @ref="@EditModal">
    <ModalContent IsCentered="true">
        <Form>
            <ModalHeader>
                <ModalTitle>@EditingEntity.Subject</ModalTitle>
                <CloseButton Clicked="CloseEditModalAsync"/>
            </ModalHeader>
            <ModalBody>
                <Validations @ref="@EditValidationsRef" Model="@EditingEntity" ValidateOnLoad="false">
                    <Validation MessageLocalizer="@LH.Localize">
                        <Field>
                            <FieldLabel>@L["Subject"]</FieldLabel>
                            <TextEdit @bind-Text="@EditingEntity.Subject">
                                <Feedback>
                                    <ValidationError/>
                                </Feedback>
                            </TextEdit>
                        </Field>
                    </Validation>
                    <Field>
                        <FieldLabel>@L["StartTime"] / @L["EndTime"]</FieldLabel>
                        <DatePicker TValue="DateTime?" @bind-Dates="SelectedDates" InputMode="DateInputMode.DateTime" SelectionMode="DateInputSelectionMode.Range" />
                    </Field>
                    <Field>
                        <FieldLabel>@L["ActualStartTime"]</FieldLabel>
                        <DateEdit TValue="DateTime" @bind-Date="EditingEntity.ActualStartTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Field>
                        <FieldLabel>@L["CanceledTime"]</FieldLabel>
                        <DateEdit TValue="DateTime?" @bind-Date="EditingEntity.CanceledTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Field>
                        <FieldLabel>@L["ReminderTime"]</FieldLabel>
                        <DateEdit TValue="DateTimeOffset" @bind-Date="EditingEntity.ReminderTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Field>
                        <FieldLabel>@L["FollowUpTime"]</FieldLabel>
                        <DateEdit TValue="DateTimeOffset?" @bind-Date="EditingEntity.FollowUpTime" InputMode="DateInputMode.DateTime"/>
                    </Field>
                    <Validation MessageLocalizer="@LH.Localize">
                        <Field>
                            <FieldLabel>@L["Description"]</FieldLabel>
                            <TextEdit @bind-Text="@EditingEntity.Description">
                                <Feedback>
                                    <ValidationError/>
                                </Feedback>
                            </TextEdit>
                        </Field>
                    </Validation>
                </Validations>
            </ModalBody>
            <ModalFooter>
                <Button Color="Color.Secondary"
                        Clicked="CloseEditModalAsync">@L["Cancel"]</Button>
                <Button Color="Color.Primary"
                        Type="@ButtonType.Submit"
                        PreventDefaultOnSubmit="true"
                        Clicked="UpdateEntityAsync">@L["Save"]</Button>
            </ModalFooter>
        </Form>
    </ModalContent>
</Modal>


@code {
    IReadOnlyList<DateTime?> SelectedDates;

    public Meeting()
    {
        CreatePolicyName = TimeZoneAppPermissions.Meetings.Create;
        UpdatePolicyName = TimeZoneAppPermissions.Meetings.Edit;
        DeletePolicyName = TimeZoneAppPermissions.Meetings.Delete;
    }

    protected override async Task OpenCreateModalAsync()
    {
        await base.OpenCreateModalAsync();

        var now = DateTime.Now;
        SelectedDates = new List<DateTime?> { now.Date.AddHours(10),now.Date.AddDays(7).AddHours(10) };
        NewEntity.ActualStartTime = now.Date.AddHours(11);
        NewEntity.CanceledTime = now.Date.AddHours(12);
        NewEntity.ReminderTime = now.Date.AddHours(13);
        NewEntity.FollowUpTime = now.Date.AddHours(14);
    }

    protected override Task OnCreatingEntityAsync()
    {
        if (SelectedDates.Count == 2 && SelectedDates[0].HasValue && SelectedDates[1].HasValue)
        {
            NewEntity.StartTime = Clock.ConvertToUtc(SelectedDates[0]!.Value);
            NewEntity.EndTime = Clock.ConvertToUtc(SelectedDates[1]!.Value);
        }

        NewEntity.ActualStartTime = Clock.ConvertToUtc(NewEntity.ActualStartTime);
        NewEntity.CanceledTime = NewEntity.CanceledTime.HasValue ? Clock.ConvertToUtc(NewEntity.CanceledTime.Value) : null;

        NewEntity.ReminderTime = Clock.ConvertToUtc(NewEntity.ReminderTime.DateTime);
        NewEntity.FollowUpTime = NewEntity.FollowUpTime.HasValue ? Clock.ConvertToUtc(NewEntity.FollowUpTime.Value.DateTime) : null;

        return Task.CompletedTask;
    }

    protected override async Task OpenEditModalAsync(MeetingDto entity)
    {
        await base.OpenEditModalAsync(entity);

        SelectedDates = new List<DateTime?> { Clock.ConvertToUserTime(EditingEntity.StartTime), Clock.ConvertToUserTime(EditingEntity.EndTime) };
        EditingEntity.ActualStartTime = Clock.ConvertToUserTime(EditingEntity.ActualStartTime);
        EditingEntity.CanceledTime = EditingEntity.CanceledTime.HasValue ? Clock.ConvertToUserTime(EditingEntity.CanceledTime.Value) : null;
        EditingEntity.ReminderTime = Clock.ConvertToUserTime(EditingEntity.ReminderTime);
        EditingEntity.FollowUpTime = EditingEntity.FollowUpTime.HasValue ? Clock.ConvertToUserTime(EditingEntity.FollowUpTime.Value) : null;
    }

    protected override Task OnUpdatingEntityAsync()
    {
        if (SelectedDates.Count == 2 && SelectedDates[0].HasValue && SelectedDates[1].HasValue)
        {
            EditingEntity.StartTime = Clock.ConvertToUtc(SelectedDates[0]!.Value);
            EditingEntity.EndTime = Clock.ConvertToUtc(SelectedDates[1]!.Value);
        }

        EditingEntity.ActualStartTime = Clock.ConvertToUtc(EditingEntity.ActualStartTime);
        EditingEntity.CanceledTime = EditingEntity.CanceledTime.HasValue ? Clock.ConvertToUtc(EditingEntity.CanceledTime.Value) : null;

        return Task.CompletedTask;
    }
}

Timezone Settings Change

If the timezone settings change, then all times will be converted to the new timezone. For example, if the current timezone changes from Europe/Istanbul to Europe/Berlin, then all times will be converted to the Europe/Berlin timezone.

Europe/Istanbul:

Europe/Berlin:

Browser Timezone Detection

When no timezone setting is configured, ABP's MVC, Blazor, and Angular applications will automatically detect the browser's timezone during initialization. The detected timezone is then stored in either the request's Cookie or Header.

This functionality is implemented by the UseAbpTimeZone middleware, which follows a specific order to determine the appropriate timezone:

1. First, it attempts to retrieve the timezone from the application/tenant/user settings
2. If no setting is found, it tries to get the timezone from the request information, including Cookie, Header, QueryString, and Form
3. Finally, if no timezone information is found, it falls back to using the server's timezone as the default

The timezone information is stored using the key __timezone

TimeZoneApp Source Code

You can download and view the TimeZoneApp source code for detailed implementation.

Summary

Through this article, we learned how to handle timezone in different types of UIs. I hope this article is helpful to you. If you have any questions, please contact me at any time.

Embedded Files functionality in .NET applications allows external files (like configuration files, images, etc.) to be directly embedded into assemblies (.exe or .dll). This simplifies deployment, prevents file loss or tampering, improves security and performance, and reduces path and dependency management issues. Through embedded resources, programs can access these files more conveniently without additional file operations.

Embedding Files in Your Project

We embed Volo\Abp\MyModule\Localization\*.json files into the assembly in our MyModule.csproj.

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net9.0</TargetFramework>
        <OutputType>Exe</OutputType>
        <Nullable>enable</Nullable>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.0" />
        <PackageReference Include="Volo.Abp.VirtualFileSystem" Version="9.0.0"  />
    </ItemGroup>

    <ItemGroup>
        <None Remove="Volo\Abp\MyModule\Localization\*.json" />
        <EmbeddedResource Include="Volo\Abp\MyModule\Localization\*.json" />
    </ItemGroup>

</Project>

If we check the en.json file in our IDE, we'll see it's embedded in the assembly.

When we decompile the built MyModule.dll file, we can also see the en.json file.

Accessing Embedded Files in Code

public class Program
{
    public static async Task<int> Main(string[] args)
    {
        var embeddedFiles = typeof(Program).Assembly.GetManifestResourceNames();
        foreach (var embeddedFile in embeddedFiles)
        {
            Console.WriteLine(embeddedFile);
            var fileStream = typeof(Program).Assembly.GetManifestResourceStream(embeddedFile);
            if (fileStream != null)
            {
                using var reader = new System.IO.StreamReader(fileStream);
                var content = await reader.ReadToEndAsync();
                Console.WriteLine(content);
            }
        }
    }
}

This code will output the embedded file names and their contents.

MyModule.Volo.Abp.MyModule.Localization.en.json

{
  "key":"value"
}

Integrating with ABP Virtual File System

The ABP Virtual File System makes it possible to manage files that don't physically exist on the file system (disk). It's mainly used to embed (js, css, image..) files into assemblies and use them like physical files at runtime.

The following code shows how to add embedded files from the current application assembly to the ABP virtual file system:

[DependsOn(typeof(AbpVirtualFileSystemModule))]
public class MyModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure<AbpVirtualFileSystemOptions>(options =>
        {
            options.FileSets.AddEmbedded<MyModule>();
        });
    }
}

ABP creates an AbpEmbeddedFileProvider to access the embedded files.

The full name of en.json is MyModule.Volo.Abp.MyModule.Localization.en.json. Without directory information, ABP uses . to split and assume directory information. This creates the following directory structure in the virtual file system:

[Dir] [/MyModule]
[Dir] [/MyModule/Volo]
[Dir] [/MyModule/Volo/Abp]
[Dir] [/MyModule/Volo/Abp/MyModule]
[Dir] [/MyModule/Volo/Abp/MyModule/Localization]
[File] [/MyModule/Volo/Abp/MyModule/Localization/en.json]

Now you can inject IVirtualFileProvider to access embedded files using the directory/file structure above.

Manifest Embedded File Provider

You might have noticed that using . to split and assume directory information can cause confusion if filenames contain dots.

For example, if your filename is zh.hans.json, ABP will generate the following directory structure, which isn't what we want:

[Dir] [/MyModule]
[Dir] [/MyModule/Volo]
[Dir] [/MyModule/Volo/Abp]
[Dir] [/MyModule/Volo/Abp/MyModule]
[Dir] [/MyModule/Volo/Abp/MyModule/Localization]
[Dir] [/MyModule/Volo/Abp/MyModule/Localization/zh]
[File] [/MyModule/Volo/Abp/MyModule/Localization/zh/hans.json]

Microsoft provides the Microsoft.Extensions.FileProviders.Embedded library to solve this problem.

We need to add this package dependency and set <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest> in our project:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net9.0</TargetFramework>
        <OutputType>Exe</OutputType>
        <Nullable>enable</Nullable>
        <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.0" />
        <PackageReference Include="Volo.Abp.VirtualFileSystem" Version="9.0.0"  />
        <PackageReference Include="Microsoft.Extensions.FileProviders.Embedded" Version="9.0.0" />
    </ItemGroup>

    <ItemGroup>
        <None Remove="Volo\Abp\MyModule\Localization\*.json" />
        <EmbeddedResource Include="Volo\Abp\MyModule\Localization\*.json" />
    </ItemGroup>

</Project>

After rebuilding the project, when we decompile MyModule.dll, we'll see an additional Microsoft.Extensions.FileProviders.Embedded.Manifest.xml file.

This manifest file stores all the directory and file information of embedded resources. When ABP finds this file, it will use ManifestEmbeddedFileProvider instead of AbpEmbeddedFileProvider to access embedded files:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Manifest>
    <ManifestVersion>1.0</ManifestVersion>
    <FileSystem>
        <File Name="Microsoft.Extensions.FileProviders.Embedded.Manifest.xml">
            <ResourcePath>Microsoft.Extensions.FileProviders.Embedded.Manifest.xml</ResourcePath>
        </File>
        <Directory Name="Volo">
            <Directory Name="Abp">
                <Directory Name="MyModule">
                    <Directory Name="Localization">
                        <File Name="zh.hans.json">
                            <ResourcePath>MyModule.Volo.Abp.MyModule.Localization.zh.hans.json</ResourcePath>
                        </File>
                    </Directory>
                </Directory>
            </Directory>
        </Directory>
    </FileSystem>
</Manifest>

Parameters of AddEmbedded Method

The AddEmbedded method can take two parameters:

baseNamespace

This may only be needed if you haven't used the Manifest Embedded File Provider and your project's root namespace isn't empty. In this case, set your root namespace here.

The root namespace is your project's name by default. You can change it or set it to empty in the csproj file.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <RootNamespace>MyModule</RootNamespace>
    </PropertyGroup>
</Project>

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <RootNamespace></RootNamespace>
    </PropertyGroup>
</Project>

Configure<AbpVirtualFileSystemOptions>(options =>
{
    options.FileSets.AddEmbedded<MyModule>(baseNamespace: "MyModule");
});

[Dir] [/Volo]
[Dir] [/Volo/Abp]
[Dir] [/Volo/Abp/MyModule]
[Dir] [/Volo/Abp/MyModule/Localization]
[File] [/Volo/Abp/MyModule/Localization/en.json]

baseFolder

If you don't want to expose all embedded files in the project, but only want to expose a specific folder (and sub folders/files), you can set the base folder relative to your project root folder.

baseFolder is only effective when using Manifest Embedded File Provider.

You can set the baseFolder parameter to /Volo/Abp/MyModule, resulting in this directory structure:

Configure<AbpVirtualFileSystemOptions>(options =>
{
    options.FileSets.AddEmbedded<MyModule>(baseFolder: "/Volo/Abp/MyModule");
});

[Dir] [Localization]
[File] [Localization/en.json]

Summary

We recommend using the Manifest Embedded File Provider in your projects and libraries. Hope this article has been helpful.

References

ABP Virtual File System

Manifest Embedded File Provider

This article explains how to implement reliable event handling using the Outbox/Inbox pattern in a modular monolithic application with multiple databases. We'll use the ModularCRM project as an example (how that project was created is explained in this document).

Project Background

ModularCRM is a monolithic application that integrates multiple ABP framework open-source modules, including:

• Account
• Identity
• Tenant Management
• Permission Management
• Setting Management
• And other open-source modules

Besides the ABP framework modules, the project contains three business modules:

• Order module (Ordering), using MongoDB database
• Product module (Products), using SQL Server database
• Payment module (Payment), using MongoDB database

The project configures separate database connection strings for ModularCRM and the three business modules in appsettings.json:

{
  "ConnectionStrings": {
    "Default": "Server=localhost,1434;Database=ModularCrm;User Id=sa;Password=1q2w3E***;TrustServerCertificate=true",
    "Products": "Server=localhost,1434;Database=ModularCrm_Products;User Id=sa;Password=1q2w3E***;TrustServerCertificate=true",
    "Ordering": "mongodb://localhost:27017/ModularCrm_Ordering?replicaSet=rs0",
    "Payment": "mongodb://localhost:27017/ModularCrm_Payment?replicaSet=rs0"
  }
}

Business Scenario

These modules communicate through the ABP framework's DistributedEventBus to implement the following business flow:

This is a simple example flow. Real business flows are more complex. The sample code is for demonstration purposes.

1. Order module: Publishes OrderPlacedEto event when an order is placed
2. Product module: Subscribes to OrderPlacedEto event and reduce product stock
3. Payment module: Subscribes to OrderPlacedEto event, processes payment, then publishes PaymentCompletedEto event
4. Order module: Subscribes to PaymentCompletedEto event and updates order status to Delivered

When implementing this flow, we need to ensure:

• Transaction consistency between order creation and event publishing
• Transaction consistency when modules process messages
• Reliable message delivery (including persistence, confirmation, and retry mechanisms)

Using the default implementation of the ABP framework's distributed event bus cannot meet these requirements, so we need to add a new mechanism that is also provided by the ABP Framework.

Outbox/Inbox Pattern Solution

To meet these requirements, we use the Outbox/Inbox pattern:

Outbox Pattern

• Saves distributed events with database operations in the same transaction
• Sends events to distributed message service through background jobs
• Ensures consistency between data updates and event publishing
• Prevents message loss during system failures

Inbox Pattern

• First saves received distributed events to the database
• Processes events in a transactional way
• Ensures messages are processed only once by saving processed message records
• Maintains processing state for reliable handling

For how to enable and configure Outbox/Inbox in projects and modules, see: https://abp.io/docs/latest/framework/infrastructure/event-bus/distributed#outbox-inbox-for-transactional-events

Module Configuration

Each module needs to configure separate Outbox/Inbox. Since it's a monolithic application, all message processing classes are in the same project, so we need to configure Outbox/Inbox for each module with Selector/EventSelector to ensure that the module only sends and receives the messages it cares about, avoiding message duplication processing.

ModularCRM Main Application Configuration

It will send and receive messages from all ABP framework open-source modules.

// This selector will match all abp built-in modules and the current module.
Func<Type, bool> abpModuleSelector = type => type.Namespace != null && (type.Namespace.StartsWith("Volo.") || type.Assembly == typeof(ModularCrmModule).Assembly);

Configure<AbpDistributedEventBusOptions>(options =>
{
    options.Inboxes.Configure("ModularCrm", config =>
    {
        config.UseDbContext<ModularCrmDbContext>();
        config.EventSelector = abpModuleSelector;
        config.HandlerSelector = abpModuleSelector;
    });

    options.Outboxes.Configure("ModularCrm", config =>
    {
        config.UseDbContext<ModularCrmDbContext>();
        config.Selector = abpModuleSelector;
    });
});

Order Module Configuration

It only sends OrderPlacedEto events and receives PaymentCompletedEto events and executes OrderPaymentCompletedEventHandler.

Configure<AbpDistributedEventBusOptions>(options =>
{
    options.Inboxes.Configure(OrderingDbProperties.ConnectionStringName, config =>
    {
        config.UseMongoDbContext<IOrderingDbContext>();
        config.EventSelector = type => type == typeof(PaymentCompletedEto);
        config.HandlerSelector = type => type == typeof(OrderPaymentCompletedEventHandler);
    });

    options.Outboxes.Configure(OrderingDbProperties.ConnectionStringName, config =>
    {
        config.UseMongoDbContext<IOrderingDbContext>();
        config.Selector = type => type == typeof(OrderPlacedEto);
    });
});

Here, the EventSelector and HandlerSelector checks only a single type. If you have multiple events and event handlers, you can check the given type if it is included in an array of types.

Product Module Configuration

It only receives EntityCreatedEto<UserEto> and OrderPlacedEto events and executes ProductsOrderPlacedEventHandler and ProductsUserCreatedEventHandler. It does not send any events now.

Configure<AbpDistributedEventBusOptions>(options =>
{
    options.Inboxes.Configure(ProductsDbProperties.ConnectionStringName, config =>
    {
        config.UseDbContext<IProductsDbContext>();
		config.EventSelector = type => type == typeof(EntityCreatedEto<UserEto>) || type == typeof(OrderPlacedEto);
        config.HandlerSelector = type => type == typeof(ProductsOrderPlacedEventHandler) || type == typeof(ProductsUserCreatedEventHandler);
    });

    // Outboxes are not used in this module
	options.Outboxes.Configure(ProductsDbProperties.ConnectionStringName, config =>
	{
		config.UseDbContext<IProductsDbContext>();
		config.Selector = type => false;
	});
});

Payment Module Configuration

It only sends PaymentCompletedEto events and receives OrderPlacedEto events and executes PaymentOrderPlacedEventHandler.

Configure<AbpDistributedEventBusOptions>(options =>
{
    options.Inboxes.Configure(PaymentDbProperties.ConnectionStringName, config =>
    {
        config.UseMongoDbContext<IPaymentMongoDbContext>();
        config.EventSelector = type => type == typeof(OrderPlacedEto);
        config.HandlerSelector = type => type == typeof(PaymentOrderPlacedEventHandler);
    });

    options.Outboxes.Configure(PaymentDbProperties.ConnectionStringName, config =>
    {
        config.UseMongoDbContext<IPaymentMongoDbContext>();
        config.Selector = type => type == typeof(PaymentCompletedEto);
    });
});

Running ModularCRM Simulation Business Flow

1. Run the following command in the ModularCrm directory:

# Start SQL Server and MongoDB databases in Docker
docker-compose up -d

# Restore and install project npm dependencies
abp install-lib              

# Migrate databases
dotnet run --project ModularCrm --migrate-database 

# Start the application
dotnet run --project ModularCrm

2. Navigate to https://localhost:44303/ to view the application homepage

3. Enter a customer name and select a product, then submit an order. After a moment, refresh the page to see the order, product, and payment information.

Application logs display the complete processing flow:

[Ordering Module] Order created:  OrderId: b7ad3f47-0e77-bb81-082f-3a1834503e88, ProductId: 0f95689f-4cb6-36f5-68bd-3a18344d32c9, CustomerName: john

[Products Module] OrderPlacedEto event received: OrderId: b7ad3f47-0e77-bb81-082f-3a1834503e88, CustomerName: john, ProductId: 0f95689f-4cb6-36f5-68bd-3a18344d32c9
[Products Module] Stock count decreased for ProductId: 0f95689f-4cb6-36f5-68bd-3a18344d32c9

[Payment Module] OrderPlacedEto event received: OrderId: b7ad3f47-0e77-bb81-082f-3a1834503e88, CustomerName: john, ProductId: 0f95689f-4cb6-36f5-68bd-3a18344d32c9
[Payment Module] Payment processing completed for OrderId: b7ad3f47-0e77-bb81-082f-3a1834503e88

[Ordering Module] PaymentCompletedEto event received: OrderId: b7ad3f47-0e77-bb81-082f-3a1834503e88, PaymentId: d0a41ead-ee0f-714c-e254-3a1834504d65, PaymentMethod: CreditCard, PaymentAmount: ModularCrm.Payment.Payment.PaymentCompletedEto
[Ordering Module] Order state updated to Delivered for OrderId: b7ad3f47-0e77-bb81-082f-3a1834503e88

In addition, when a new user registers, the product module will also receive the EntityCreatedEto<UserEto> event, and we will send an email to the new user, just to demonstrate the Outbox/Inbox Selector mechanism.

[Products Module] UserCreated event received: UserId: "9a1f2bd0-5b28-210a-9e56-3a18344d310a", UserName: admin
[Products Module] Sending a popular products email to admin@abp.io...

Summary

By introducing the Outbox/Inbox pattern, we have achieved:

1. Transactional message sending and receiving
2. Reliable message processing mechanism
3. Modular event processing in a multi-database environment

ModularCRM project not only implements reliable message processing but also demonstrates how to handle multi-database scenarios gracefully in a monolithic application. Project source code: https://github.com/abpframework/abp-samples/tree/master/ModularCrm-OutboxInbox-Pattern

Reference

• Outbox/Inbox for transactional events
• ConnectionStrings
• ABP Studio: Single Layer Solution Template

The ABP Framework provides various implementations of encryption and decryption to protect sensitive data. Here are three main encryption scenarios and their implementations:

User Passwords

ABP's Identity module uses HMAC-SHA512 combined with PBKDF2 algorithm for password hashing. The process is as follows:

• Encryption process:

  • System generates a random 128-bit salt
  • Combines password and salt, performs 100,000 iterations using HMAC-SHA512 and PBKDF2 algorithms
  • Stores the final hash value combined with the salt (Note: stored ciphertext cannot be reversed to plaintext)

• Verification process:

  • System extracts the stored salt
  • Recalculates the hash value of the provided password using the same algorithm and iterations
  • Compares the results; verification succeeds if matched, fails if not

String Encryption

ABP's IStringEncryptionService uses AES algorithm (CBC mode) for string encryption and decryption. It mainly encrypts and decrypts strings like settings and configuration information. The process is as follows:

• Encryption process:

  • Derives encryption key from passphrase and salt using Rfc2898DeriveBytes (PBKDF2) algorithm
  • Encrypts using AES algorithm with 256-bit key (controlled by Options.Keysize)
  • Uses initialization vector (Options.InitVectorBytes) to ensure encryption security

• Decryption process:

  • Uses the same passphrase and salt
  • Goes through the same key derivation process
  • Restores the encrypted content to original text

Note: If you modify any encryption parameters like passphrase, salt, key size, etc., ensure all applications using encryption use the same parameters, otherwise decryption will fail. For example, encrypted settings in the database will become undecryptable.

OAuth2/AuthServer Signing and Encryption

ABP uses the OpenIddict library for OAuth2 authentication server implementation, which uses two types of credentials to protect generated tokens:

• Credential types:

  • Signing credentials: Prevent token tampering, can be asymmetric (like RSA or ECDSA keys) or symmetric
  • Encryption credentials: Ensure token content confidentiality, prevent unauthorized access and reading

• Environment configuration:

  • Development environment:
    • Automatically creates two separate RSA certificates
    • One for signing, another for encryption
  • Production environment:
    • ABP Studio generates a single RSA certificate (openiddict.pfx) when creating project
    • This certificate is used for both signing and encryption operations

• Custom options:

  • Can replace default certificate with self-generated RSA certificate
  • Supports symmetric encryption (like AES), but not recommended for production

Data Protection

Besides the above encryption and decryption features, ASP.NET Core's built-in components and services may use data protection, such as encrypting private data in cookies or generating links for email confirmation or password recovery. For details, refer to ASP.NET Core Data Protection

Summary

The ABP Framework protects data security through various encryption mechanisms: from HMAC-SHA512 hashing for user passwords, to AES encryption for configuration information, and RSA certificate signing and encryption in OAuth2 authentication, while also integrating ASP.NET Core's data protection features.

For production environments, it's recommended to use strong passphrases and custom salt values, prioritize asymmetric encryption algorithms, and ensure proper management and backup of all encryption credentials.

References

• Hash passwords in ASP.NET Core
• String Encryption
• Encryption and signing credentials
• ASP.NET Core Data Protection

The Unit of Work is a software design pattern that maintains a list of objects affected by a business transaction and coordinates the writing out of changes and the resolution of concurrency problems to ensure that all changes are made within a single transaction.

Transaction Management Overview

One of the primary responsibilities of the Unit of Work is managing database transactions. It provides the following transaction management features:

• Automatically manages database connections and transaction scopes, eliminating the need for manual transaction control
• Ensures business operation integrity by making all database operations within a unit of work either succeed or roll back completely
• Supports configuration of transaction isolation levels and timeout periods
• Supports nested transactions and transaction propagation

Transaction Behavior

Default Transaction Settings

You can modify the default behavior through the following configuration:

Configure<AbpUnitOfWorkDefaultOptions>(options =>
{
    /*
        Modify the default transaction behavior for all unit of work:
        - UnitOfWorkTransactionBehavior.Enabled: Always enable transactions, all requests will start a transaction
        - UnitOfWorkTransactionBehavior.Disabled: Always disable transactions, no requests will start a transaction
        - UnitOfWorkTransactionBehavior.Auto: Automatically decide whether to start a transaction based on HTTP request type
    */
    options.TransactionBehavior = UnitOfWorkTransactionBehavior.Disabled;
    
    // Set default timeout
    options.Timeout = TimeSpan.FromSeconds(30);
    
    // Set default isolation level
    options.IsolationLevel = IsolationLevel.ReadCommitted;
});

Automatic Transaction Management

ABP Framework implements automatic management of Unit of Work and transactions through middlewares, MVC global filters, and interceptors. In most cases, you don't need to manage them manually

Transaction Behavior for HTTP Requests

By default, the framework adopts an intelligent transaction management strategy for HTTP requests:

• GET requests won't start a transactional unit of work because there is no data modification
• Other HTTP requests (POST/PUT/DELETE etc.) will start a transactional unit of work

Manual Transaction Control

If you need to manually start a new unit of work, you can customize whether to start a transaction and set the transaction isolation level and timeout:

// Start a transactional unit of work
using (var uow = _unitOfWorkManager.Begin(
    isTransactional: true,
    isolationLevel: IsolationLevel.RepeatableRead,
    timeout: 30
))
{
    // Execute database operations within transaction
    await uow.CompleteAsync();
}

// Start a non-transactional unit of work
using (var uow = _unitOfWorkManager.Begin(
    isTransactional: false
))
{
    // Execute database operations without transaction
    await uow.CompleteAsync();
}

Configuring Transactions Using [UnitOfWork] Attribute

You can customize transaction behavior by using the UnitOfWorkAttribute on methods, classes, or interfaces:

[UnitOfWork(
    IsTransactional = true,
    IsolationLevel = IsolationLevel.RepeatableRead,
    Timeout = 30
)]
public virtual async Task ProcessOrderAsync(int orderId)
{
    // Execute database operations within transaction
}

Non-Transactional Unit of Work

In some scenarios, you might not need transaction support. You can create a non-transactional unit of work by setting IsTransactional = false:

public virtual async Task ImportDataAsync(List<DataItem> items)
{
    using (var uow = _unitOfWorkManager.Begin(
        isTransactional: false
    ))
    {
        foreach (var item in items)
        {
            await _repository.InsertAsync(item, autoSave: true);
            // Each InsertAsync will save to database immediately
            // If subsequent operations fail, saved data won't be rolled back
        }

        await uow.CompleteAsync();
    }
}

Applicable scenarios:

• Batch import data scenarios where partial success is accepted
• Read-only operations, such as queries
• Scenarios with low data consistency requirements

Methods to Commit Transactions

In Transactional Unit of Work

A Unit of Work provides several methods to commit changes to the database:

1. IUnitOfWork.SaveChangesAsync

await _unitOfWorkManager.Current.SaveChangesAsync();

2. autoSave parameter in repositories

await _repository.InsertAsync(entity, autoSave: true);

Both autoSave and SaveChangesAsync commit changes in the current context to the database. However, these are not applied until CompleteAsync is called. If the unit of work throws an exception or CompleteAsync is not called, the transaction will be rolled back. It means all the DB operations will be reverted back. Only after successfully executing CompleteAsync will the transaction be permanently committed to the database.

3. CompleteAsync

using (var uow = _unitOfWorkManager.Begin())
{
    // Execute database operations
    await uow.CompleteAsync();
}

When you manually control the Unit of Work with UnitOfWorkManager, the CompleteAsync method is crucial for transaction completion. The unit of work maintains a DbTransaction object internally, and the CompleteAsync method invokes DbTransaction.CommitAsync to commit the transaction. The transaction will not be committed if CompleteAsync is either not executed or fails to execute successfully.

This method not only commits all database transactions but also:

• Executes and processes all pending domain events within the Unit of Work
• Executes all registered post-operations and cleanup tasks within the Unit of Work
• Releases all DbTransaction resources upon disposal of the Unit of Work object

Note: CompleteAsync method should be called only once. Multiple calls are not supported.

In Non-Transactional Unit of Work

In non-transactional Unit of Work, these methods behave differently:

Both autoSave and SaveChangesAsync will persist changes to the database immediately, and these changes cannot be rolled back. Even in non-transactional Unit of Work, calling the CompleteAsync method remains necessary as it handles other essential tasks.

Example:

using (var uow = _unitOfWorkManager.Begin(isTransactional: false))
{
    // Changes are persisted immediately and cannot be rolled back
    await _repository.InsertAsync(entity1, autoSave: true);
    
    // This operation persists independently of the previous operation
    await _repository.InsertAsync(entity2, autoSave: true);
    
    await uow.CompleteAsync();
}

Methods to Roll Back Transactions

In Transactional Unit of Work

A unit of work provides multiple approaches to roll back transactions:

1. Automatic Rollback

For transactions automatically managed by the ABP Framework, any uncaught exceptions during the request will trigger an automatic rollback.

2. Manual Rollback

For manually managed transactions, you can explicitly invoke the RollbackAsync method to immediately roll back the current transaction.

Important: Once RollbackAsync is called, the entire Unit of Work transaction will be rolled back immediately, and any subsequent calls to CompleteAsync will have no effect.

using (var uow = _unitOfWorkManager.Begin(
    isTransactional: true,
    isolationLevel: IsolationLevel.RepeatableRead,
    timeout: 30
))
{
    await _repository.InsertAsync(entity);
    
    if (someCondition)
    {
        await uow.RollbackAsync();
        return;
    }
    
    await uow.CompleteAsync();
}

The CompleteAsync method attempts to commit the transaction. If any exceptions occur during this process, the transaction will not be committed.

Here are two common exception scenarios:

1. Exception Handling Within Unit of Work

using (var uow = _unitOfWorkManager.Begin(
    isTransactional: true,
    isolationLevel: IsolationLevel.RepeatableRead,
    timeout: 30
))
{
    try
    {
        await _bookRepository.InsertAsync(book);
        await uow.SaveChangesAsync();
        await _productRepository.UpdateAsync(product);
        await uow.CompleteAsync();
    }
    catch (Exception)
    {
        // Exceptions can occur in InsertAsync, SaveChangesAsync, UpdateAsync, or CompleteAsync
        // Even if some operations succeed, the transaction remains uncommitted to the database
        // While you can explicitly call RollbackAsync to roll back the transaction,
        // the transaction will not be committed anyway if CompleteAsync fails to execute
        throw;
    }
}

2. Exception Handling Outside Unit of Work

try
{
    using (var uow = _unitOfWorkManager.Begin(
        isTransactional: true,
        isolationLevel: IsolationLevel.RepeatableRead,
        timeout: 30
    ))
    {
        await _bookRepository.InsertAsync(book);
        await uow.SaveChangesAsync();
        await _productRepository.UpdateAsync(product);
        await uow.CompleteAsync();
    }
}
catch (Exception)
{
    // Exceptions can occur in UpdateAsync, SaveChangesAsync, UpdateAsync, or CompleteAsync
    // Even if some operations succeed, the transaction remains uncommitted to the database
    // Since CompleteAsync was not successfully executed, the transaction will not be committed
    throw;
}

In Non-Transactional Unit of Work

In non-transactional units of work, operations are irreversible. Changes saved using autoSave: true or SaveChangesAsync() are persisted immediately, and the RollbackAsync method has no effect.

Transaction Management Best Practices

1. Remember to Commit Transactions

When manually controlling transactions, remember to call the CompleteAsync method to commit the transaction after operations are complete.

2. Pay Attention to Context

If a unit of work already exists in the current context, UnitOfWorkManager.Begin method and UnitOfWorkAttribute will reuse it. Specify requiresNew: true to force create a new unit of work.

[UnitOfWork]
public async Task Method1()
{
    using (var uow = _unitOfWorkManager.Begin(
        requiresNew: true, 
        isTransactional: true,
        isolationLevel: IsolationLevel.RepeatableRead,
        timeout: 30
    ))
    {
        await Method2();
        await uow.CompleteAsync();
    }
}

3. Use virtual Methods

To be able to use Unit of Work attribute, you must use the virtual modifier for methods in dependency injection class services, because ABP Framework uses interceptors, and it cannot intercept non virtual methods, thus unable to implement Unit of Work functionality.

4. Avoid Long Transactions

Enabling long-running transactions can lead to resource locking, excessive transaction log usage, and reduced concurrent performance, while rollback costs are high and may exhaust database connection resources. It's recommended to split into shorter transactions, reduce lock holding time, and optimize performance and reliability.

Transaction-Related Recommendations

• Choose appropriate transaction isolation levels based on business requirements
• Avoid overly long transactions, long-running operations should be split into multiple small transactions
• Use the requiresNew parameter reasonably to control transaction boundaries
• Pay attention to setting appropriate transaction timeout periods
• Ensure transactions can properly roll back when exceptions occur
• For read-only operations, it's recommended to use non-transactional Unit of Work to improve performance

References

• ABP Unit of Work
• EF Core Transactions
• Transaction Isolation Levels

When deploying an ABP application with OpenIddict to IIS or Azure, you may encounter issues with loading PFX/PKCS12 certificates. This article explains how to properly configure certificate loading to ensure it works correctly in these environments.

The Problem

When running under IIS or Azure, the application pool identity may not have sufficient permissions to access certificate private keys. This commonly results in errors such as:

• System.Security.Cryptography.CryptographicException: Access denied.
• WindowsCryptographicException: Access is denied.
• System.Security.Cryptography.CryptographicException: The system cannot find the file specified.

The Solution

Using AddDevelopmentEncryptionAndSigningCertificate

For development environments using DevelopmentEncryptionAndSigningCertificate, you must configure the application pool to load a user profile.

Note: We strongly recommend using DevelopmentEncryptionAndSigningCertificate only in development environments. For production, always create and use a separate certificate.

Using AddProductionEncryptionAndSigningCertificate

The ABP OpenIddict module provides an AddProductionEncryptionAndSigningCertificate extension method. By default, the template project attempts to load an openiddict.pfx certificate in production environments.

To ensure proper certificate loading in IIS or Azure, you need to specify appropriate X509KeyStorageFlags when calling this method:

public override void PreConfigureServices(ServiceConfigurationContext context)
{
    var hostingEnvironment = context.Services.GetHostingEnvironment();

    if (!hostingEnvironment.IsDevelopment())
    {
       PreConfigure<AbpOpenIddictAspNetCoreOptions>(options =>
       {
          options.AddDevelopmentEncryptionAndSigningCertificate = false;
       });

       PreConfigure<OpenIddictServerBuilder>(serverBuilder =>
       {
         var flag = X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.EphemeralKeySet;
         serverBuilder.AddProductionEncryptionAndSigningCertificate("openiddict.pfx", "YourCertificatePassword", flag);
       });
    }
}

Understanding X509KeyStorageFlags

The configuration uses two important flags:

• X509KeyStorageFlags.MachineKeySet: Specifies that the key belongs to the local computer key store, binding the key pair's lifecycle to the computer rather than a specific user.
• X509KeyStorageFlags.EphemeralKeySet: Indicates that the key will be stored only in memory and not persisted to disk or key store, enhancing security for runtime-only certificate requirements.

Using these flags in combination helps prevent permission-related issues in IIS and Azure environments.

Troubleshooting Guide

If you continue to experience issues, verify the following:

• Confirm that the certificate password is correct
• Verify that the openiddict.pfx file exists in your deployment
• Ensure the certificate is valid - you can generate a new one using:

  dotnet dev-certs https -v -ep openiddict.pfx -p YourCertificatePassword
  

• Check the stdout logs for related errors (See how to get stdout-log)

References

• ABP OpenIddict Deployment
• ABP IIS Deployment
• ABP Azure Deployment
• How to Generate a New Certificate
• Load User Profile in IIS

We have introduced a new feature in the ABP framework to bundle the JavaScript/CSS files in the Blazor wasm app. This feature is called Global Assets. With this feature, you don't need to run the abp bundle command to manually create/maintain the global.js and global.css files in your Blazor wasm app.

How Global Assets works?

The new Blazor wasm app has two projects:

1. MyProjectName (ASP.NET Core app)
2. MyProjectName.Client (Blazor wasm app)

The MyProjectName reference the MyProjectName.Client project, and will be the entry point of the application, which means the MyProjectName project will be the host project of the MyProjectName.Client project.

The static/virtual files of MyProjectName can be accessed by the MyProjectName.Client project, so we can create dynamic global assets in the MyProjectName project and use them in the MyProjectName.Client project.

How it works in ABP?

We have created a new package WebAssembly.Theme.Bundling for the theme WebAssembly module and used the Volo.Abp.AspNetCore.Mvc.UI.Bundling.BundleContributor to add JavaScript/CSS files to the bundling system.

• LeptonXLiteTheme: AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule
• LeptonXTheme: AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule
• LeptonTheme: AbpAspNetCoreComponentsWebAssemblyLeptonThemeBundlingModule
• BasicTheme: AbpAspNetCoreComponentsWebAssemblyBasicThemeBundlingModule

The new ThemeBundlingModule only depends on AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule(new package). It's an abstractions module, which only depends on AbpAspNetCoreMvcUiBundlingAbstractionsModule.

We will get all JavaScript/CSS files on OnApplicationInitializationAsync method of AbpAspNetCoreMvcUiBundlingModule from bundling system and add them to IDynamicFileProvider service. After that, we can access the JavaScript/CSS files in the Blazor wasm app.

Add the Global Assets in the module

If your module has JavaScript/CSS files that need to the bundling system, You have to create a new project(YourModuleName.Blazor.WebAssembly.Bundling) to your module solution, and reference the new project in the MyProjectName project and module dependencies.

The new project should only depend on the AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule and define BundleContributor classes to contribute the JavaScript/CSS files.

Q: The new project(YourModuleName.Blazor.WebAssembly.Bundling) doesn't have the libs/myscript.js and libs/myscript.css files why the files can be added to the bundling system?

A: Because the MyProjectName.Client will depend on the MyBlazorModule(YourModuleName.Blazor) that contains the JavaScript/CSS files, The MyProjectName is referencing the MyProjectName.Client project, so the MyProjectName project can access the JavaScript/CSS files in the MyProjectName.Client project and add them to the bundling system.

[DependsOn(
    typeof(AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule)
)]
public class MyBlazorWebAssemblyBundlingModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure<AbpBundlingOptions>(options =>
        {
            // Script Bundles
            options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global).AddContributors(typeof(MyModuleBundleScriptContributor));

            // Style Bundles
            options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global).AddContributors(typeof(MyModuleBundleStyleBundleContributor));
        });
    }
}

public class MyModuleBundleScriptContributor : BundleContributor
{
    public override void ConfigureBundle(BundleConfigurationContext context)
    {
        context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.js");
    }
}

public class MyModuleBundleStyleBundleContributor : BundleContributor
{
    public override void ConfigureBundle(BundleConfigurationContext context)
    {
        context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.css");
    }
}

Use the Global Assets in the Blazor WASM

MyCompanyName.MyProjectName.Blazor

Convert your MyCompanyName.MyProjectName.Blazor project to integrate the ABP module system and depend on the AbpAspNetCoreMvcUiBundlingModule and AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule:

• The AbpAspNetCoreMvcUiBundlingModule uses to create the JavaScript/CSS files to virtual files.
• The AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule uses to add theme JavaScript/CSS to the bundling system.

Here is how your project files look like:

Program.cs:

public class Program
{
    public async static Task<int> Main(string[] args)
    {
        //...

        var builder = WebApplication.CreateBuilder(args);
        builder.Host.AddAppSettingsSecretsJson()
            .UseAutofac()
            .UseSerilog();
        await builder.AddApplicationAsync<MyProjectNameBlazorModule>();
        var app = builder.Build();
        await app.InitializeApplicationAsync();
        await app.RunAsync();
        return 0;

	//...
	}
}

MyProjectNameBlazorModule.cs:

[DependsOn(
    typeof(AbpAutofacModule),
    typeof(AbpAspNetCoreMvcUiBundlingModule),
    typeof(AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule) //Should be added!
)]
public class MyProjectNameBlazorModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        //https://github.com/dotnet/aspnetcore/issues/52530
        Configure<RouteOptions>(options =>
        {
            options.SuppressCheckForUnhandledSecurityMetadata = true;
        });

        // Add services to the container.
        context.Services.AddRazorComponents()
            .AddInteractiveWebAssemblyComponents();
    }

    public override void OnApplicationInitialization(ApplicationInitializationContext context)
    {
        var env = context.GetEnvironment();
        var app = context.GetApplicationBuilder();

        // Configure the HTTP request pipeline.
        if (env.IsDevelopment())
        {
            app.UseWebAssemblyDebugging();
        }
        else
        {
            // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.MapAbpStaticAssets();
        app.UseRouting();
        app.UseAntiforgery();

        app.UseConfiguredEndpoints(builder =>
        {
            builder.MapRazorComponents<App>()
                .AddInteractiveWebAssemblyRenderMode()
                .AddAdditionalAssemblies(WebAppAdditionalAssembliesHelper.GetAssemblies<MyProjectNameBlazorClientModule>());
        });
    }
}

MyCompanyName.MyProjectName.Blazor.csproj:

<ItemGroup>
	<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.Server" Version="9.0.0.0" />
	<PackageReference Include="Volo.Abp.Autofac" Version="9.0.0" />
	<PackageReference Include="Volo.Abp.AspNetCore.Mvc.UI.Bundling" Version="9.0.0" />
	<PackageReference Include="Volo.Abp.AspNetCore.Components.WebAssembly.LeptonXLiteTheme.Bundling" Version="9.0.0" />
	<!-- <PackageReference Include="Volo.Abp.AspNetCore.Components.WebAssembly.LeptonXTheme.Bundling" Version="9.0.0" />  --> if you're using LeptonXTheme
	<ProjectReference Include="..\MyProjectName.Blazor.Client\MyProjectName.Blazor.Client.csproj" />
</ItemGroup>

BlazorWebAssemblyBundlingModule in the ABP commercial

Here is the list of Bundling Modules in the ABP commercial. If you're using the pro template, you should add them to the MyCompanyName.MyProjectName.Blazor project.

| BundlingModules | Nuget Package | |---------------------------------------------|-----------------------------------------------------| | AbpAuditLoggingBlazorWebAssemblyBundlingModule | Volo.Abp.AuditLogging.Blazor.WebAssembly.Bundling | | FileManagementBlazorWebAssemblyBundlingModule | Volo.FileManagement.Blazor.WebAssembly.Bundling | | SaasHostBlazorWebAssemblyBundlingModule | Volo.Saas.Host.Blazor.WebAssembly.Bundling | | ChatBlazorWebAssemblyBundlingModule | Volo.Chat.Blazor.WebAssembly.Bundling | | CmsKitProAdminBlazorWebAssemblyBundlingModule | Volo.CmsKit.Pro.Admin.Blazor.WebAssembly.Bundling |

MyCompanyName.MyProjectName.Blazor.Client

1. Remove the global.JavaScript/CSS files from the MyCompanyName.MyProjectName.Blazor's wwwroot folder.
2. Remove the AbpCli:Bundle section from the appsettings.json file.
3. Remove all BundleContributor classes that inherit from IBundleContributor. Then, create MyProjectNameStyleBundleContributor and MyProjectNameScriptBundleContributor classes to add your style and JavaScript files. Finally, add them to AbpBundlingOptions.

public class MyProjectNameStyleBundleContributor : BundleContributor
{
    public override void ConfigureBundle(BundleConfigurationContext context)
    {
        context.Files.Add(new BundleFile("main.css", true));
    }
}


public class MyProjectNameScriptBundleContributor : BundleContributor
{
    public override void ConfigureBundle(BundleConfigurationContext context)
    {
        context.Files.Add(new BundleFile("main.js", true));
    }
}

Configure<AbpBundlingOptions>(options =>
{
	var globalStyles = options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global);
	globalStyles.AddContributors(typeof(MyProjectNameStyleBundleContributor));
	
	var globalScripts = options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global);
	globalScripts.AddContributors(typeof(MyProjectNameScriptBundleContributor));
});

Use the Global Assets in the Blazor WebApp

MyCompanyName.MyProjectName.Blazor.WebApp

Depending on the AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule in your MyCompanyName.MyProjectName.Blazor.WebApp project.

• The AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule uses to add theme JavaScript/CSS to the bundling system.

BlazorWebAssemblyBundlingModule in the ABP commercial

Here is the list of Bundling Modules in the ABP commercial. If you're using the pro template, you should add them to the MyCompanyName.MyProjectName.Blazor.WebApp project.

| BundlingModules | Nuget Package | |---------------------------------------------|-----------------------------------------------------| | AbpAuditLoggingBlazorWebAssemblyBundlingModule | Volo.Abp.AuditLogging.Blazor.WebAssembly.Bundling | | FileManagementBlazorWebAssemblyBundlingModule | Volo.FileManagement.Blazor.WebAssembly.Bundling | | SaasHostBlazorWebAssemblyBundlingModule | Volo.Saas.Host.Blazor.WebAssembly.Bundling | | ChatBlazorWebAssemblyBundlingModule | Volo.Chat.Blazor.WebAssembly.Bundling | | CmsKitProAdminBlazorWebAssemblyBundlingModule | Volo.CmsKit.Pro.Admin.Blazor.WebAssembly.Bundling |

MyCompanyName.MyProjectName.Blazor.WebApp.Client

1. Remove the global.JavaScript/CSS files from the MyCompanyName.MyProjectName.Blazor.WebApp.Client's wwwroot folder.
2. Remove the AbpCli:Bundle section from the appsettings.json file.
3. Remove all BundleContributor classes that inherit from IBundleContributor. Then, create MyProjectNameStyleBundleContributor and MyProjectNameScriptBundleContributor classes to add your style and JavaScript files. Finally, add them to AbpBundlingOptions.

public class MyProjectNameStyleBundleContributor : BundleContributor
{
    public override void ConfigureBundle(BundleConfigurationContext context)
    {
        context.Files.Add(new BundleFile("main.css", true));
    }
}


public class MyProjectNameScriptBundleContributor : BundleContributor
{
    public override void ConfigureBundle(BundleConfigurationContext context)
    {
        context.Files.Add(new BundleFile("main.js", true));
    }
}

Configure<AbpBundlingOptions>(options =>
{
	var globalStyles = options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global);
	globalStyles.AddContributors(typeof(MyProjectNameStyleBundleContributor));
	
	var globalScripts = options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global);
	globalScripts.AddContributors(typeof(MyProjectNameScriptBundleContributor));
});

Check the Global Assets

Run the MyProject project and check the https://localhost/global.js and https://localhost/global.css files. You should be able to see the JavaScript/CSS files content from the Bundling system:

GlobalAssets(AbpBundlingGlobalAssetsOptions)

You can configure the JavaScript and CSS file names in the GlobalAssets property of the AbpBundlingOptions class.

The default values are global.js and global.css.

Conclusion

With the new Global Assets feature, you can easily bundle the JavaScript/CSS files in the Blazor wasm app. This feature is very useful for the Blazor wasm app, and it will save you a lot of time and effort. We hope you will enjoy this feature and use it in your projects.

References

• Virtual Files
• Bundle Contributors
• Global Assets Pull Request

🎉 The Annual .NET Developer Conference Was Successfully Held!

On December 14th, .NET Conf China 2024 was grandly held at the Zhonggu Xiaonanguo Garden Hotel in Shanghai. With the theme of Intelligence, Innovation, Openness, the conference spotlighted the latest trends and practices in .NET, encompassing artificial intelligence, open-source technology, and enterprise-level development. Technology enthusiasts, enterprise tech leaders, and open-source community members from across the country gathered to celebrate the thriving growth of the .NET ecosystem.

As one of the largest .NET technical conferences in China, this event attracted numerous renowned technical experts and community organizations. It showcased the latest achievements of .NET in supporting multi-platform and multi-architecture environments and provided developers with an inspiring sense of the power of technology and the warmth of the community through a series of sessions and practice exchanges.

Highlights of the Event: Merging Technical Depth and Breadth

The conference featured a main venue and three breakout sessions (A, B, and C), covering a wide range of topics in substantial depth.

Main Venue: Keynotes and Industry Insights

The main venue opened with a keynote by Steve, Development Director of the .NET Platform Team, who provided an in-depth analysis of the new features of .NET 9 and its future trajectory , outlining a blueprint for innovation and efficiency in development. Following that, Microsoft CTO Wei Qing delivered a keynote discussing how enterprises can enhance their core competitiveness with .NET technologies through real-world cases.

The roundtable discussion, themed “Openness and Collaboration,” brought together industry experts such as Wei Qing, Su Zhenwei, Xiao Weiyu, Yi Mingzhi, Zhang Shanyou, and Zhang Guangpo. They explored the future of generative AI, open-source collaboration, and the .NET technology ecosystem in a lively and thought-provoking dialogue.

Breakout Sessions: Comprehensive Technical Discussions

The breakout sessions (A, B, and C) covered diverse topics, including artificial intelligence, enterprise-level development, open-source practices, and cross-platform development :

• AI and .NET Integration : Sessions focused on practical applications of AI technologies, such as building enterprise-level AI platforms, exploring natural language programming, and applying Semantic Kernel in real-world scenarios.
• Deep Dive into Enterprise Applications with .NET : Insights on optimizing .NET applications for localized systems, enhancing the security of enterprise AI development, and advanced debugging techniques in .NET.
• Open Source and Community Innovation : Developers shared experiences from open-source project development to enterprise application, covering technologies such as Blazor, EFCore9, and Avalonia, along with their adaptation and optimization for local ecosystems.

These sessions not only demonstrated the diverse applications of .NET across various fields but also provided actionable insights to help developers refine their technical practices.

ABP and Developers: Exploring the Future of Application Development

As a key product in the .NET ecosystem, the ABP Team engaged deeply with developers at the conference. They showcased the unique advantages of ABP in rapidly building modern applications and provided detailed product insights, drawing significant interest from developers.

During booth interactions, developers gained a deeper understanding of the core features of the ABP Framework, the latest updates in the ABP 9.0 version, and the all-new ABP Studio tool. They also explored best practices in areas such as enterprise-level application development, modular architecture design, and microservices with ABP team members.

Additionally, ABP hosted a giveaway, offering prizes like Bluetooth headphones and copies of Mastering ABP Framework by Halil İbrahim Kalkan, which added fun and left attendees with a strong impression of the ABP platform.

Conclusion and Outlook: Advancing Toward the Future of Technology

.NET Conf China 2024 was not just a celebration of technology but also a forward-looking exploration of AI's future. AI was a recurring theme throughout the event, with particular emphasis on applications of generative AI and natural language processing. These discussions underscored the enormous potential for deep integration between AI and .NET technologies. From building enterprise AI platforms to making AI smarter and more efficient with .NET, AI is becoming a critical innovation tool for developers and enterprises alike.

The rapid development of AI challenges developers to keep pace with the latest technological trends and applications, driving the evolution of tools and fostering more efficient and intelligent development methods. Looking ahead, we believe AI will continue to integrate deeply with .NET technologies, empowering developers to tackle complex challenges, enhance productivity, and drive broader technological innovation.

Through this conference, developers not only expanded their technical horizons but also deepened their understanding of AI, .NET, and the broader ecosystem. In the future, we look forward to even closer integration of AI technologies with development practices in the .NET ecosystem, paving the way for a smarter era.

🌐 Technology Unites, Innovation Knows No Boundaries. See you at the next .NET Conf China!

As we wrap up this journey, let us turn our attention to Shanghai—a city full of vitality and innovation. The dazzling night view of the Bund, with lights reflecting off both sides of the Huangpu River, perfectly embodies a blend of history and modernity. Just like the theme of .NET Conf China 2024 - Intelligence, Innovation, Openness, Shanghai inspires developers to explore the boundaries of technology and co-create a future of infinite possibilities.

Looking forward, we hope to welcome more tech enthusiasts in this vibrant city, striving together toward a brighter technological future!

A typical ABP modular project usually consists of three main projects: Application, Domain, and EntityFrameworkCore/MongoDB. In these projects, we may provide many services that require unit testing.

Using abstract unit test classes involves first writing tests in the Application and Domain layers that are independent of the storage technology, ensuring the correctness of core business logic. These abstract tests are then implemented in EntityFrameworkCore or MongoDB. The benefits of this approach include:

1. Reduced Coupling: Core logic tests do not depend on specific storage technologies, so switching databases does not require rewriting test code.
2. Better Isolation: Focuses on verifying business logic correctness, avoiding interference from database operations.
3. Increased Reusability: The same abstract tests can be reused with different storage implementations.
4. Easier Maintenance and Extensibility: Different storage implementations can be extended independently without breaking existing tests.
5. Faster and More Reliable Tests: Reduces dependency on databases, making tests faster and more stable.

How to migrate old unit tests to the new unit test structure

Assume our project name is MyCompanyName.MyProjectName.

Changes to the MyCompanyName.MyProjectName.Application.Tests project:

1. Remove the MyCompanyName.MyProjectName.Application.Tests project's MyProjectNameApplicationCollection class.
2. Modify the MyCompanyName.MyProjectName.Application.Tests project's MyProjectNameApplicationTestBase class.

public abstract class MyProjectNameApplicationTestBase<TStartupModule> : MyProjectNameTestBase<TStartupModule>
    where TStartupModule : IAbpModule
{
	//...
}

3. Modify the MyCompanyName.MyProjectName.Application.Tests project's unit test classes to become abstract unit test classes, such as: SampleAppServiceTests.

public abstract class SampleAppServiceTests<TStartupModule> : MyProjectNameApplicationTestBase<TStartupModule>
    where TStartupModule : IAbpModule
{
    [Fact]
    public async Task Initial_Data_Should_Contain_Admin_User()
    {
        //...
    }
}

Changes to the MyCompanyName.MyProjectName.Domain.Tests project:

1. Remove the MyCompanyName.MyProjectName.Domain.Tests project's MyProjectNameDomainCollection class.
2. Modify the MyCompanyName.MyProjectName.Domain.Tests project's MyProjectNameDomainTestBase class.

public abstract class MyProjectNameDomainTestBase<TStartupModule> : MyProjectNameTestBase<TStartupModule>
    where TStartupModule : IAbpModule
{
	//...
}

3. Modify the MyCompanyName.MyProjectName.Domain.Tests project's unit test classes to become abstract unit test classes, such as: SampleDomainTests.

public abstract class SampleDomainTests<TStartupModule> : MyProjectNameDomainTestBase<TStartupModule>
    where TStartupModule : IAbpModule
{
    [Fact]
    public async Task Should_Set_Email_Of_A_User()
    {
		//...
    }
}

4. Modify the MyCompanyName.MyProjectName.Domain.Tests project's csproj and module class. Remove references to EntityFrameworkCore/MongoDB.

MyCompanyName.MyProjectName.Domain.Tests.csproj:

<Project Sdk="Microsoft.NET.Sdk">

  //...

  <ItemGroup>
    <ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.Domain\MyCompanyName.MyProjectName.Domain.csproj" />
    <ProjectReference Include="..\MyCompanyName.MyProjectName.TestBase\MyCompanyName.MyProjectName.TestBase.csproj" />
  </ItemGroup>
</Project>

MyProjectNameDomainTestModule.cs:

[DependsOn(
    typeof(MyProjectNameDomainModule),
    typeof(MyProjectNameTestBaseModule)
)]
public class MyProjectNameDomainTestModule : AbpModule
{
	//...
}

Changes to the MyCompanyName.MyProjectName.EntityFrameworkCore.Tests project:

Here, we need to create implementation classes for all abstract unit tests.

[Collection(MyProjectNameTestConsts.CollectionDefinitionName)]
public class EfCoreSampleAppServiceTests : SampleAppServiceTests<MyProjectNameEntityFrameworkCoreTestModule>
{
	//...
}

[Collection(MyProjectNameTestConsts.CollectionDefinitionName)]
public class EfCoreSampleDomainTests : SampleDomainTests<MyProjectNameEntityFrameworkCoreTestModule>
{
	//...
}

We also need to modify the project's dependencies and module class, which should directly or indirectly reference the Application and Domain test projects.

MyCompanyName.MyProjectName.EntityFrameworkCore.Tests.csproj:

<Project Sdk="Microsoft.NET.Sdk">

   //...

  <ItemGroup>
    <ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.EntityFrameworkCore\MyCompanyName.MyProjectName.EntityFrameworkCore.csproj" />
    <ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" />
    <ProjectReference Include="..\..\..\..\..\framework\src\Volo.Abp.EntityFrameworkCore.Sqlite\Volo.Abp.EntityFrameworkCore.Sqlite.csproj" />
  </ItemGroup>
</Project>

MyProjectNameEntityFrameworkCoreTestModule.cs:

[DependsOn(
    typeof(MyProjectNameApplicationTestModule),
    typeof(MyProjectNameEntityFrameworkCoreModule),
    typeof(AbpEntityFrameworkCoreSqliteModule)
    )]
public class MyProjectNameEntityFrameworkCoreTestModule : AbpModule
{
	//...
}

Changes to the MyCompanyName.MyProjectName.MongoDB.Tests project (skip this step if not using MongoDB):

Like the EntityFrameworkCore project, we need to create implementation classes for all abstract unit tests and modify the project's dependencies and module class.

[Collection(MyProjectNameTestConsts.CollectionDefinitionName)]
public class MongoDBSampleAppServiceTests : SampleAppServiceTests<MyProjectNameMongoDbTestModule>
{
	//...
}

[Collection(MyProjectNameTestConsts.CollectionDefinitionName)]
public class MongoDBSampleDomainTests : SampleDomainTests<MyProjectNameMongoDbTestModule>
{
	//...
}

<Project Sdk="Microsoft.NET.Sdk">

  //...

  <ItemGroup>
    <ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.MongoDB\MyCompanyName.MyProjectName.MongoDB.csproj" />
    <ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" />
  </ItemGroup>
</Project>

[DependsOn(
    typeof(MyProjectNameApplicationTestModule),
    typeof(MyProjectNameMongoDbModule)
)]
public class MyProjectNameMongoDbTestModule : AbpModule
{
	//...
}

Changes to the MyCompanyName.MyProjectName.Web.Tests project:

We need to reference the EntityFrameworkCore/MongoDB test projects in this test project.

<Project Sdk="Microsoft.NET.Sdk">

  //...

  <ItemGroup>
    <ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" />
    <ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.Web\MyCompanyName.MyProjectName.Web.csproj" />
    <ProjectReference Include="..\..\..\..\..\framework\src\Volo.Abp.AspNetCore.TestBase\Volo.Abp.AspNetCore.TestBase.csproj" />
    <ProjectReference Include="..\MyCompanyName.MyProjectName.EntityFrameworkCore.Tests\MyCompanyName.MyProjectName.EntityFrameworkCore.Tests.csproj" />
  </ItemGroup>
</Project>

[DependsOn(
    typeof(AbpAspNetCoreTestBaseModule),
    typeof(MyProjectNameWebModule),
    typeof(MyProjectNameApplicationTestModule),
    typeof(MyProjectNameEntityFrameworkCoreTestModule)
)]
public class MyProjectNameWebTestModule : AbpModule
{
	//...
}

We no longer need the MyProjectNameWebCollection class in this project. Please delete it and use [Collection(MyProjectNameTestConsts.CollectionDefinitionName)] instead.

Conclusion

This is our new unit test structure. Decoupling unit tests from storage technologies ensures the independence of business logic and allows easy switching between storage implementations. Abstract unit test classes improve test reusability, maintainability, and efficiency, reducing refactoring costs and providing flexibility for future tech updates.

References

• Unit Test
• Abstract all db-related unit tests

Delivering static assets efficiently is a key factor in building performant web applications. By optimizing how assets like CSS, JavaScript, and images are served to the browser, you can reduce load times, decrease network traffic, and improve the overall user experience.

One powerful tool to help achieve this is MapStaticAssets, a feature in ASP.NET Core that significantly optimizes the delivery of static resources. Whether you're working with Blazor, Razor Pages, MVC, or other UI frameworks, MapStaticAssets streamlines asset management and ensures that your web app delivers resources in the most efficient way possible.

Why Optimizing Static Assets Matters

Serving static assets without optimization can lead to several performance bottlenecks:

• Excessive network requests: The browser may need to request the same resources multiple times, even if they haven’t changed.
• Unnecessary data transfer: Larger files are sent over the network, consuming bandwidth and slowing down page loads.
• Outdated assets: Without proper cache management, users may receive stale versions of files after an app update.

Optimizing static assets involves compressing files, managing caching headers, and ensuring that only the necessary resources are sent to the client. MapStaticAssets takes care of all these issues in a seamless, automated way.

What is MapStaticAssets?

MapStaticAssets is designed to enhance the default static asset serving mechanism in ASP.NET Core. It can replace UseStaticFiles in most scenarios and comes with several built-in optimizations. These optimizations are executed at both build and publish time, ensuring that static resources are served in the most efficient way possible when your app is running.

Here's how you can implement MapStaticAssets in your app:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseRouting();

app.UseAuthorization();

// Replacing UseStaticFiles with MapStaticAssets
app.MapStaticAssets();
app.MapRazorPages();

app.Run();

Key Features of MapStaticAssets

1. Build-time Compression:
   MapStaticAssets automatically compresses all static assets during the build process. It uses gzip compression during development and gzip + brotli compression when publishing. This reduces the file size significantly, ensuring faster download times.

   For example, in a default Razor Pages template, assets like bootstrap.min.css and jquery.js are compressed by over 80%, resulting in significantly reduced file sizes:

   | File | Original Size | Compressed Size | Compression Reduction | |----------------------|---------------|-----------------|-----------------------| | bootstrap.min.css | 163 KB | 17.5 KB | 89.26% | | jquery.js | 89.6 KB | 28 KB | 68.75% | | bootstrap.min.js | 78.5 KB | 20 KB | 74.52% | | Total | 331.1 KB | 65.5 KB | 80.20% |

2. Content-based ETags:
   MapStaticAssets generates ETags based on the SHA-256 hash of the file content, encoded in Base64. This ensures that the browser only re-downloads a resource if its content has changed. This eliminates unnecessary network requests, improving page load speeds.

3. Smaller File Sizes for Libraries:
   Popular component libraries, such as Fluent UI Blazor and MudBlazor, benefit from similar compression optimizations. For example, the size of the MudBlazor library is reduced by over 90%, from 588 KB to just 46.7 KB after compression.

   | File | Original Size | Compressed Size | Compression Reduction | |----------------------|---------------|-----------------|-----------------------| | MudBlazor.min.css | 541 KB | 37.5 KB | 93.07% | | MudBlazor.min.js | 47.4 KB | 9.2 KB | 80.59% | | Total | 588.4 KB | 46.7 KB | 92.07% |

4. Automatic Optimization:
   As libraries or components are added or updated, MapStaticAssets automatically optimizes the assets as part of the build process. This includes minimizing the size of JavaScript and CSS files, reducing the impact of mobile or low-bandwidth environments.

5. Serving Assets with a CDN:
   Although MapStaticAssets is focused on server-side optimizations, integrating a CDN (Content Delivery Network) can further boost performance by serving static assets from servers geographically closer to the user, reducing latency.

Comparing MapStaticAssets to IIS Dynamic Compression

MapStaticAssets provides several advantages over traditional dynamic compression techniques, such as IIS gzip compression:

• Simplicity: There is no need for server-specific configuration, making MapStaticAssets easy to implement.
• Performance: By compressing assets at build time, the app doesn't need to perform compression during every request, which improves server performance.
• Optimization: Developers can focus on ensuring that assets are compressed to the smallest possible size during the build process.

For example, using MapStaticAssets, a file like MudBlazor.min.css is compressed down to 37.5 KB, whereas IIS dynamic compression might result in a size of 90 KB. This represents a 59% reduction in size.

About MapAbpStaticAssets

The ABP framework is 100% compatible with this new feature.

However, some JavaScript, CSS, and image files exist in the Virtual File System, which ASP.NET Core's MapStaticAssets can't handle. For these files, additional StaticFileMiddleware is needed to serve them, which is where MapAbpStaticAssets comes in.

MapAbpStaticAssets adds the necessary StaticFileMiddleware to ensure that virtual files are correctly served. This middleware setup ensures seamless delivery of virtual resources alongside static assets.

You can view the source code of MapAbpStaticAssets on GitHub.

Conclusion

Optimizing static asset delivery is essential for building fast, efficient web applications. MapStaticAssets simplifies and automates the optimization of static files by providing build-time compression, caching headers, and content-based ETags. This ensures that your app's static assets are always delivered in the most efficient way, whether users are on fast broadband or slower mobile connections. By using MapStaticAssets, you can deliver a faster, more reliable experience for your users with minimal effort.

References

• Static files in ASP.NET Core
• What's new in ASP.NET Core 9.0

In most companies, a user belongs to more than one organization. Also, in some applications, we need to filter the data shown depending on the logged-in user's organization. For such scenarios, allowing users to select one of the organizations they belong to is a good practice.

Creating a Data Filter with Organization Units

IHasOrganization

First, we need to create a data filter that filters data based on the organization unit.

The IHasOrganization interface is used to define the organization unit property in the entity classes, and used to filter the data based on the organization unit.

public interface IHasOrganization
{
    public Guid? OrganizationId { get; set; }
}

public class Book : AggregateRoot<Guid>, IHasOrganization
{
    public string Name { get; set; }

    public string Isbn { get; set; }

    public Guid? OrganizationId { get; set; }
}

Entity Framework Core DbContext Implementation

We will override the ShouldFilterEntity and CreateFilterExpression methods in the BookStoreDbContext class to configure the data filter for the entity that implements the IHasOrganization interface.

public class BookStoreDbContext : AbpDbContext<BookStoreDbContext>
{
	// Your others DbSet properties...

    public DbSet<Book> Books { get; set; }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);

        // Your configure code...

        builder.Entity<Book>(b =>
        {
            b.ToTable(BookStoreConsts.DbTablePrefix + "Book", BookStoreConsts.DbSchema);
            b.ConfigureByConvention();
        });
    }

    public CurrentOrganizationIdProvider CurrentOrganizationIdProvider => LazyServiceProvider.LazyGetRequiredService<CurrentOrganizationIdProvider>();

    protected override bool ShouldFilterEntity<TEntity>(IMutableEntityType entityType)
    {
        if (typeof(IHasOrganization).IsAssignableFrom(typeof(TEntity)))
        {
            return true;
        }

        return base.ShouldFilterEntity<TEntity>(entityType);
    }

    protected override Expression<Func<TEntity, bool>> CreateFilterExpression<TEntity>(ModelBuilder modelBuilder)
    {
        var expression = base.CreateFilterExpression<TEntity>(modelBuilder);

        if (typeof(IHasOrganization).IsAssignableFrom(typeof(TEntity)))
        {
            Expression<Func<TEntity, bool>> hasOrganizationIdFilter = e => EF.Property<Guid>(e, "OrganizationId") == CurrentOrganizationIdProvider.CurrentOrganizationId;
            expression = expression == null ? hasOrganizationIdFilter : QueryFilterExpressionHelper.CombineExpressions(expression, hasOrganizationIdFilter);
        }

        return expression;
    }
}

The CurrentOrganizationIdProvider

This class is used to get the current organization id, We will use the AsyncLocal class to store the current organization id, The Change method is used to change the current organization id. This service is registered as a singleton service.

public class CurrentOrganizationIdProvider : ISingletonDependency
{
    private readonly AsyncLocal<Guid?> _currentOrganizationId = new AsyncLocal<Guid?>();

    public Guid? CurrentOrganizationId  => _currentOrganizationId.Value;

    public virtual IDisposable Change(Guid? organizationId)
    {
        var parent = CurrentOrganizationId;
        _currentOrganizationId.Value = organizationId;
        return new DisposeAction(() =>
        {
            _currentOrganizationId.Value = parent;
        });
    }
}

Domain Service Implementation

We will store the current organization id in the cache for the logged-in user. at the same time, we want to store it per browser. So we also add the different browser info for every logged-in user.

In the BrowserInfoClaimsPrincipalContributor class, We add a random BrowserInfo claim to the logged-in user. And we will use user id and browser info as a cache key.

public static class CurrentUserExtensions
{
    public static Guid? GetBrowserInfo(this ICurrentUser currentUser)
    {
        var claimValue = currentUser.FindClaimValue("BrowserInfo");
        if (claimValue != null && Guid.TryParse(claimValue, out var result))
        {
            return result;
        }
        return null;
    }
}

public class BrowserInfoClaimsPrincipalContributor : IAbpClaimsPrincipalContributor, ITransientDependency
{
    public Task ContributeAsync(AbpClaimsPrincipalContributorContext context)
    {
        var identity = context.ClaimsPrincipal.Identities.FirstOrDefault();
        identity?.AddClaim(new Claim("BrowserInfo", Guid.NewGuid().ToString()));
        return Task.CompletedTask;
    }
}

Application Service Implementation

The CurrentOrganizationAppService to get/change the current organization for the logged-in user. BookAppService to get the books based on the current organization id.

[Authorize]
public class CurrentOrganizationAppService : BookStoreAppService, ICurrentOrganizationAppService
{
    private readonly IdentityUserManager _identityUserManager;
    private readonly IDistributedCache<CurrentOrganizationIdCacheItem> _cache;

    public CurrentOrganizationAppService(IdentityUserManager identityUserManager, IDistributedCache<CurrentOrganizationIdCacheItem> cache)
    {
        _identityUserManager = identityUserManager;
        _cache = cache;
    }

    public virtual async Task<List<OrganizationDto>> GetOrganizationListAsync()
    {
        var user = await _identityUserManager.FindByIdAsync(CurrentUser.GetId().ToString());
        var organizationUnits = await _identityUserManager.GetOrganizationUnitsAsync(user);
        return organizationUnits.Select(ou => new OrganizationDto
        {
            Id = ou.Id,
            DisplayName = ou.DisplayName
        }).ToList();
    }

    public virtual async Task<Guid?> GetCurrentOrganizationIdAsync()
    {
        var cacheKey = CurrentUser.Id.ToString() + ":" + CurrentUser.GetBrowserInfo();
        return (await _cache.GetAsync(cacheKey))?.OrganizationId;
    }

    public virtual async Task ChangeAsync(Guid? organizationId)
    {
        var cacheKey = CurrentUser.Id.ToString() + ":" + CurrentUser.GetBrowserInfo();
        await _cache.SetAsync(cacheKey, new CurrentOrganizationIdCacheItem
        {
            OrganizationId = organizationId
        });
    }
}

[Authorize]
public class BookAppService : BookStoreAppService, IBookAppService
{
    private readonly IBasicRepository<Book, Guid> _bookRepository;

    public BookAppService(IBasicRepository<Book, Guid> bookRepository)
    {
        _bookRepository = bookRepository;
    }

    public virtual async Task<List<BookDto>> GetListAsync()
    {
        var books = await _bookRepository.GetListAsync();
        return books.Select(book => new BookDto
        {
            Id = book.Id,
            Name = book.Name,
            Isbn = book.Isbn,
            OrganizationId = book.OrganizationId
        }).ToList();
    }
}

Seed Sample Data

Let's seed some sample data for the Book and Organization entities.

We added two organization units, USA Branch and Turkey Branch, and some books to each organization unit. Also, we added the admin user to both organization units.

public class BooksDataSeedContributor : IDataSeedContributor, ITransientDependency
{
    public Guid UsaBranchId = Guid.Parse("00000000-0000-0000-0000-000000000001");
    public Guid TurkeyBranchId = Guid.Parse("00000000-0000-0000-0000-000000000002");

    private readonly IBasicRepository<Book, Guid>  _bookRepository;
    private readonly OrganizationUnitManager _organizationUnitManager;
    private readonly IOrganizationUnitRepository _organizationUnitRepository;
    private readonly IdentityUserManager _identityUserManager;
    private readonly IUnitOfWorkManager _unitOfWorkManager;

    public BooksDataSeedContributor(
        IBasicRepository<Book, Guid> bookRepository,
        OrganizationUnitManager organizationUnitManager,
        IOrganizationUnitRepository organizationUnitRepository,
        IdentityUserManager identityUserManager,
        IUnitOfWorkManager unitOfWorkManager)
    {
        _bookRepository = bookRepository;
        _organizationUnitManager = organizationUnitManager;
        _organizationUnitRepository = organizationUnitRepository;
        _identityUserManager = identityUserManager;
        _unitOfWorkManager = unitOfWorkManager;
    }

    public virtual async Task SeedAsync(DataSeedContext context)
    {
        using (var uow = _unitOfWorkManager.Begin())
        {
            var usa = await _organizationUnitRepository.FindAsync(UsaBranchId);
            if (usa == null)
            {
                await _organizationUnitManager.CreateAsync(new OrganizationUnit(UsaBranchId, "USA Branch"));
            }

            var turkey = await _organizationUnitRepository.FindAsync(TurkeyBranchId);
            if (turkey == null)
            {
                await _organizationUnitManager.CreateAsync(new OrganizationUnit(TurkeyBranchId, "Turkey Branch"));
            }

            await uow.SaveChangesAsync();

            var admin = await _identityUserManager.FindByNameAsync("admin");
            Check.NotNull(admin, "admin");

            await _identityUserManager.AddToOrganizationUnitAsync(admin.Id, UsaBranchId);
            await _identityUserManager.AddToOrganizationUnitAsync(admin.Id, TurkeyBranchId);

            if (await _bookRepository.GetCountAsync() <= 0)
            {
                await _bookRepository.InsertAsync(new Book
                {
                    Name = "1984",
                    Isbn = "978-0451524935",
                    OrganizationId = UsaBranchId
                });

                await _bookRepository.InsertAsync(new Book
                {
                    Name = "Animal Farm",
                    Isbn = "978-0451526342",
                    OrganizationId = UsaBranchId
                });

                await _bookRepository.InsertAsync(new Book
                {
                    Name = "Brave New World",
                    Isbn = "978-0060850524",
                    OrganizationId = UsaBranchId
                });

                await _bookRepository.InsertAsync(new Book
                {
                    Name = "Fahrenheit 451",
                    Isbn = "978-1451673319",
                    OrganizationId = TurkeyBranchId
                });

                await _bookRepository.InsertAsync(new Book
                {
                    Name = "The Catcher in the Rye",
                    Isbn = "978-0316769488",
                    OrganizationId = TurkeyBranchId
                });

                await _bookRepository.InsertAsync(new Book
                {
                    Name = "To Kill a Mockingbird",
                    Isbn = "978-0061120084",
                    OrganizationId = TurkeyBranchId
                });
            }

            await uow.CompleteAsync();
        }
    }
}

Web Page Implementation

We will add a dropdown list to the top right corner of the page to allow users to select the organization they belong to. When the dropdown list changes, we will call the application service api to change the current organization id.

public class OrganizationUnitComponent : AbpViewComponent
{
    public async Task<IViewComponentResult> InvokeAsync()
    {
        var currentOrganizationAppService = LazyServiceProvider.GetRequiredService<ICurrentOrganizationAppService>();
        var organizationDtos = await currentOrganizationAppService.GetOrganizationListAsync();
        var currentOrganizationId = await currentOrganizationAppService.GetCurrentOrganizationIdAsync();
        return View("/Components/OrganizationUnits/Default.cshtml", new OrganizationUnitComponentModel
        {
            CurrentOrganizationId = currentOrganizationId,
            OrganizationDtos = organizationDtos
        });
    }
}

public class OrganizationUnitComponentModel
{
    public Guid? CurrentOrganizationId { get; set; }

    public List<OrganizationDto> OrganizationDtos { get; set; }
}

@using Microsoft.AspNetCore.Mvc.TagHelpers
@using Volo.Abp.AspNetCore.Mvc.UI.Bundling.TagHelpers
@model BookStore.Web.Components.OrganizationUnits.OrganizationUnitComponentModel

<div class="dropstart">
    <a href="#" class="btn mt-2" data-bs-toggle="dropdown" type="button">
        <i class="fa fa-city m-auto"></i>
    </a>
    <ul class="dropdown-menu p-0" style="width: 200px">
        <div class="list-group">
            @foreach (var ou in Model.OrganizationDtos)
            {
                <button type="button" onclick="setOrganizationUnitId('@ou.Id')" class="list-group-item list-group-item-action @(ou.Id == Model.CurrentOrganizationId ? "active" : "")">@ou.DisplayName</button>
            }
        </div>
    </ul>
</div>

<script>
    function setOrganizationUnitId(id) {
        bookStore.currentOrganization.currentOrganization.change(id).then(function () {
			location.reload();
        });
    }
</script>

Add the OrganizationUnitComponent to the toolbar.

public class BookStoreToolbarContributor : IToolbarContributor
{
    public virtual Task ConfigureToolbarAsync(IToolbarConfigurationContext context)
    {
		// ...
    
        if (context.Toolbar.Name == StandardToolbars.Main)
        {
            context.Toolbar.Items.Add(new ToolbarItem(typeof(OrganizationUnitComponent)).RequireAuthenticated());
        }

        return Task.CompletedTask;
    }
}

In addition, we also need to add a middleware after UseAuthorization to change the current organization id.

app.UseAuthorization();
app.Use(async (httpContext, next) =>
{
	var currentUser = httpContext.RequestServices.GetRequiredService<ICurrentUser>();
	var cacheKey = currentUser.Id.ToString() + ":" + currentUser.GetBrowserInfo();
	var cache = httpContext.RequestServices.GetRequiredService<IDistributedCache<CurrentOrganizationIdCacheItem>>();
	var cacheItem = await cache.GetAsync(cacheKey);
	if (cacheItem != null)
	{
		var currentOrganizationIdProvider = httpContext.RequestServices.GetRequiredService<CurrentOrganizationIdProvider>();
		currentOrganizationIdProvider.Change(cacheItem.OrganizationId);
	}
	await next(httpContext);
});
// ...

The Index page will show the books based on the current organization id.

public class IndexModel : BookStorePageModel
{
    public List<BookDto> Books { get; set; } = new List<BookDto>();
    public string? OrganizationName { get; set; }

    protected readonly IBookAppService BookAppService;
    protected readonly ICurrentOrganizationAppService CurrentOrganizationAppService;
    protected readonly IOrganizationUnitRepository OrganizationUnitRepository;

    public IndexModel(
        IBookAppService bookAppService,
        ICurrentOrganizationAppService currentOrganizationAppService,
        IOrganizationUnitRepository organizationUnitRepository)
    {
        BookAppService = bookAppService;
        CurrentOrganizationAppService = currentOrganizationAppService;
        OrganizationUnitRepository = organizationUnitRepository;
    }

    public async Task OnGetAsync()
    {
        if (CurrentUser.IsAuthenticated)
        {
            var currentOrganizationId = await CurrentOrganizationAppService.GetCurrentOrganizationIdAsync();
            if (currentOrganizationId.HasValue)
            {
                OrganizationName = (await OrganizationUnitRepository.GetAsync(currentOrganizationId.Value)).DisplayName;
            }

            Books = await BookAppService.GetListAsync();
        }
    }
}

@page
@model BookStore.Web.Pages.IndexModel
@using Microsoft.AspNetCore.Mvc.Localization
@using BookStore.Localization
@inject IHtmlLocalizer<BookStoreResource> L

@if (!Model.OrganizationName.IsNullOrEmpty())
{
    <h5>The books belonging to @Model.OrganizationName organization</h5>
}

<ul class="list-group">
    @foreach(var book in Model.Books)
    {
    <li class="list-group-item">Book Name: @book.Name, ISBN: @book.Isbn</li>
    }
</ul>

Final UI

The final UI will look like this:

The index page will show empty if the current organization id is not set. After selecting the organization unit, the index page will show the books based on the selected organization unit.

Summary

In this blog post. We showd simple implementation of switching between organization units. You can extend this implementation to meet your requirements.

After ABP 8.3 we introduced User-defined function mapping feature for global filters which will gain performance improvements.

References

• Data Filtering
• Claims Principal Factory

Introduction

ABP provides data filters that can filter queries automatically based on some rules. This feature is useful for implementing multi-tenancy, soft delete, and other global filters. It uses EF Core's Global Query Filters system for the EF Core Integration.

EF Core Global Query Filters generate filter conditions and apply them to SQL queries. ABP controls whether this filter condition takes effect through a variable. However, this variable may cause performance losses in some scenarios.

The Filter Condition Variable

Think of a scenario with a global filter IIsActive, which filters out inactive entities:

public class Book : IIsActive
{
    public string Name { get; set; }

    public bool IsActive { get; set; } 
}

The SQL generated by the EF Core Global Query Filters is as follows:

SELECT * FROM [AppBooks] AS [a]
WHERE (@__ef_filter__p_0 = CAST(1 AS bit) OR [a].[IsActive] = CAST(1 AS bit))

The __ef_filter__p_0 variable controls whether the filter condition takes effect.

The generated SQL is not optimal, and some databases do not optimize it well.

Using User-defined function mapping for global filters

In the upcoming preview version of ABP, v8.3.0-rc.1, we start the User-defined function mapping to implement global filters more efficiently. This feature is enabled by default, so you don't need to make any changes if you create a new solution and start from scratch. Otherwise, you can enable it easily by following the instructions below.

To use this new feature for your custom global filters, you need to change your DbContext as follows:

protected bool IsActiveFilterEnabled => DataFilter?.IsEnabled<IIsActive>() ?? false;

protected override bool ShouldFilterEntity<TEntity>(IMutableEntityType entityType)
{
    if (typeof(IIsActive).IsAssignableFrom(typeof(TEntity)))
    {
        return true;
    }

    return base.ShouldFilterEntity<TEntity>(entityType);
}

protected override Expression<Func<TEntity, bool>> CreateFilterExpression<TEntity>(ModelBuilder modelBuilder)
{
    var expression = base.CreateFilterExpression<TEntity>(modelBuilder);

    if (typeof(IIsActive).IsAssignableFrom(typeof(TEntity)))
    {
        Expression<Func<TEntity, bool>> isActiveFilter = e => !IsActiveFilterEnabled || EF.Property<bool>(e, "IsActive");

        if (UseDbFunction())
        {
            isActiveFilter = e => IsActiveFilter(((IIsActive)e).IsActive, true);

            var abpEfCoreCurrentDbContext = this.GetService<AbpEfCoreCurrentDbContext>();
            modelBuilder.HasDbFunction(typeof(MyProjectNameDbContext).GetMethod(nameof(IsActiveFilter))!)
                .HasTranslation(args =>
                {
                    // (bool isActive, bool boolParam)
                    var isActive = args[0];
                    var boolParam = args[1];

                    if (abpEfCoreCurrentDbContext.Context?.DataFilter.IsEnabled<IIsActive>() == true)
                    {
                        // isActive == true
                        return new SqlBinaryExpression(
                            ExpressionType.Equal,
                            isActive,
                            new SqlConstantExpression(Expression.Constant(true), boolParam.TypeMapping),
                            boolParam.Type,
                            boolParam.TypeMapping);
                    }

                    // empty where sql
                    return new SqlConstantExpression(Expression.Constant(true), boolParam.TypeMapping);
                });
        }

        expression = expression == null ? isActiveFilter : QueryFilterExpressionHelper.CombineExpressions(expression, isActiveFilter);
    }

    return expression;
}

public static bool IsActiveFilter(bool isActive, bool boolParam)
{
    throw new NotSupportedException(AbpEfCoreDataFilterDbFunctionMethods.NotSupportedExceptionMessage);
}

public override string GetCompiledQueryCacheKey()
{
    return $"{base.GetCompiledQueryCacheKey()}:{IsActiveFilterEnabled}";
}

After these changes, the SQL generated by the EF Core Global Query Filters will be as follows:

Enabling the IIsActive filter:

SELECT * FROM [AppBooks] AS [a] WHERE 
[a].[IsActive] = CAST(1 AS bit)

Disabling the IIsActive filter:

SELECT * FROM [AppBooks] AS [a]

Conclusion

We have implemented global filters using User-defined function mapping, which can generate more efficient SQL and thus improve performance.

Upgrade to the latest ABP version and enjoy the performance improvement!

References

• ABP Framework Data Filtering
• EF Core's Global Query Filters system
• User-defined function mapping

The Claim Type

A web application may use one or more authentication schemes to obtain the current user's information, such as Cookies, JwtBearer, OpenID Connect, Google etc.

After authentication, we get a set of claims that can be issued using a trusted identity provider. A claim is a type/name-value pair representing the subject. The type property provides the semantic content of the claim, that is, it states what the claim is about.

The ICurrentUser service of the ABP Framework provides a convenient way to access the current user's information from the claims.

The claim type is the key to getting the correct value of the current user, and we have a static AbpClaimTypes class that defines the names of the standard claims in the ABP Framework:

public static class AbpClaimTypes
{
    public static string UserId { get; set; } = ClaimTypes.NameIdentifier;
    public static string UserName { get; set; } = ClaimTypes.Name;
    public static string Role { get; set; } = ClaimTypes.Role;
    public static string Email { get; set; } = ClaimTypes.Email;
    //...
}

As you can see, the default claim type of AbpClaimTypes comes from the System.Security.Claims.ClaimTypes class, which is the recommended practice in NET.

Claim type in different authentication schemes

We usually see two types of claim types in our daily development. One of them is the System.Security.Claims.ClaimTypes and the other one is the OpenId Connect standard claims.

ASP NET Core Identity

There is a ClaimsIdentityOptions property in the IdentityOptions, which can be used to configure the claim type:

| Property | Description | |----------------------|---------------------------------------------------------------------------------------------------------------| | EmailClaimType | Gets or sets the ClaimType used for the user email claim. Defaults to Email. | | RoleClaimType | Gets or sets the ClaimType used for a Role claim. Defaults to Role. | | SecurityStampClaimType | Gets or sets the ClaimType used for the security stamp claim. Defaults to "AspNet.Identity.SecurityStamp". | | UserIdClaimType | Gets or sets the ClaimType used for the user identifier claim. Defaults to NameIdentifier. | | UserNameClaimType | Gets or sets the ClaimType used for the user name claim. Defaults to Name. |

• The Identity creates a ClaimsIdentity object with the claim type that you have configured in the ClaimsIdentityOptions class.
• The ABP Framework configures it based on AbpClaimTypes, so usually you don't need to worry about it.

JwtBearer/OpenID Connect Client

The JwtBearer/OpenID Connect gets claims from id_token or fetches user information from the AuthServer, and then maps/adds it to the current ClaimsIdentity.

To map the standard claim type to the System.Security.Claims.ClaimTypes via azure-activedirectory-identitymodel-extensions-for-dotnet library by default, which is maintained by the Microsoft team:

Dictionary<string, string> ClaimTypeMapping = new Dictionary<string, string>
{
    { "actort", ClaimTypes.Actor },
    { "birthdate", ClaimTypes.DateOfBirth },
    { "email", ClaimTypes.Email },
    { "family_name", ClaimTypes.Surname },
    { "gender", ClaimTypes.Gender },
    { "given_name", ClaimTypes.GivenName },
    { "nameid", ClaimTypes.NameIdentifier },
    { "sub", ClaimTypes.NameIdentifier },
    { "website", ClaimTypes.Webpage },
    { "unique_name", ClaimTypes.Name },
    { "oid", "http://schemas.microsoft.com/identity/claims/objectidentifier" },
    { "scp", "http://schemas.microsoft.com/identity/claims/scope" },
    { "tid", "http://schemas.microsoft.com/identity/claims/tenantid" },
    { "acr", "http://schemas.microsoft.com/claims/authnclassreference" },
    { "adfs1email", "http://schemas.xmlsoap.org/claims/EmailAddress" },
    { "adfs1upn", "http://schemas.xmlsoap.org/claims/UPN" },
    { "amr", "http://schemas.microsoft.com/claims/authnmethodsreferences" },
    { "authmethod", ClaimTypes.AuthenticationMethod },
    { "certapppolicy", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/applicationpolicy" },
    { "certauthoritykeyidentifier", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/authoritykeyidentifier" },
    { "certbasicconstraints", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/basicconstraints" },
    { "certeku", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/eku" },
    { "certissuer", "http://schemas.microsoft.com/2012/12/certificatecontext/field/issuer" },
    { "certissuername", "http://schemas.microsoft.com/2012/12/certificatecontext/field/issuername" },
    { "certkeyusage", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/keyusage" },
    { "certnotafter", "http://schemas.microsoft.com/2012/12/certificatecontext/field/notafter" },
    { "certnotbefore", "http://schemas.microsoft.com/2012/12/certificatecontext/field/notbefore" },
    { "certpolicy", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/certificatepolicy" },
    { "certpublickey", ClaimTypes.Rsa },
    { "certrawdata", "http://schemas.microsoft.com/2012/12/certificatecontext/field/rawdata" },
    { "certserialnumber", ClaimTypes.SerialNumber },
    { "certsignaturealgorithm", "http://schemas.microsoft.com/2012/12/certificatecontext/field/signaturealgorithm" },
    { "certsubject", "http://schemas.microsoft.com/2012/12/certificatecontext/field/subject" },
    { "certsubjectaltname", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/san" },
    { "certsubjectkeyidentifier", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/subjectkeyidentifier" },
    { "certsubjectname", "http://schemas.microsoft.com/2012/12/certificatecontext/field/subjectname" },
    { "certtemplateinformation", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/certificatetemplateinformation" },
    { "certtemplatename", "http://schemas.microsoft.com/2012/12/certificatecontext/extension/certificatetemplatename" },
    { "certthumbprint", ClaimTypes.Thumbprint },
    { "certx509version", "http://schemas.microsoft.com/2012/12/certificatecontext/field/x509version" },
    { "clientapplication", "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application" },
    { "clientip", "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-ip" },
    { "clientuseragent", "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-user-agent" },
    { "commonname", "http://schemas.xmlsoap.org/claims/CommonName" },
    { "denyonlyprimarygroupsid", ClaimTypes.DenyOnlyPrimaryGroupSid },
    { "denyonlyprimarysid", ClaimTypes.DenyOnlyPrimarySid },
    { "denyonlysid", ClaimTypes.DenyOnlySid },
    { "devicedispname", "http://schemas.microsoft.com/2012/01/devicecontext/claims/displayname" },
    { "deviceid", "http://schemas.microsoft.com/2012/01/devicecontext/claims/identifier" },
    { "deviceismanaged", "http://schemas.microsoft.com/2012/01/devicecontext/claims/ismanaged" },
    { "deviceostype", "http://schemas.microsoft.com/2012/01/devicecontext/claims/ostype" },
    { "deviceosver", "http://schemas.microsoft.com/2012/01/devicecontext/claims/osversion" },
    { "deviceowner", "http://schemas.microsoft.com/2012/01/devicecontext/claims/userowner" },
    { "deviceregid", "http://schemas.microsoft.com/2012/01/devicecontext/claims/registrationid" },
    { "endpointpath", "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path" },
    { "forwardedclientip", "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip" },
    { "group", "http://schemas.xmlsoap.org/claims/Group" },
    { "groupsid", ClaimTypes.GroupSid },
    { "idp", "http://schemas.microsoft.com/identity/claims/identityprovider" },
    { "insidecorporatenetwork", "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork" },
    { "isregistereduser", "http://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser" },
    { "ppid", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" },
    { "primarygroupsid", ClaimTypes.PrimaryGroupSid },
    { "primarysid", ClaimTypes.PrimarySid },
    { "proxy", "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy" },
    { "pwdchgurl", "http://schemas.microsoft.com/ws/2012/01/passwordchangeurl" },
    { "pwdexpdays", "http://schemas.microsoft.com/ws/2012/01/passwordexpirationdays" },
    { "pwdexptime", "http://schemas.microsoft.com/ws/2012/01/passwordexpirationtime" },
    { "relyingpartytrustid", "http://schemas.microsoft.com/2012/01/requestcontext/claims/relyingpartytrustid" },
    { "role", ClaimTypes.Role },
    { "roles", ClaimTypes.Role },
    { "upn", ClaimTypes.Upn },
    { "winaccountname", ClaimTypes.WindowsAccountName },
};

Disable JwtBearer/OpenID Connect Client Claim Type Mapping

To turn off the claim type mapping, you can set the MapInboundClaims property of JwtBearerOptions or OpenIdConnectOptions to false. Then, you can get the original claim types from the token(access_token or id_token):

JWT Example:

{
  "iss": "https://localhost:44305/",
  "exp": 1714466127,
  "iat": 1714466127,
  "aud": "MyProjectName",
  "scope": "MyProjectName offline_access",
  "sub": "ed7f5cfd-7311-0402-245c-3a123ff787f9",
  "unique_name": "admin",
  "preferred_username": "admin",
  "given_name": "admin",
  "role": "admin",
  "email": "admin@abp.io",
  "email_verified": "False",
  "phone_number_verified": "False",
}

OAuth2(Google, Facebook, Twitter, Microsoft) Extenal Login Client

The OAuth2 handler fetchs a JSON containing user information from the OAuth2 server. The third-party provider issues the claim type based on their standard server and then maps/adds it to the current ClaimsIdentity. The ASP NET Core provides some built-in claim-type mappings for different providers as can be seen below examples:

Example: The ClaimActions property of the GoogleOptions maps the Google's claim types to System.Security.Claims.ClaimTypes:

ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "id"); // v2
ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "sub"); // v3
ClaimActions.MapJsonKey(ClaimTypes.Name, "name");
ClaimActions.MapJsonKey(ClaimTypes.GivenName, "given_name");
ClaimActions.MapJsonKey(ClaimTypes.Surname, "family_name");
ClaimActions.MapJsonKey("urn:google:profile", "link");
ClaimActions.MapJsonKey(ClaimTypes.Email, "email");

Example: The ClaimActions property of the FacebookOptions maps the Facebook's claim types to System.Security.Claims.ClaimTypes:

ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "id");
ClaimActions.MapJsonSubKey("urn:facebook:age_range_min", "age_range", "min");
ClaimActions.MapJsonSubKey("urn:facebook:age_range_max", "age_range", "max");
ClaimActions.MapJsonKey(ClaimTypes.DateOfBirth, "birthday");
ClaimActions.MapJsonKey(ClaimTypes.Email, "email");
ClaimActions.MapJsonKey(ClaimTypes.Name, "name");
ClaimActions.MapJsonKey(ClaimTypes.GivenName, "first_name");
ClaimActions.MapJsonKey("urn:facebook:middle_name", "middle_name");
ClaimActions.MapJsonKey(ClaimTypes.Surname, "last_name");
ClaimActions.MapJsonKey(ClaimTypes.Gender, "gender");
ClaimActions.MapJsonKey("urn:facebook:link", "link");
ClaimActions.MapJsonSubKey("urn:facebook:location", "location", "name");
ClaimActions.MapJsonKey(ClaimTypes.Locality, "locale");
ClaimActions.MapJsonKey("urn:facebook:timezone", "timezone");

OpenIddict AuthServer

The OpenIddict uses the standard claims as the claim type of the id_token or access_token and UserInfo endpoint response, etc.

• For JWT token, it also uses the azure-activedirectory-identitymodel-extensions-for-dotnet to get the claims from the id_token or access_token.
• For reference token, it gets the claims from the database.

Summary

Once you find the claims you received do not meet your expectations, follow the instructions above to troubleshoot the problem.

This article can help you understand the claim type in the ABP Framework and ASP NET Core.

Introduction

Sharing cookies between subdomains is a common requirement in web development. For example, you have a website with multiple subdomains, and you want to share the login status between these subdomains. Once a user logs in to one subdomain, the user should be logged in to all subdomains.

This article will show you how to achieve this in an ASP.NET Core application.

Implementation principle

The cookie has a Domain attribute which specifies which server can receive a cookie. If specified, then cookies are available on the server and its subdomains. For example, if you set Domain=.abp.io, cookies are available on abp.io and its subdomains like community.abp.io.

If the server does not specify a Domain, the cookies are available on the server but not on its subdomains. Therefore, specifying the Domain is less restrictive than omitting it. However, it can be helpful when subdomains need to share information about a user.

Change the domain of the cookie in ASP.NET Core

There is a CookiePolicyMiddleware in ASP.NET Core, you can add some policies to the CookiePolicyOptions during cookies are appended or deleted.

We will add a policy to the CookiePolicyOptions to change the domain of the cookie:

services.Configure<CookiePolicyOptions>(options =>
{
    options.OnAppendCookie = cookieContext =>
    {
        ChangeCookieDomain(cookieContext, null);
    };

    options.OnDeleteCookie = cookieContext =>
    {
        ChangeCookieDomain(null, cookieContext);
    };
});

private static void ChangeCookieDomain(AppendCookieContext appendCookieContext, DeleteCookieContext deleteCookieContext)
{
    if (appendCookieContext != null)
    {
        // Change the domain of all cookies
        //appendCookieContext.CookieOptions.Domain = ".abp.io";

        // Change the domain of the specific cookie
        if (appendCookieContext.CookieName == ".AspNetCore.Culture")
        {
            appendCookieContext.CookieOptions.Domain = ".abp.io";
        }
    }

    if (deleteCookieContext != null)
    { 
        // Change the domain of all cookies
        //appendCookieContext.CookieOptions.Domain = ".abp.io";

        // Change the domain of the specific cookie
        if (deleteCookieContext.CookieName == ".AspNetCore.Culture")
        {
            deleteCookieContext.CookieOptions.Domain = ".abp.io";
        }
    }
}

Add the app.UseCookiePolicy() in the ASP.NET Core pipeline:

//...
app.UseStaticFiles();
app.UseCookiePolicy();
//...

If you check the HTTP response headers, you will see the Set-Cookie header with the domain attribute as follows:

Set-Cookie: .AspNetCore.Culture=c%3Den%7Cuic%3Den; expires=Mon, 09 Mar 2026 02:00:00 GMT; domain=.abp.io; path=/

The subdomains can share the .AspNetCore.Culture cookie now.

In another community article, we use the same middleware to fix the Chrome login issue for the IdentityServer4

Summary

The CookiePolicy middleware provides a way to control cookies in an ASP.NET Core, It is very useful if you have more complex requirements for Cookies.

What is Testcontainers?

Testcontainers is a library that provides easy and lightweight APIs for bootstrapping local development and test dependencies with real services wrapped in Docker containers.

Using Testcontainers, you can write tests that depend on the same services you use in production without mocks or in-memory services.

Get more information about Testcontainers from https://testcontainers.com/.

How to Use Testcontainers in ABP Unit Test?

ABP Framework provides a built-in unit test infrastructure, allowing you to add your unit and integration tests easily.

It uses SQLite in-memory and EphemeralMongo as the default database for unit tests and it's enough for most of the cases. However, you may need to test your code with a real database like PostgreSQL, MySQL, SQL Server, etc.

In this article, I will show you how to use Testcontainers in ABP unit tests to test your code with a real database from a Docker container.

The Testcontainers will pull the Docker images of the databases you want to use. You can pull them manually before running the tests to speed them up.

docker pull mcr.microsoft.com/mssql/server:2019-CU18-ubuntu-20.04
docker pull mongo:6.0

Code Changes For Entity Framework Core Tests

1. Remove Volo.Abp.EntityFrameworkCore.Sqlite package and add the Testcontainers.MsSql package to the MyProjectName.EntityFrameworkCore.Tests project.

<Project Sdk="Microsoft.NET.Sdk">

  <Import Project="..\..\common.props" />

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <RootNamespace>MyCompanyName.MyProjectName</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.EntityFrameworkCore\MyCompanyName.MyProjectName.EntityFrameworkCore.csproj" />
    <ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
    <PackageReference Include="Testcontainers.MsSql" Version="3.7.0" />
  </ItemGroup>

</Project>

2. Update MyProjectNameEntityFrameworkCoreFixture class as shown below:

We start an SQL Server container in the InitializeAsync method and dispose of it in the DisposeAsync method. The GetRandomConnectionString method sets a random database for each test.

using System;
using System.Threading.Tasks;
using Testcontainers.MsSql;
using Xunit;

namespace MyCompanyName.MyProjectName.EntityFrameworkCore;

public class MyProjectNameEntityFrameworkCoreFixture : IAsyncLifetime
{
    private readonly static MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build();

    public async Task InitializeAsync()
    {
        await _msSqlContainer.StartAsync();
    }

    public static string GetRandomConnectionString()
    {
        var randomDbName = "Database=Db_" + Guid.NewGuid().ToString("N");
        return _msSqlContainer.GetConnectionString().Replace("Database=master", randomDbName, StringComparison.OrdinalIgnoreCase);
    }

    public async Task DisposeAsync()
    {
        await _msSqlContainer.DisposeAsync().AsTask();
    }
}

3. Update MyProjectNameEntityFrameworkCoreTestModule class as shown below:

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.EntityFrameworkCore;
using Volo.Abp.FeatureManagement;
using Volo.Abp.Modularity;
using Volo.Abp.PermissionManagement;
using Volo.Abp.SettingManagement;
using Volo.Abp.Uow;

namespace MyCompanyName.MyProjectName.EntityFrameworkCore;

[DependsOn(
    typeof(MyProjectNameApplicationTestModule),
    typeof(MyProjectNameEntityFrameworkCoreModule)
    )]
public class MyProjectNameEntityFrameworkCoreTestModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        ConfigureMsSqlDatabase(context.Services);
    }

    private void ConfigureMsSqlDatabase(IServiceCollection services)
    {
        var connectionString = MyProjectNameEntityFrameworkCoreFixture.GetRandomConnectionString();
        using (var context = new MyProjectNameDbContext(new DbContextOptionsBuilder<MyProjectNameDbContext>()
                   .UseSqlServer(connectionString)
                   .Options))
        {
            context.Database.Migrate();
        }
        services.Configure<AbpDbContextOptions>(options =>
        {
            options.Configure(context =>
            {
                context.DbContextOptions.UseSqlServer(connectionString);
            });
        });
    }
}

The EF Core unit tests results will be like the following:

Code Changes For MongoDB Tests

1. Remove EphemeralMongo related packages and add the Testcontainers.MongoDb package to the MyProjectName.EntityFrameworkCore.Tests project.

<Project Sdk="Microsoft.NET.Sdk">

  <Import Project="..\..\common.props" />

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <RootNamespace>MyCompanyName.MyProjectName</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.MongoDB\MyCompanyName.MyProjectName.MongoDB.csproj" />
    <ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
    <PackageReference Include="Testcontainers.MongoDb" Version="3.7.0" />
  </ItemGroup>

</Project>

2. Update MyProjectNameMongoDbFixture class as shown below:

We start a MongoDB container in the InitializeAsync method and dispose of it in the DisposeAsync method. The GetRandomConnectionString method sets a random database for each test.

using System;
using System.Threading.Tasks;
using Testcontainers.MongoDb;
using Xunit;

namespace MyCompanyName.MyProjectName.MongoDB;

public class MyProjectNameMongoDbFixture : IAsyncLifetime
{
    private readonly static MongoDbContainer _mongoDbContainer = new MongoDbBuilder().WithCommand().Build();

    public async Task InitializeAsync()
    {
        await _mongoDbContainer.StartAsync();
    }

    public static string GetRandomConnectionString()
    {
        var randomDbName = "Db_" + Guid.NewGuid().ToString("N");
        return _mongoDbContainer.GetConnectionString().EnsureEndsWith('/') + randomDbName + "?authSource=admin";
    }

    public async Task DisposeAsync()
    {
        await _mongoDbContainer.DisposeAsync().AsTask();
    }
}

The MongoDB unit tests results will be like the following:

Summary

The Testcontainers works well with ABP Framework and it's easy to use. If you need to test your code with a real database, Testcontainers is a good choice for you.

While it still needs to be faster than in-memory databases, but its advantages are obvious.

Enjoy testing with Testcontainers!

The first .NET community event in 2024 was successfully held in Shenzhen on January 14, 2024.

This event is co-organized by Microsoft MVP China Team, Microsoft Reactor, China .NET Community and Shenzhen .NET Club.

ABP.IO continues to strongly support the community, and we have prepared exquisite gifts for participants.

The event includes four wonderful technical lectures to reveal big data and AI's potential opportunities and innovations. It is a transfer of knowledge and a platform for communication and cooperation among technology enthusiasts.

See you at the next community event!

China's most influential .NET event officially kicked off on December 16, 2023. Although a heavy snowfall a few days ago impacted traffic, It did not stop the enthusiastic developers.

The conference has invited 30+ technical experts from various fields to share the new features of .NET 8, full-stack Blazor, AI and .NET MAUI and other trend-setting technology highlights, focusing on the theme of Intelligent · Open Source · Security. In-depth discussion of artificial Intelligence, web development, front-end & security and other hot technical topics, and more .NET technical experts shared their valuable practical experience over the past year.

As one of the community partners of .NET Conf China 2023

Our ABP.IO China team arrived at the venue much earlier than it started and was carefully prepared to welcome the developers.

At the event, we showed developers the latest news and related updates on ABP.IO. We also held face-to-face interactive conversations with multiple developers, including senior ABP developers, framework fans and ABP Commercial customers. We listened to everyone's feedback and discussed how to make ABP.IO better serve developers.

As always, we have a raffle.

Including ABP Commercial's TEAM and PERSONAL licenses, Halil İbrahim Kalkan's latest book Mastering ABP Framework, the ABP community's popular Implementing Domain Driven Design book, Bluetooth headset and other ABP peripheral brochures, stickers...

Through this event,

We gained a lot and felt the enthusiasm and support of the developers community for ABP.IO. We will continue to work hard to provide better services for developers and contribute to the development of ABP.IO.

See you at the next community event!

This article will show you the new feature of containers with NET 8.0.

Non-root user

The Non-root user feature on net 8 is a security measure that allows users to have limited access to the system without having full administrative privileges. Hosting containers as non-root aligns with the principle of least privilege. It’s free security provided by the operating system. If you run your app as root, your app process can do anything in the container, like modify files, install packages, or run arbitrary executables. That’s a concern if your app is ever attacked. If you run your app as non-root, your app process cannot do much, greatly limiting what a bad actor could accomplish.

Default ASP.NET Core port changed from 80 to 8080

In .NET 8, there has been a change in the default port used by ASP.NET Core applications. Previously, the default port assigned to ASP.NET Core applications was 80. However, starting from .NET 8, the default port has been changed to 8080. This change was made to avoid conflicts with other applications and services that commonly use port 80, such as web servers like IIS or Apache. By using port 8080 as the default, there is less potential for clashes and easier deployment of ASP.NET Core applications alongside other services.

It's important to note that this change only affects the default port used when an ASP.NET Core application is run without explicitly specifying a port.

If you want your application to continue using port 80, you can still specify it during the application launch or configure it in the application settings.

• Recommended: Explicitly set the ASPNETCORE_HTTP_PORTS, ASPNETCORE_HTTPS_PORTS, and ASPNETCORE_URLS environment variables to the desired port. Example: docker run --rm -it -p 9999:80 -e ASPNETCORE_HTTP_PORTS=80 <my-app>
• Update existing commands and configuration that rely on the expected default port of port 80 to reference port 8080 instead. Example: docker run --rm -it -p 9999:8080 <my-app>

The dockerfile of ABP templates has been updated to use port 80.

References

• Secure your .NET cloud apps with rootless Linux Containers
• Containers breaking changes
• ASP.NET Core apps use port 8080 by default
• Docker images for ASP.NET Core

Introduction

I would love to talk about the new feature in EF Core 8.0, specifically the raw SQL queries for unmapped types. This feature was recently introduced by Microsoft and is aimed at providing more flexibility and customization in database queries.

What is the raw SQL queries for the unmapped types feature?

To give you a better understanding, let's look at a sample repository method with the ABP framework. Here is an example of a raw SQL query using the new feature:

public interface IAuthorRepository : IRepository<Author, Guid>
{
    Task<List<AuthorIdWithNames>> GetAllAuthorNamesAsync();
}

public class AuthorIdWithNames
{
    public Guid Id { get; set; }

    public string Name { get; set; }
}

public class EfCoreAuthorRepository : EfCoreRepository<BookStoreDbContext, Author, Guid>, IAuthorRepository
{
    public EfCoreAuthorRepository(IDbContextProvider<BookStoreDbContext> dbContextProvider)
        : base(dbContextProvider)
    {
    }

    public virtual async Task<List<AuthorIdWithNames>> GetAllAuthorNamesAsync()
    {
        return await (await GetDbContextAsync()).Database.SqlQuery<AuthorIdWithNames>(@$"SELECT Id, Name FROM Authors").ToListAsync();
    }
}

In this code, we can see that we are using the SqlQuery method to execute a raw SQL query on a custom type, AuthorIdWithNames in this case. This allows us to retrieve data that may not be mapped to any of our entity classes in the context.

In summary

This feature can be particularly useful in scenarios where we need to access data from tables or views that are not directly mapped to our entities. It also provides an alternative to using stored procedures for querying data.

However, it's important to note that using raw SQL queries can increase the risk of SQL injection attacks. So, it's recommended to use parameterized queries to prevent this. Additionally, this feature may not work with certain database providers, so it's important to check for compatibility before implementing it.

In conclusion, the raw SQL queries for unmapped types feature in EF Core 8.0 is a great addition for developers looking for more flexibility in database queries. It allows us to work with data that may not be directly mapped to our entities and can be a useful tool in certain scenarios. Just remember to use parameterized queries and check for compatibility before implementing it.

References

• Raw SQL queries for unmapped types
• SQL Queries

In this document we will explain how to convert BookStore's Books create & edit modals to regular razor pages.

Before

Now

Index page

Repalce abp-button(NewBookButton) buttom with <a class="btn btn-primary" href="/Books/CreateModal"><i class="fa fa-plus"></i> @L["NewBook"].Value</a>.

Index js file

Remove the related codes of createModal and editModal.

Change the Edit row action with location.href = "/Books/EditModal?id=" + data.record.id;

Create/Edit Book page

Remove Layout = null; and add some custom style and javascript code to CreateModal.cshtml & EditModal.cshtml.

@section styles {
    <style>
        .abp-view-modal .modal {
                position: static;
                display: block;
                opacity: inherit !important;
        }
        .abp-view-modal .modal.fade .modal-dialog {
            transition: inherit !important;
            transform: inherit !important;;
        }
        .abp-view-modal .modal-header .btn-close {
            display: none;
        }
    </style>
}
@section scripts {
    <script>
        $(".abp-view-modal form").abpAjaxForm().on('abp-ajax-success', function () {
            location.href = "/Books";
        });
    </script>
}

Add a div element with abp-view-modal class to wrap the abp-dynamic-form, Set size of abp-modal to ExtraLarge and remove the AbpModalButtons.Cancel button from abp-modal-footer.

CreateModal

<div class="abp-view-modal">
    <abp-dynamic-form abp-model="Book" asp-page="/Books/CreateModal">
        <abp-modal static="true" size="ExtraLarge">
            <abp-modal-header title="@L["NewBook"].Value"></abp-modal-header>
            <abp-modal-body>
                <abp-form-content />
            </abp-modal-body>
            <abp-modal-footer buttons="@(AbpModalButtons.Save)"></abp-modal-footer>
        </abp-modal>
    </abp-dynamic-form>
</div>

EditModal

<div class="abp-view-modal">
    <abp-dynamic-form abp-model="Book" asp-page="/Books/EditModal">
        <abp-modal size="ExtraLarge">
            <abp-modal-header title="@L["Update"].Value"></abp-modal-header>
            <abp-modal-body>
                <abp-form-content />
            </abp-modal-body>
            <abp-modal-footer buttons="@(AbpModalButtons.Save)"></abp-modal-footer>
        </abp-modal>
    </abp-dynamic-form>
</div>

You can check this Git commit for details.

https://github.com/abpframework/abp-samples/commit/f3014e0ec422cb2d8816d0e00dd6ab9cc1adfc21

Interceptors

EF Core 7 has made a lot of enhancements to interceptors, You can see the list from EF Core improved interceptors.

• Interception for creating and populating new entity instances (aka "materialization")
• Interception to modify the LINQ expression tree before a query is compiled
• Interception for optimistic concurrency handling (DbUpdateConcurrencyException)
• Interception for connections before checking if the connection string has been set
• Interception for when EF Core has finished consuming a result set, but before that result set is closed
• Interception for the creation of a DbConnection by EF Core
• Interception for DbCommand after it has been initialized

Lazy initialization of connection string

You generally don't need to use this feature, ABP has its own connection string feature.

The framework will automatically handle the module or multi-tenant connection string

Add interceptors in AbpDbContext

Add interceptors is very simple, Add your interceptors in the OnConfiguring method of DbContext

public class BookStoreDbContext : AbpDbContext<BookStoreDbContext>,
{

    public BookStoreDbContext(DbContextOptions<BookStoreDbContext> options)
        : base(options)
    {

    }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.AddInterceptors(new MyEfCorenterceptor());

        base.OnConfiguring(optionsBuilder);
    }
}

Some interceptors may be Singleton services. This means a single instance is used by many DbContext instances. The implementation must be thread-safe.

See the EF Core Interceptors documentation for more information.

ITokenExtensionGrant

Create a MyTokenExtensionGrant class that inherits ITokenExtensionGrant, and then register it with the framework.

public override void PreConfigureServices(ServiceConfigurationContext context)
{
    //...
    PreConfigure<OpenIddictServerBuilder>(builder =>
    {
        builder.Configure(openIddictServerOptions =>
        {
            openIddictServerOptions.GrantTypes.Add(MyTokenExtensionGrant.ExtensionGrantName);
        });
    });
    //...
}

public override void ConfigureServices(ServiceConfigurationContext context)
{
    //...
    Configure<AbpOpenIddictExtensionGrantsOptions>(options =>
    {
        options.Grants.Add(MyTokenExtensionGrant.ExtensionGrantName, new MyTokenExtensionGrant());
    });
    //...
}

Generate a new token response

In the MyTokenExtensionGrant class below we have two methods to get a new token using a user token or user API key. You can choose one of them based on your business.

These methods are just examples. Please add more logic to validate input data.

using System.Collections.Immutable;
using System.Security.Principal;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc;
using OpenIddict.Abstractions;
using OpenIddict.Server;
using OpenIddict.Server.AspNetCore;
using Volo.Abp.Identity;
using Volo.Abp.OpenIddict;
using Volo.Abp.OpenIddict.ExtensionGrantTypes;
using IdentityUser = Volo.Abp.Identity.IdentityUser;
using SignInResult = Microsoft.AspNetCore.Mvc.SignInResult;

namespace OpenIddict.Demo.Server.ExtensionGrants;

public class MyTokenExtensionGrant : ITokenExtensionGrant
{
    public const string ExtensionGrantName = "MyTokenExtensionGrant";

    public string Name => ExtensionGrantName;

    public async Task<IActionResult>  HandleAsync(ExtensionGrantContext context)
    {
        // You can get a new token using any of the following methods based on your business.
        // They are just examples. You can implement your own logic here.

        return await HandleUserAccessTokenAsync(context);
        return await HandleUserApiKeyAsync(context);
    }

    public async Task<IActionResult>  HandleUserAccessTokenAsync(ExtensionGrantContext context)
    {
        var userToken = context.Request.GetParameter("token").ToString();

        if (string.IsNullOrEmpty(userToken))
        {
            return new ForbidResult(
                new[] {OpenIddictServerAspNetCoreDefaults.AuthenticationScheme},
                properties: new AuthenticationProperties(new Dictionary<string, string>
                {
                    [OpenIddictServerAspNetCoreConstants.Properties.Error] = OpenIddictConstants.Errors.InvalidRequest
                }!));
        }

        // We will validate the user token
        // The Token is issued by the OpenIddict server, So we can validate it using the introspection endpoint

        var transaction = await context.HttpContext.RequestServices.GetRequiredService<IOpenIddictServerFactory>().CreateTransactionAsync();
        transaction.EndpointType = OpenIddictServerEndpointType.Introspection;
        transaction.Request = new OpenIddictRequest
        {
            ClientId = context.Request.ClientId,
            ClientSecret = context.Request.ClientSecret,
            Token = userToken
        };

        var notification = new OpenIddictServerEvents.ProcessAuthenticationContext(transaction);
        var dispatcher = context.HttpContext.RequestServices.GetRequiredService<IOpenIddictServerDispatcher>();
        await dispatcher.DispatchAsync(notification);

        if (notification.IsRejected)
        {
            return new ForbidResult(
                new []{ OpenIddictServerAspNetCoreDefaults.AuthenticationScheme },
                properties: new AuthenticationProperties(new Dictionary<string, string>
                {
                    [OpenIddictServerAspNetCoreConstants.Properties.Error] = notification.Error ?? OpenIddictConstants.Errors.InvalidRequest,
                    [OpenIddictServerAspNetCoreConstants.Properties.ErrorDescription] = notification.ErrorDescription,
                    [OpenIddictServerAspNetCoreConstants.Properties.ErrorUri] = notification.ErrorUri
                }));
        }

        var principal = notification.GenericTokenPrincipal;
        if (principal == null)
        {
            return new ForbidResult(
                new []{ OpenIddictServerAspNetCoreDefaults.AuthenticationScheme },
                properties: new AuthenticationProperties(new Dictionary<string, string>
                {
                    [OpenIddictServerAspNetCoreConstants.Properties.Error] = notification.Error ?? OpenIddictConstants.Errors.InvalidRequest,
                    [OpenIddictServerAspNetCoreConstants.Properties.ErrorDescription] = notification.ErrorDescription,
                    [OpenIddictServerAspNetCoreConstants.Properties.ErrorUri] = notification.ErrorUri
                }));
        }

        // We have validated the user token and got the user id

        var userId = principal.FindUserId();
        var userManager = context.HttpContext.RequestServices.GetRequiredService<IdentityUserManager>();
        var user = await userManager.GetByIdAsync(userId.Value);
        var userClaimsPrincipalFactory = context.HttpContext.RequestServices.GetRequiredService<IUserClaimsPrincipalFactory<IdentityUser>>();
        var claimsPrincipal = await userClaimsPrincipalFactory.CreateAsync(user);

        // Prepare the scopes
        var scopes = GetScopes(context);

        claimsPrincipal.SetScopes(scopes);
        claimsPrincipal.SetResources(await GetResourcesAsync(context, scopes));
        await context.HttpContext.RequestServices.GetRequiredService<AbpOpenIddictClaimsPrincipalManager>().HandleAsync(context.Request, principal);
        return new SignInResult(OpenIddictServerAspNetCoreDefaults.AuthenticationScheme, claimsPrincipal);
    }


    protected async Task<IActionResult> HandleUserApiKeyAsync(ExtensionGrantContext context)
    {
        var userApiKey = context.Request.GetParameter("user_api_key").ToString();

        if (string.IsNullOrEmpty(userApiKey))
        {
            return new ForbidResult(
                new[] {OpenIddictServerAspNetCoreDefaults.AuthenticationScheme},
                properties: new AuthenticationProperties(new Dictionary<string, string>
                {
                    [OpenIddictServerAspNetCoreConstants.Properties.Error] = OpenIddictConstants.Errors.InvalidRequest
                }!));
        }

        // Here we can validate the user API key and get the user id
        if (false) // Add your own logic here
        {
            // If the user API key is invalid
            return new ForbidResult(
                new[] {OpenIddictServerAspNetCoreDefaults.AuthenticationScheme},
                properties: new AuthenticationProperties(new Dictionary<string, string>
                {
                    [OpenIddictServerAspNetCoreConstants.Properties.Error] = OpenIddictConstants.Errors.InvalidRequest
                }!));
        }

        // Add your own logic to get the user by API key
        var userManager = context.HttpContext.RequestServices.GetRequiredService<IdentityUserManager>();
        var user = await userManager.FindByNameAsync("admin");
        if (user == null)
        {
            return new ForbidResult(
                new[] {OpenIddictServerAspNetCoreDefaults.AuthenticationScheme},
                properties: new AuthenticationProperties(new Dictionary<string, string>
                {
                    [OpenIddictServerAspNetCoreConstants.Properties.Error] = OpenIddictConstants.Errors.InvalidRequest
                }!));
        }

        // Create a principal for the user
        var userClaimsPrincipalFactory = context.HttpContext.RequestServices.GetRequiredService<IUserClaimsPrincipalFactory<IdentityUser>>();
        var claimsPrincipal = await userClaimsPrincipalFactory.CreateAsync(user);

        // Prepare the scopes
        var scopes = GetScopes(context);

        claimsPrincipal.SetScopes(scopes);
        claimsPrincipal.SetResources(await GetResourcesAsync(context, scopes));
        await context.HttpContext.RequestServices.GetRequiredService<AbpOpenIddictClaimsPrincipalManager>().HandleAsync(context.Request, claimsPrincipal);
        return new SignInResult(OpenIddictServerAspNetCoreDefaults.AuthenticationScheme, claimsPrincipal);
    }

    private ImmutableArray<string> GetScopes(ExtensionGrantContext context)
    {
        // Prepare the scopes
        // The scopes must be defined in the OpenIddict server

        // If you want to get the scopes from the request, you have to add `scope` parameter in the request
        // scope: AbpAPI profile roles email phone offline_access

        //var scopes = context.Request.GetScopes();

        // If you want to set the scopes here, you can use the following code
        var scopes = new[] { "AbpAPI", "profile", "roles", "email", "phone", "offline_access" }.ToImmutableArray();

        return scopes;
    }

    private async Task<IEnumerable<string>> GetResourcesAsync(ExtensionGrantContext context, ImmutableArray<string> scopes)
    {
        var resources = new List<string>();
        if (!scopes.Any())
        {
            return resources;
        }

        await foreach (var resource in context.HttpContext.RequestServices.GetRequiredService<IOpenIddictScopeManager>().ListResourcesAsync(scopes))
        {
            resources.Add(resource);
        }
        return resources;
    }
}

Get a new token using user access token

• Get a user token using the password grant type.

• Use the user token to get a new token using the HandleUserAccessTokenAsync method.

Get a new token using user API key

• Directly get a new token using the HandleUserApiKeyAsync method.

Source code

https://github.com/abpframework/abp/blob/dev/modules/openiddict/app/OpenIddict.Demo.Server/ExtensionGrants/MyTokenExtensionGrant.cs

Source Code

You can find the source of the example solution used in this article here.

In this article, I will use bUnit for a simple test of a Blazor component.

Getting Started

Use the ABP CLI to create a blazor app

abp new BookStore -t app -u blazor

Then add the BookStore.Blazor.Tests xunit test project to the solution, and add bUnit package and ProjectReference to the test project.

The contents of BookStore.Blazor.Tests.csproj

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>

        <IsPackable>false</IsPackable>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="bunit" Version="1.28.9" />
        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
        <PackageReference Include="Volo.Abp.Authorization.Abstractions" Version="8.1.1" />
        <PackageReference Include="xunit" Version="2.7.1" />
        <PackageReference Include="xunit.runner.visualstudio" Version="2.5.8">
            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
            <PrivateAssets>all</PrivateAssets>
        </PackageReference>
        <PackageReference Include="coverlet.collector" Version="6.0.2">
            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
            <PrivateAssets>all</PrivateAssets>
        </PackageReference>
    </ItemGroup>

    <ItemGroup>
      <ProjectReference Include="..\..\src\BookStore.Blazor\BookStore.Blazor.csproj" />
      <ProjectReference Include="..\BookStore.EntityFrameworkCore.Tests\BookStore.EntityFrameworkCore.Tests.csproj" />
    </ItemGroup>

</Project>

Create BookStoreBlazorTestModule that depends on AbpAspNetCoreComponentsModule and BookStoreEntityFrameworkCoreTestModule.

[DependsOn(
    typeof(AbpAspNetCoreComponentsModule),
    typeof(BookStoreEntityFrameworkCoreTestModule)
)]
public class BookStoreBlazorTestModule : AbpModule
{

}

Create a BookStoreBlazorTestBase class and add the CreateTestContext method. The CreateTestContext have key code.

It creates a AutofacServiceProvider and add all ABP's services to the TestContext.

public abstract class BookStoreBlazorTestBase : BookStoreTestBase<BookStoreBlazorTestModule>
{
    protected virtual TestContext CreateTestContext()
    {
        var testContext = new TestContext();
        var blazorise = testContext.JSInterop.SetupModule("./_content/Blazorise/utilities.js?v=1.5.1.0");
        blazorise.SetupVoid("log", _ => true);

        testContext.Services.UseServiceProviderFactory(serviceCollection =>
        {
            foreach (var service in ServiceProvider.GetRequiredService<IAbpApplicationWithExternalServiceProvider>().Services)
            {
                serviceCollection.Add(service);
            }
            var containerBuilder = new ContainerBuilder();
            containerBuilder.Populate(serviceCollection);
            return new AutofacServiceProvider(containerBuilder.Build());
        });

        testContext.Services.AddBlazorise().AddBootstrap5Providers().AddFontAwesomeIcons();
        testContext.Services.Replace(ServiceDescriptor.Transient<IComponentActivator, ServiceProviderComponentActivator>());

        return testContext;
    }
}

Finally, we add an Index_Tests class to test the Index component.

public class Index_Tests : BookStoreBlazorTestBase
{
[Fact]
    public void Index_Test()
    {
        // Arrange
        var ctx = CreateTestContext();

        // Act
        var cut = ctx.RenderComponent<BookStore.Blazor.Pages.Index>();

        // Assert
        cut.Find(".lead").InnerHtml.Contains("Welcome to the application. This is a startup project based on the ABP framework. For more information, visit abp.io.").ShouldBeTrue();
        cut.Find("#username").InnerHtml.Contains("Welcome admin").ShouldBeTrue();
    }
}

Reference document

https://github.com/bUnit-dev/bUnit

https://docs.microsoft.com/en-us/aspnet/core/blazor/test

This is an example project that demonstrates using MiniProfiler with the ABP Framework. See the article that explain this project:

https://abp.io/community/posts/using-miniprofiler-with-the-abp-framework-6el5dziz

https://github.com/abpframework/abp-samples/tree/master/MiniProfiler

https://github.com/abpframework/abp-samples/tree/master/MiniProfiler-Tiered

Source Code

You can find the source of the example solution used in this article here.

Getting Started

This example is based on the following document https://docs.abp.io/en/abp/latest/Localization#extending-existing-resource

We will change the default DisplayName:Abp.Timing.Timezone and Description:Abp.Timing.Timezone of AbpTimingResource and add localized text in Russian language(ru).

I created the AbpTiming folder in the Localization directory of the ExtendLocalizationResource.Domain.Shared project.

Create en.json and ru.json in its directory.

en.json

{
  "culture": "en",
  "texts": {
    "DisplayName:Abp.Timing.Timezone": "My Time zone",
    "Description:Abp.Timing.Timezone": "My Application time zone"
  }
}

ru.json

{
  "culture": "ru",
  "texts": {
    "DisplayName:Abp.Timing.Timezone": "Часовой пояс",
    "Description:Abp.Timing.Timezone": "Часовой пояс приложения"
  }
}

We have below content in ExtendLocalizationResource.Domain.Shared.csproj file, See Virtual-File-System understand how it works.

<ItemGroup>
    <EmbeddedResource Include="Localization\ExtendLocalizationResource\*.json" />
    <Content Remove="Localization\ExtendLocalizationResource\*.json" />
</ItemGroup>

<ItemGroup>
    <PackageReference Include="Microsoft.Extensions.FileProviders.Embedded" Version="5.0.*" />
</ItemGroup>

Change the code of the ConfigureServices method in ExtendLocalizationResourceDomainSharedModule.

Configure<AbpLocalizationOptions>(options =>
{
    options.Resources
        .Add<ExtendLocalizationResourceResource>("en")
        .AddBaseTypes(typeof(AbpValidationResource))
        .AddVirtualJson("/Localization/ExtendLocalizationResource");

    //add following code
    options.Resources
        .Get<AbpTimingResource>()
        .AddVirtualJson("/Localization/AbpTiming");

    options.DefaultResourceType = typeof(ExtendLocalizationResourceResource);
});

Execute ExtendLocalizationResource.DbMigrator to migrate the database and run ExtendLocalizationResource.Web.

We have changed the English localization text and added Russian localization.

Index page

<p>@AbpTimingResource["DisplayName:Abp.Timing.Timezone"]</p>
@using(CultureHelper.Use("ru"))
{
    <p>@AbpTimingResource["DisplayName:Abp.Timing.Timezone"]</p>
}