ABP.IO Stories

QuickGrid in .NET 11: Sorting and Paging That Live in the URL

Tue, 29 Sep 2026 11:51:55 Z

QuickGrid in .NET 11: Sorting and Paging That Live in the URL

Release status. Everything in this article was built and tested on .NET 11 RC1 (SDK 11.0.100-rc.1.26425.128, Microsoft.AspNetCore.Components.QuickGrid 11.0.0-rc.1.26425.128, released September 8, 2026). RC1 ships with a go-live license, but it is not the final release. Query parameter names and defaults described here are the RC1 behavior — they were renamed once during the previews (details below), so recheck them when you move to RC2 or GA, planned for .NET Conf in November 2026.

QuickGrid has always been a good data grid with one structural limitation: its sort column, sort direction, and page index lived only in component memory, and its controls were

Building a Vendor Onboarding Workflow with ABP Low-Code

Mon, 13 Jul 2026 12:51:56 Z

Building a Vendor Onboarding Workflow with ABP Low-Code

Vendor onboarding usually starts with a few familiar steps.

A company sends its details, someone checks the documents, another person reviews the score, and the team either approves the vendor or asks for more information. After a while, the process turns into a mix of spreadsheets, uploaded files, status notes, and "who is waiting on this one?" messages.

In this article, we'll build that workflow with the Low-Code System. We'll model the data in the Low-Code Designer, let the React runtime render the page, and then add one custom endpoint for a summary that does not belong to normal CRUD.

The example is an internal operations page where a team receives vendor applications, reviews compliance documents, tracks deadlines, and follows rejected or priority vendors from one place.

That is a good place to try ABP Low-Code, because the first version of the workflow is mostly data, screens, validation rules, and a few process-specific actions. You do not need to hand-write a React page only to list vendor applications, upload a compliance document, or show a rejection reason when the status is rejected.

We will start from an already running ABP React + EF Core application with Low-Code enabled, so the article can stay focused on the Admin Console, the Designer, and the runtime flow.

What We Are Building

The workflow has one main record: VendorApplication.

A reviewer should be able to:

Create a vendor application with company and contact details.
Track whether the vendor is Submitted, InReview, Approved, or Rejected.
Set the requested date and approval deadline.
Mark priority vendors.
Assign a category such as Software, Services, or Hardware.
Upload a logo and a compliance document.
Fill in a rejection reason only when the application is rejected.
Filter the generated grid by status, requested date, priority, and category.
Call a summary endpoint that returns counts for dashboard-like use.

We'll also touch two extra pieces around that main record. VendorReviewTemplate comes from C# so you can see how code-defined metadata appears in the Designer. Later, a VendorEscalation model is added while the Designer is switched to Runtime JSON. You could build the whole workflow with one entry point, but using these three entry points makes the hybrid model visible without turning the article into three separate implementations.

A Quick Note on How Low-Code Fits Together

The Low-Code Designer is where you describe the model and the UI metadata. In this article we use four areas:

Data for enums and entities.
Pages for the generated grid route.
Forms for the create/edit form layout.
Actions for the custom HTTP endpoint.

The Designer stores metadata. The React runtime reads that metadata and renders the page at runtime. That is the important mental model: when we add a field to the entity, the field can become a grid column, a filter, a validation rule, or a form input depending on how we configure the metadata around it.

There is also one database detail to keep in mind. Metadata that comes from C# code or from Dev JSON is source-controlled application metadata. When it introduces or changes a persisted entity, run the normal EF Core migration and database update flow before using the generated runtime page. In the validated demo for this article I used SQLite, so the migration updated the local SQLite database. Runtime JSON is different: it is authored at runtime, so I do not run a C# migration in that section.

Add a Code-Defined Review Template

Let's start with one model that does not come from the Designer.

In this workflow, vendor reviewers can use review templates. The template itself is not the center of the workflow, so I kept it focused on the review rules:

[DynamicEnum]
public enum VendorReviewTemplateType
{
    Standard = 0,
    Security = 1,
    Finance = 2
}

[DynamicEntity(DefaultDisplayPropertyName = nameof(Name))]
[DynamicEntityUI(DisplayName = "Vendor Review Templates")]
public class VendorReviewTemplate : DynamicEntityBase
{
    [Required]
    [StringLength(128)]
    [DynamicPropertyUnique]
    public string Name { get; set; }

    public VendorReviewTemplateType TemplateType { get; set; }
    public int MinimumComplianceScore { get; set; }
    public bool RequiresDocumentReview { get; set; }
    public string? Notes { get; set; }
}

Then include the entity in your EF Core DbContext. This is the part that makes the migration create a real backing table for the code-defined model:

public DbSet VendorReviewTemplates { get; set; }

builder.Entity(b =>
{
    b.ToTable(
        VendorOnboardingLowCodeConsts.DbTablePrefix + "VendorReviewTemplates",
        VendorOnboardingLowCodeConsts.DbSchema
    );
    b.ConfigureByConvention();
    b.Property(x => x.Name).IsRequired().HasMaxLength(128);
    b.Property(x => x.Notes).HasMaxLength(512);
    b.HasIndex(x => x.Name).IsUnique();
});

Because this model is defined in C#, treat it like the rest of your application schema changes: add the entity, add the DbSet/mapping, create/apply the EF Core migration, and then start the application.

After the app starts, open Admin Console > Low-Code Designer > Data. The model is visible there, but it is read-only because it was defined in code.

Open the Properties tab and you can see the fields that came from the C# class. They are available to the Low-Code System, but the Designer marks them as code-owned.

That is useful in real projects. Some metadata can be shipped with the application, while the rest of the workflow can still be designed through the Admin Console.

Create the Vendor Enums

Now move to the part we actually build in the Designer.

The animation below shows the Designer path in one pass. The next sections slow it down and explain the enum, entity, page, and form steps.

Open Data > Enums and create the status enum:

VendorApplicationStatus
Submitted
InReview
Approved
Rejected

Before saving, the enum modal should contain the name and the four values:

Then create the category enum:

VendorCategory
Software
Services
Hardware

The order of the status values matters for the custom endpoint later, because the script checks the enum values by their numeric indexes. In this example Submitted is 0, Approved is 2, and Rejected is 3.

After saving, the enum detail page shows the numeric values that the runtime and scripts will use:

Create the VendorApplication Entity

Go to Data > Entities and create VendorApplication.

This is the model that drives the rest of the article. Add these fields:

| Field | Type | Configuration | | --- | --- | --- | | CompanyName | String | Required and unique | | ContactEmail | String | Required, email validation | | Status | Enum | VendorApplicationStatus | | RequestedOn | Date | Application date | | ApprovalDeadline | Date | Review deadline | | IsPriority | Boolean | Priority flag | | Category | Enum | VendorCategory | | ComplianceScore | Int | Review score | | Logo | Image | Logo upload | | ComplianceDocument | File | Document upload | | RejectionReason | String | Optional |

The Properties tab is where the entity becomes more than a name. The table shows the field types, enum bindings, and source layer. Scroll down and the upload-related fields are visible with their Image and File types:

There is no React code yet, but we already have a lot of behavior described: required fields, uniqueness, email validation, enum fields, upload fields, and the data shape that the runtime will use.

The Image and File types are worth calling out. They are not plain strings with a path. In the generated form they become upload controls, which is exactly what we need for vendor logos and compliance documents.

Since VendorApplication is authored in the Dev JSON layer, it also belongs to the source-controlled model. After saving the entity metadata, create/apply the EF Core migration before you open the generated page in the runtime. This is the step that creates the backing table for the low-code entity in the database.

Generate a Grid Page

The reviewers need a page where they can work with applications, so go to Pages and create a dataGrid page named vendor-onboarding.

Bind it to VendorApplication.

Before saving the page, the modal connects the route name, title, icon, and entity:

After the page is created, set RequestedOn as the default sort field, keep it descending, adjust the icon if you want, and assign vendor-application-form as the create/edit form:

For the review workflow, keep the configured columns focused on the fields reviewers use most:

Company name
Status
Requested date
Priority
Category

Then configure the filters you want reviewers to use most often. In this workflow, the important filters are company, status, requested date, priority, and category. Depending on the runtime defaults, the generated grid may still expose additional fields such as contact email; the workflow is still driven by the focused page metadata above.

Once the page is saved, the React runtime can resolve the route from the page metadata. The grid is generated from the entity and page configuration rather than from a hand-written React component.

Build the Create/Edit Form

A grid is not enough. We also need a form that feels like the workflow.

Go to Forms and create vendor-application-form for VendorApplication. Split the fields into three tabs:

Company: CompanyName, ContactEmail, Category, IsPriority
Review: Status, RequestedOn, ApprovalDeadline, ComplianceScore, RejectionReason
Documents: Logo, ComplianceDocument

Now add the conditional behavior for RejectionReason. In this demo I used two complementary rules: one rule shows the field when Status = Rejected, and the other hides it for non-rejected statuses.

This is one of the places where Low-Code becomes more than "generate a CRUD page". The runtime does more than render a static form; it evaluates the rule while the user edits the record.

Apply the Migration Before Opening the Runtime

Before opening the generated page, apply the database migration for the Dev JSON changes. We used Dev JSON for VendorApplication, so the Designer wrote source-controlled descriptor files under _Dynamic. The entity shape is now part of the application model, and the database needs the matching backing table before the React runtime can save records.

That is why Dev JSON is a good fit during development: the metadata files and the EF Core migration can be reviewed, committed, and reproduced in another environment. If the same entity had been created in the Runtime JSON layer, you would not create a C# migration for that runtime edit; the metadata change would be stored in the database instead. In practice, use Dev JSON for development-time, source-controlled changes, and use Runtime JSON when you want production-time changes to be managed from the Admin Console and persisted in the database.

Try It in the React Runtime

Open the generated vendor-onboarding page in the React runtime and create a vendor application.

On the Documents tab, the Logo and ComplianceDocument fields are rendered as upload fields:

Now edit a record and change the status to Rejected. The RejectionReason field becomes available on the Review tab:

After saving a few records, use the generated filters to narrow the list to rejected vendors. Depending on the runtime configuration, the filter panel can expose more fields than the small set you configured for the workflow; here we only use the Status = Rejected filter:

The short animation below gives a quick pass through the same runtime states: upload fields, the conditional rejection reason, and the filtered grid.

At this point we have a working page, form, validation, uploads, and filters. The important part is that all of it came from the metadata we configured in the Designer.

Add a Custom Summary Endpoint

Generated CRUD is enough for day-to-day record editing, but teams often need one operation that is specific to their process.

For vendor onboarding, a summary endpoint is a good example:

GET /api/custom/vendor-onboarding/summary

In the Designer, open Actions and create a custom HTTP action with that route. The script can use the Scripting API to query the same VendorApplication data that the generated grid uses.

Here is the script used in the demo:

var entityName = 'Acme.VendorOnboardingLowCode.Procurement.VendorApplication';
var vendorQuery = await db.query(entityName);
var totalVendors = await db.count(entityName);
var submittedVendors = await vendorQuery.where(x => x.Status === 0).count();
var approvedVendors = await vendorQuery.where(x => x.Status === 2).count();
var today = query.today || new Date().toISOString().slice(0, 10);
var overdueReviews = await vendorQuery
  .where(x => x.ApprovalDeadline != null && x.ApprovalDeadline < today && x.Status !== 2)
  .count();

return ok({
  totalVendors: totalVendors,
  submittedVendors: submittedVendors,
  approvedVendors: approvedVendors,
  overdueReviews: overdueReviews,
  evaluatedOn: today
});

Use the entity name shown in your Designer. In the screenshots, it is Acme.VendorOnboardingLowCode.Procurement.VendorApplication.

When the endpoint runs, it returns the current counts from the low-code records:

That is the bridge I like here. The page and form stay metadata-driven, but the process-specific summary is a short script exposed as a custom endpoint.

Add One Runtime Model

Now switch the Designer layer to Runtime JSON and add one more entity: VendorEscalation.

This model represents the items that need extra attention. It could have been created in the same place as VendorApplication; I am adding it here only to show that runtime-authored metadata participates in the same Low-Code System.

Unlike the code and Dev JSON examples above, this runtime-authored model is not part of the source-controlled migration flow in this walkthrough.

The create modal is the same Designer experience, but the selected layer is now Runtime JSON:

Create a data grid page for it and open it in the React runtime:

From the user's point of view, it behaves like the first generated page. From the metadata point of view, we have now seen code-defined metadata, Designer-authored metadata, and runtime-authored metadata in the same application.

Read the Same Data from ABP Code

The last bridge is application code.

Sometimes the generated page is not the only consumer. You may want a typed application service, a scheduled job, or another API to read the same low-code records. The code below shows the idea by returning a backlog summary:

private readonly IRepository _vendorApplicationRepository;
private readonly IAsyncQueryableExecuter _queryableExecuter;

public async Task GetBacklogAsync()
{
    var entityDescriptor = DynamicModelManager.Instance.Find(
        "Acme.VendorOnboardingLowCode.Procurement.VendorApplication"
    );

    if (entityDescriptor == null)
    {
        throw new UserFriendlyException("VendorApplication model was not found.");
    }

    var query = await _vendorApplicationRepository
        .SetEntityName(entityDescriptor.Name)
        .GetQueryableAsync();
    var today = DateOnly.FromDateTime(Clock.Now);
    var priorityQuery = query.Where(vendor =>
        vendor.Data["IsPriority"] != null &&
        (bool?)vendor.Data["IsPriority"] == true);

    var nextPriorityVendor = await _queryableExecuter.FirstOrDefaultAsync(
        priorityQuery.OrderByDescending(vendor =>
            (DateOnly?)vendor.Data["RequestedOn"]));

    return new VendorBacklogDto
    {
        TotalVendors = checked((int)await _queryableExecuter.LongCountAsync(query)),
        PriorityVendors = checked((int)await _queryableExecuter.LongCountAsync(priorityQuery)),
        RejectedVendors = checked((int)await _queryableExecuter.LongCountAsync(
            query.Where(vendor =>
                vendor.Data["Status"] != null &&
                (int?)vendor.Data["Status"] == 3))),
        OverdueReviews = checked((int)await _queryableExecuter.LongCountAsync(
            query.Where(vendor =>
                vendor.Data["ApprovalDeadline"] != null &&
                (DateOnly?)vendor.Data["ApprovalDeadline"] < today &&
                vendor.Data["Status"] != null &&
                (int?)vendor.Data["Status"] != 2))),
        NextPriorityVendor = nextPriorityVendor?.GetData("CompanyName")
    };
}

The important detail is that the aggregate operations stay on IQueryable; the code does not load every vendor into memory just to count them. This is not a replacement for the generated page. It is the other direction: use the generated page for the admin experience, then read the same records from normal ABP code when another part of the application needs them.

Going Further

The workflow we built is intentionally focused, but the same shape can grow in a few directions:

Add permissions around the generated pages and custom endpoint.
Add more form rules for review-specific fields.
Add an approval notification after a vendor is accepted.
Add a scheduled job that checks overdue applications.
Build a dashboard widget on top of the summary endpoint.

The main pattern stays the same: model the data in the Low-Code Designer, let the React runtime render the operational page, and add code or scripting only for the parts that are specific to your business process.

Conclusion

ABP Low-Code is useful when the first version of a business workflow is mostly metadata: entities, fields, filters, forms, validation, uploads, and a few custom actions.

In this vendor onboarding example, the VendorApplication model gave us a generated grid and form, the runtime handled upload fields and conditional UI, and a custom endpoint added the summary that CRUD would not provide by itself. We also saw that low-code metadata can come from the Designer, from runtime JSON, or from C# code when you need that bridge.

That is the part worth remembering: you can start with a working admin experience quickly, then extend the workflow where the generated behavior stops being enough.

Introducing ABP Low-Code: Build Real ABP Apps in Minutes

Mon, 13 Jul 2026 12:44:16 Z

Introducing ABP Low-Code: Build Real ABP Apps in Minutes

Create runtime-managed pages, generated React screens, code-first C# entities, and Script API extensions without leaving the ABP application model.

The opening loop below is the outcome this article is proving: one ABP application moving from runtime editing to generated operational screens and then into code-backed extension points.

Want to try the same path? Start from ABP Studio, enable the Low-Code runtime and designer, define pages in the Admin Console, and see them resolve inside the running ABP app.

ABP Low-Code at a glance

Built into the ABP Platform

Low-code is most useful when speed does not create a separate stack to maintain later.

That is where many low-code products start to strain. They move quickly at the beginning, then force a second implementation track when the app needs permissions, auditability, custom logic, or tighter integration with existing application code.

ABP Low-Code takes a different path. It runs inside the ABP Platform, so runtime-managed pages are part of an application foundation that already includes identity, permissions, audit logging, APIs, and code-level extensibility.

Edit at runtime. See it in the app.

In the Low-Code Designer inside the Admin Console, you update a runtime-managed page. A few seconds later, the same application surface is visible in the live app. No rebuild loop. No parallel front-end implementation. No "we will wire it later" gap between authoring and runtime.

ABP Low-Code shortens the cycle from model change to running screen while keeping the output grounded in the same ABP application.

The screenshot below shows that authoring step directly: a runtime page is being configured in the Admin Console's Low-Code Designer, where low-code defines the grid, form, actions, and view composition that the live application will resolve.

What this shows: authoring and runtime are connected. Pages are defined in the designer and resolved in the running application.

CRUD is table stakes

If low-code only saves you from drawing a table and a form, it is not enough. Business applications need richer operational surfaces.

In the generated app, the Events screen ships with search, actions, filters, and form-driven editing. The form structure already understands tabs, relations, validation, and business-shaped input instead of leaving you with a blank shell to finish by hand.

The next GIF shows the actual runtime page produced from that model: first the generated Events grid with operational actions, then the generated form with structured inputs instead of a blank CRUD shell.

The point is not just generated CRUD. It is generated CRUD that already looks like the operational screens teams maintain in real applications.

One model, multiple operational screens

Business users do not think in one view. Operators want a calendar for scheduling, a kanban board for workflow, a grid for bulk operations, a gallery when media matters, and a dashboard when they need the state of the business at a glance.

ABP Low-Code keeps those surfaces attached to the same underlying model. The same Session model can appear as a calendar for planning and a kanban pipeline for operational flow. The same generated app can also include a speaker gallery and an overview dashboard for metrics.

The next GIF keeps the same Session model but changes how the team works with it: calendar for planning, then kanban for operational flow, without rebuilding a second screen by hand.

The dashboard screenshot below continues that same application story. It is another surface generated around the same underlying data, this time optimized for KPIs, counts, and current operational status.

This is where ABP Low-Code starts to feel less like a form generator and more like a runtime application layer: one model, many working screens, no second implementation track for each view type.

When low-code needs code

The real differentiator is not that ABP Low-Code can go fast. It is that speed does not require isolation from the application foundation.

When generated CRUD is not enough, you extend the same app instead of throwing the low-code layer away.

ABP Low-Code exposes a server-side Script API inside the same application model. That scripting surface can back:

Custom endpoints when the UI needs an API-shaped response.
Interceptors when create or update commands need validation or mutation.
Event handlers when logic should react to runtime events.
Background jobs when work should continue asynchronously.
Background workers when operational logic should run on a schedule.

In this article, the visible proof happens to be GET /api/custom/eventflow/highlights. The next GIF focuses on an endpoint because it is the easiest proof surface to read. But the broader point is that endpoints are only one consumer of the same low-code scripting layer.

That hybrid model matters in both directions:

Code-first ABP entities can be surfaced in low-code flows and runtime pages.
Low-code-managed data and screens stay reachable from Script API actions, application services, repository queries, and custom endpoints.
Teams do not lose architectural control just because they gained a faster authoring layer.

The next GIF steps into that Script API surface. In the same Admin Console, a script-backed low-code endpoint is opened, executed from the built-in test area, and its returned payload is shown immediately below so you can see runtime data flowing through an API-shaped contract.

The actual capability is the shared ABP application model behind it: script when runtime logic is enough, C# when typed application services and repository queries are the better fit.

This is the difference between "low-code as a shortcut" and "low-code as part of your application platform."

From code-first entity to generated page

The first direction is code-first to low-code. A code-first SponsorActivation entity checked into the ASP.NET Core project can still become a working runtime page without forking into a separate low-code-only model.

The code-first entity carries the same metadata that ABP Low-Code uses to generate the page:

[DynamicEntity(DefaultDisplayPropertyName = nameof(CompanyName))]
[DynamicEntityUI("Sponsor Activations")]
[DynamicEntityAttachments("application/pdf", "image/*", MaxFileCount = 4)]
public class SponsorActivation : DynamicEntityBase
{
    [Required]
    [DynamicPropertyUI(DisplayName = "Sponsor")]
    public string CompanyName { get; private set; }

    [Required]
    [EmailAddress]
    [DynamicPropertyUI(DisplayName = "Contact Email")]
    public string ContactEmail { get; private set; }

    public SponsorActivationStatus Status { get; set; }

    [DynamicForeignKey("EventFlow.Events.Event", "Title")]
    public Guid? EventId { get; set; }

    [DynamicForeignKey("Volo.Abp.Identity.IdentityUser", nameof(IdentityUser.UserName), ForeignAccess.View)]
    public Guid? OwnerUserId { get; set; }

    [DynamicPropertyType(EntityPropertyType.Money)]
    public decimal ActivationBudget { get; set; }

    [DynamicPropertyImageOptions("image/png", "image/jpeg")]
    public string? BrandLogo { get; set; }

    [DynamicPropertyFileOptions("application/pdf", ".pptx", ".docx")]
    public string? ActivationBrief { get; set; }
}

That class lives as normal C# source, gets migrated like the rest of the application, and is seeded with real records so the runtime page does not open as an empty shell.

Inside the designer, selecting the SponsorActivation entity auto-generates the page identity, binds the grid to the entity, and lands on a real runtime route at /dynamic/sponsor-activation. The generated surface includes sponsor, email, event lookup, owner lookup, budget, image, and file fields directly from the C# model.

The next GIF shows that bridge in action: a new code-first SponsorActivation entity is selected inside low-code, a page is generated from its metadata, and the resulting runtime route opens with the modeled fields already wired in.

The screenshot after that is the resulting page, not a placeholder. You are looking at the generated form that came from the C# entity definition, including lookups, budget handling, image upload, and file upload fields.

That is the distinction that matters: code-first ABP entities can move through low-code without becoming throwaway artifacts, and low-code-generated surfaces remain part of the same application story.

Low-code data stays reachable from C#

The bridge also works in the other direction. A normal ABP application service can query a low-code model through IRepository, apply real filters, and combine that result with code-first aggregates.

The service behind the endpoint in the previous section looks like this:

public async Task GetHybridSummaryAsync()
{
    var liveSessionQuery = (await _dynamicEntityRepository
            .SetEntityName("EventFlow.Events.Session")
            .GetQueryableAsync())
        .Where("int(it[\"Status\"]) == @0", 2);

    var publicSessionQuery = liveSessionQuery
        .Where("bool(it[\"IsPublic\"]) == @0", true);

    var sponsorQuery = (await _sponsorActivationRepository.GetQueryableAsync())
        .Where(activation =>
            activation.Status == SponsorActivationStatus.Approved ||
            activation.Status == SponsorActivationStatus.Live);

    var liveSessionCount = await AsyncExecuter.CountAsync(liveSessionQuery);
    var publicSessionCount = await AsyncExecuter.CountAsync(publicSessionQuery);
    var activeSponsorActivationCount = await AsyncExecuter.CountAsync(sponsorQuery);

    return new EventFlowLowCodeProofDto
    {
        LiveSessionCount = liveSessionCount,
        PublicSessionCount = publicSessionCount,
        ActiveSponsorActivationCount = activeSponsorActivationCount
    };
}

Here, low-code-managed Session rows are filtered from C# with real Where(...) clauses, then combined with the typed SponsorActivation repository. The endpoint and dashboard are just one presentation surface for that shared ABP query path.

That is the ABP difference: low-code data stays reachable from code, and code-first entities stay reachable from low-code.

Why ABP Low-Code matters

The value is not novelty. It is a faster way to build real business applications without separating speed from the application foundation.

Speed without replatforming. Runtime-managed screens reduce delivery time without moving the team onto a separate application stack.
Governance without friction. Permissions, identity, auditability, and ABP platform foundations stay part of the story from day one.
Extensibility without rewrite pressure. When custom behavior shows up, the same application can be extended instead of replacing the low-code output.

That is the core ABP Low-Code promise: faster delivery, still inside the application model you can extend.

Try it yourself

The public starting point for ABP Low-Code is ABP Studio.

The screenshot below is the exact toggle in the ABP Studio solution wizard where low-code runtime and designer support are enabled for a new ABP solution.

Open ABP Studio and create a new solution.
In the solution wizard, enable Include Low-Code runtime and designer.
Complete the wizard, then run the generated backend and React UI from the solution.
Sign in with the administrator account created for that solution.
Open Admin Console to define runtime-managed entities, forms, pages, permissions, endpoints, and script actions.
Switch to the application side to see those changes resolve live in the running app.

Building Dynamic XML Sitemaps with ABP Framework

Mon, 15 Dec 2025 11:58:47 Z

Building Dynamic XML Sitemaps with ABP Framework

Search Engine Optimization (SEO) is crucial for any web application that wants to be discovered by users. One of the most fundamental SEO practices is providing a comprehensive XML sitemap that helps search engines crawl and index your website efficiently. In this article, we'll use a reusable ABP module that automatically generates dynamic XML sitemaps for both static Razor Pages and dynamic content from your database.

By the end of this tutorial, you'll have a production-ready sitemap solution that discovers your pages automatically, includes dynamic content like blog posts or products, and regenerates sitemaps in the background without impacting performance.

What is an XML Sitemap?

An XML sitemap is a file that lists all important pages of your website in a structured format that search engines can easily read. It acts as a roadmap for crawlers like Google, Bing, and others, telling them which pages exist, when they were last updated, and how they relate to each other.

For modern web applications with dynamic content, manually maintaining sitemap files quickly becomes impractical. A dynamic sitemap solution that automatically discovers and updates URLs is essential for:

Large content sites with frequently changing blog posts, articles, or products
Multi-tenant applications where each tenant may have different content
Enterprise applications with complex page hierarchies
E-commerce platforms with thousands of product pages

Why Build a Custom Sitemap Module?

While there are general-purpose sitemap libraries available, building a custom module for ABP Framework provides several advantages:

✅ Deep ABP Integration: Leverages ABP's dependency injection, background workers, and module system ✅ Automatic Discovery: Uses ASP.NET Core's Razor Page infrastructure to automatically find pages ✅ Type-Safe Configuration: Strongly-typed attributes and options for configuration ✅ Multi-Group Support: Organize sitemaps by logical groups (main, blog, products, etc.) ✅ Background Generation: Non-blocking sitemap regeneration using ABP's background worker system ✅ Repository Integration: Direct integration with ABP repositories for database entities

Project Architecture Overview

Before using the module, let's understand its architecture:

The sitemap module consists of several key components:

Discovery Layer: Discovers Razor Pages and their metadata using reflection
Source Layer: Defines contracts for providing sitemap items (static pages and dynamic content)
Collection Layer: Collects items from all registered sources
Generation Layer: Transforms collected items into XML format
Management Layer: Orchestrates file generation and background workers

Installation

To get started, clone the demo repository which includes the sitemap module:

git clone https://github.com/salihozkara/AbpSitemapDemo
cd AbpSitemapDemo

The repository contains the sitemap module in the Modules/abp.sitemap/ directory. To use it in your own project, add a project reference:

Module Configuration

After installing the package, add the module to your ABP application's module class:

using Abp.Sitemap.Web;

[DependsOn(
    typeof(SitemapWebModule), // 👈 Add sitemap module
    // ... other dependencies
)]
public class YourProjectWebModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        // Configure sitemap options
        Configure(options =>
        {
            options.BaseUrl = "https://yourdomain.com"; // 👈 Your website URL
            options.FolderPath = "Sitemaps"; // 👈 Where XML files are stored
            options.WorkerPeriod = 3600000; // 👈 Regenerate every hour (in milliseconds)
        });
    }
}

Note: In ABP applications, BaseUrl can be resolved from AppUrlOptions to stay consistent with environment configuration.

That's it! The module is now integrated and will automatically:

Discover your Razor Pages
Generate sitemap XML files on application startup
Regenerate sitemaps in the background every hour

Usage Examples

Let's explore practical examples of using the sitemap module. You can see complete working examples in the AbpSitemapDemo repository.

Example 1: Mark Static Pages

The simplest way to include pages in your sitemap is using attributes:

using Abp.Sitemap.Web.Sitemap.Sources.Page.Attributes;

namespace YourProject.Pages;

[IncludeSitemapXml] // 👈 Include in default "Main" group
public class IndexModel : PageModel
{
    public void OnGet()
    {
        // Your page logic
    }
}

[IncludeSitemapXml(Group = "Help")]
public class FaqModel : PageModel
{
    public void OnGet()
    {
        // Your page logic
    }
}

These pages will be automatically discovered and included in the sitemap XML files.

Example 2: Add Dynamic Content from Database

For dynamic content like blog posts, products, or articles, create a custom sitemap source. Here's a complete example using a Book entity:

using Abp.Sitemap.Web.Sitemap.Core;
using Abp.Sitemap.Web.Sitemap.Sources.Group;
using Volo.Abp.DependencyInjection;

namespace YourProject.Sitemaps;

public class BookSitemapSource : GroupedSitemapItemSource, ITransientDependency
{
    public BookSitemapSource(
        IReadOnlyRepository repository,
        IAsyncQueryableExecuter executer)
        : base(repository, executer, group: "Books") // 👈 Creates sitemap-Books.xml
    {
        Filter = x => x.IsPublished; // 👈 Only published books
    }

    protected override Expression> Selector =>
        book => new SitemapItem(
            book.Id.ToString(), // 👈 Unique identifier
            $"/Books/Detail/{book.Id}", // 👈 URL pattern matching your route
            book.LastModificationTime ?? book.CreationTime // 👈 Last modified date
        )
        {
            ChangeFrequency = "weekly",
            Priority = 0.7
        };
}

Key points:

Inherits from GroupedSitemapItemSource
Specifies the entity type (Book)
Defines a group name ("Books") which creates sitemap-Books.xml
Uses Filter to include only published books
Maps entity properties to sitemap URLs using Selector
Automatically registered via ITransientDependency

Example 3: Category-Based Dynamic Content

For content with categories, you can build more complex URL patterns:

using Abp.Sitemap.Web.Sitemap.Core;
using Abp.Sitemap.Web.Sitemap.Sources.Group;

namespace YourProject.Sitemaps;

public class ArticleSitemapSource : GroupedSitemapItemSource, ITransientDependency
{
    public ArticleSitemapSource(
        IReadOnlyRepository repository,
        IAsyncQueryableExecuter executer)
        : base(repository, executer, "Articles")
    {
        // Multiple filter conditions
        Filter = x => x.IsPublished && 
                     !x.IsDeleted && 
                     x.PublishDate <= DateTime.Now;
    }

    protected override Expression> Selector =>
        article => new SitemapItem(
            article.Id.ToString(),
            $"/blog/{article.Category.Slug}/{article.Slug}", // 👈 Category-based URL
            article.LastModificationTime ?? article.CreationTime
        );
}

This example demonstrates:

Multiple filter conditions for complex business logic
Building URLs with category slugs

Testing Your Sitemaps

After configuring the module, test your sitemap generation:

1. Run Your Application

dotnet run

The sitemaps are automatically generated on application startup.

2. Check Generated Files

Navigate to {WebProject}/Sitemaps/ directory (at the root of your web project):

{WebProject}
└── Sitemaps/
    ├── sitemap.xml           # Main group (static pages)
    ├── sitemap-Books.xml     # Books from database
    ├── sitemap-Articles.xml  # Articles from database
    └── sitemap-Help.xml      # Help pages

3. Verify XML Content

Open sitemap-Books.xml and verify the structure:



  
    https://yourdomain.com/Books/Detail/3a071e39-12c9-48d7-8c1e-3b4f5c6d7e8f
    2025-12-13
  
  
    https://yourdomain.com/Books/Detail/7b8c9d0e-1f2a-3b4c-5d6e-7f8g9h0i1j2k
    2025-12-10

4. Test in Browser

Visit the sitemap URLs directly (the module serves them from the root path):

Main sitemap: https://localhost:5001/sitemap.xml
Books sitemap: https://localhost:5001/sitemap-Books.xml

Note: The sitemaps are stored in {WebProject}/Sitemaps/ directory and served directly from the root URL.

Advanced Configuration

Custom Regeneration Schedule

Control when sitemaps are regenerated using cron expressions:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    Configure(options =>
    {
        options.BaseUrl = "https://yourdomain.com";
        options.WorkerCronExpression = "0 0 2 * * ?"; // 👈 Every day at 2 AM
        // Or use period in milliseconds:
        // options.WorkerPeriod = 7200000; // 2 hours
    });
}

Environment-Specific Configuration

Use different settings for development and production:

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

    Configure(options =>
    {
        if (hostingEnvironment.IsDevelopment())
        {
            options.BaseUrl = "https://localhost:5001";
            options.WorkerPeriod = 300000; // 5 minutes for testing
        }
        else
        {
            options.BaseUrl = configuration["App:SelfUrl"]!;
            options.WorkerPeriod = 3600000; // 1 hour in production
        }
        
        options.FolderPath = "Sitemaps";
    });
}

Manual Sitemap Generation

Trigger sitemap generation manually (useful for admin panels):

using Abp.Sitemap.Web.Sitemap.Management;

public class SitemapManagementService : ITransientDependency
{
    private readonly SitemapFileGenerator _generator;

    public SitemapManagementService(SitemapFileGenerator generator)
    {
        _generator = generator;
    }

    [Authorize("Admin")]
    public async Task RegenerateSitemapsAsync()
    {
        await _generator.GenerateAsync(); // 👈 Manual regeneration
    }
}

Real-World Use Cases

Here are practical scenarios where the sitemap module excels:

E-Commerce Platform

// Products grouped by category
public class ProductSitemapSource : GroupedSitemapItemSource
{
    // Automatically includes all active products with stock
}

// Separate sitemap for categories
public class CategorySitemapSource : GroupedSitemapItemSource
{
    // All browsable categories
}

// Brand pages
public class BrandSitemapSource : GroupedSitemapItemSource
{
    // All active brands
}

Result: sitemap-Products.xml, sitemap-Categories.xml, sitemap-Brands.xml

Content Management System

// Blog posts by date
public class BlogPostSitemapSource : GroupedSitemapItemSource
{
    // Filter by published date, priority based on view count
}

// Static CMS pages
[IncludeSitemapXml]
public class AboutUsModel : PageModel { }

Best Practices

1. Group Related Content

Organize your sitemaps logically:

// ✅ Good: Logical grouping
"Products", "Categories", "Brands", "Blog", "Help"

// ❌ Bad: Everything in one group
"Main" // Contains 50,000 mixed URLs

2. Use Filters Wisely

// ✅ Good: Only published, non-deleted content
Filter = x => x.IsPublished && 
             !x.IsDeleted && 
             x.PublishDate <= DateTime.Now

// ❌ Bad: Including draft content
Filter = x => true // Everything included

3. Keep URLs Clean

// ✅ Good: SEO-friendly URLs
$"/products/{product.Slug}"
$"/blog/{year}/{month}/{article.Slug}"

// ❌ Bad: Technical IDs exposed
$"/product-detail?id={product.Id}"

Troubleshooting

Sitemap Not Generated

Problem: No XML files in {WebProject}/Sitemaps/

Solutions:

Check module is added to dependencies
Verify SitemapOptions.BaseUrl is configured
Check application logs for errors
Ensure the web project directory has write permissions

Pages Not Appearing

Problem: Some pages missing from sitemap

Solutions:

Verify [IncludeSitemapXml] attribute is present
Check namespace imports: using Abp.Sitemap.Web.Sitemap.Sources.Page.Attributes;
Ensure PageModel classes are public
Check filter conditions in custom sources

Background Worker Not Running

Problem: Sitemaps not regenerating automatically

Solutions:

Check SitemapOptions.WorkerPeriod is set
Verify background workers are enabled in ABP configuration
Check application logs for worker errors

Performance Considerations

Caching Strategy

Consider adding caching for frequently accessed sitemaps:

public class CachedSitemapFileGenerator : ITransientDependency
{
    private readonly SitemapFileGenerator _generator;
    private readonly IDistributedCache _cache;

    public async Task GetOrGenerateAsync(string group)
    {
        var cacheKey = $"Sitemap:{group}";
        var cached = await _cache.GetStringAsync(cacheKey);
        
        if (cached != null)
            return cached;
        
        await _generator.GenerateAsync();
        // Read and cache...
    }
}

Conclusion

The ABP Sitemap module provides a production-ready solution for dynamic sitemap generation in ABP Framework applications. By leveraging ABP's architecture—dependency injection, repository pattern, and background workers—the module automatically discovers pages, includes dynamic content, and regenerates sitemaps without manual intervention.

Key benefits: ✅ Zero Configuration for basic scenarios ✅ Type-Safe attribute-based configuration ✅ Extensible for complex business logic ✅ Performance optimized with background processing ✅ SEO-Friendly following XML sitemap standards

Whether you're building a blog, e-commerce platform, or enterprise application, this module provides a solid foundation for search engine optimization.

Additional Resources

Documentation

Source Code

Complete Working Demo - Full implementation with examples
- BookSitemapSource - Entity-based source example
- Index.cshtml - Page attribute usage

Implement Automatic Method-Level Caching in ABP Framework

Mon, 08 Dec 2025 07:16:29 Z

Implement Automatic Method-Level Caching in ABP Framework

Caching is one of the most effective ways to improve application performance, but implementing it manually for every method can be tedious and error-prone. What if you could cache method results automatically with just an attribute? In this article, we'll explore how to build an automatic method-level caching system in ABP Framework that handles cache invalidation, supports multiple scopes, and integrates seamlessly with your existing application.

By the end of this guide, you'll understand how to implement attribute-based caching that automatically invalidates when entities change, supports user-specific and global caching scopes, and provides built-in metrics for monitoring cache performance.

💡 Complete Implementation Available: This article is based on a working demo project. You can find the complete implementation in the AbpAutoCacheDemo repository, with the core AutoCache library implementation available in this commit.

What is Automatic Method-Level Caching?

Automatic method-level caching is a technique that intercepts method calls and caches their results without requiring manual cache management code. Instead of writing cache logic in every method, you simply decorate methods with attributes that define caching behavior.

The key benefits include:

Reduced Boilerplate: No repetitive cache management code in your business logic
Consistent Caching Strategy: Centralized cache configuration and behavior
Smart Invalidation: Automatic cache clearing when related entities change
Multiple Scopes: Support for global, user-specific, and entity-specific caching
Built-in Monitoring: Track cache hits, misses, and performance metrics

Architecture Overview

The automatic caching system consists of several key components working together:

Core Components:

CacheAttribute: The attribute you apply to methods to enable automatic caching
AutoCacheInterceptor: Intercepts method calls and handles cache operations
AutoCacheManager: Manages cache storage, retrieval, and key generation
IAutoCacheKeyManager: Handles cache key mapping and invalidation
AutoCacheInvalidationHandler: Listens to entity changes and clears related caches

This architecture leverages ABP's dynamic proxy system and event bus to provide seamless caching without modifying your business logic.

Prerequisites

Before implementing automatic caching, ensure you have:

ABP Framework 10.0 or later

Implementation

📦 Repository Structure: The complete implementation is available in the AbpAutoCacheDemo repository. The AutoCache library is located in the src/AutoCache folder, making it easy to extract and reuse in your own projects.

Step - 1: Create the AutoCache Module

First, let's create a separate module for our caching infrastructure. This makes it reusable across projects.

Step - 1: Create the AutoCache Module

First, let's create a separate module for our caching infrastructure. This makes it reusable across projects.

Create AutoCache.csproj:


    
        net10.0
        enable

Create the module class AutoCacheModule.cs:

using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.Caching.StackExchangeRedis;
using Volo.Abp.Domain;
using Volo.Abp.Modularity;

namespace AutoCache;

[DependsOn(typeof(AbpDddDomainModule), typeof(AbpCachingStackExchangeRedisModule))]
public class AutoCacheModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.OnRegistered(AutoCacheRegister.RegisterInterceptorIfNeeded); // 👈 Register interceptor
    }
}

This module automatically registers the cache interceptor for any class that uses the CacheAttribute.

Step - 2: Define the Cache Attribute

The CacheAttribute is the core of our automatic caching system. It specifies which entities affect the cache and what scope to use.

Create CacheAttribute.cs:

using System;
using Volo.Abp.Domain.Entities;

namespace AutoCache;

[AttributeUsage(AttributeTargets.Method)]
public class CacheAttribute : Attribute
{
    /// 
    /// Entity types that affect this cache. When these entities change, the cache will be invalidated.
    /// 
    public Type[] InvalidateOnEntities { get; set; }

    /// 
    /// Scope of the cache (Global, CurrentUser, AuthenticatedUser, or Entity)
    /// 
    public AutoCacheScope Scope { get; set; } = AutoCacheScope.Global;

    /// 
    /// Absolute expiration time relative to now in milliseconds (0 = use default, -1 = disabled)
    /// 
    public long AbsoluteExpirationRelativeToNow { get; set; }

    /// 
    /// Sliding expiration time in milliseconds (0 = use default, -1 = disabled)
    /// 
    public long SlidingExpiration { get; set; }

    public bool ConsiderUow { get; set; }

    public string AdditionalCacheKey { get; set; }

    public CacheAttribute(params Type[] invalidateOnEntities) // 👈 Specify entities that trigger cache invalidation
    {
        foreach (var entityType in invalidateOnEntities)
        {
            ArgumentNullException.ThrowIfNull(entityType);
            if (!typeof(IEntity).IsAssignableFrom(entityType))
            {
                throw new ArgumentException($"Type {entityType.FullName} must implement IEntity interface.");
            }
        }
        InvalidateOnEntities = invalidateOnEntities;
    }
}

Key Properties:

InvalidateOnEntities: Array of entity types that, when modified, will clear this cache
Scope: Determines cache visibility (Global, CurrentUser, AuthenticatedUser, Entity)
AbsoluteExpirationRelativeToNow / SlidingExpiration: Control cache lifetime

Step - 3: Define Cache Scopes

Cache scopes determine how cache entries are partitioned. Create AutoCacheScope.cs:

using System;

namespace AutoCache;

[Flags]
public enum AutoCacheScope
{
    /// 
    /// Cache is shared globally across all users
    /// 
    Global,

    /// 
    /// Cache is scoped to the current user (based on user ID)
    /// 
    CurrentUser,

    /// 
    /// Cache is scoped to authenticated vs unauthenticated users
    /// 
    AuthenticatedUser,

    /// 
    /// Cache is scoped to the primary key of the entity involved
    /// 
    Entity
}

When to Use Each Scope:

Global: For data that's the same for all users (e.g., configuration, public lists)
CurrentUser: For user-specific data (e.g., user profile, user's orders)
AuthenticatedUser: For data that differs between authenticated and anonymous users
Entity: For data tied to a specific entity instance (e.g., book details by ID)

Step - 4: Implement the Cache Interceptor

The interceptor is the heart of automatic caching. It intercepts method calls, checks the cache, and stores results. Create AutoCacheInterceptor.cs:

using System;
using System.Collections.Concurrent;
using System.Linq;
using System.Reflection;
using System.Threading.Tasks;
using Microsoft.Extensions.Caching.Distributed;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using Volo.Abp.DependencyInjection;
using Volo.Abp.DynamicProxy;

namespace AutoCache;

public class AutoCacheInterceptor : AbpInterceptor, ITransientDependency
{
    private readonly ILogger _logger;
    private readonly AutoCacheOptions _options;
    private static readonly MethodInfo GetOrAddCacheAsyncMethod;
    private readonly AutoCacheManager _autoCacheManager;
    private static readonly ConcurrentDictionary MethodCache = new();

    static AutoCacheInterceptor()
    {
        GetOrAddCacheAsyncMethod = typeof(AutoCacheInterceptor).GetMethod(
            nameof(GetOrAddCacheAsync),
            BindingFlags.NonPublic | BindingFlags.Instance
        )!;
    }

    public AutoCacheInterceptor(
        ILogger logger,
        IOptions options, 
        AutoCacheManager autoCacheManager)
    {
        _logger = logger;
        _autoCacheManager = autoCacheManager;
        _options = options.Value;
    }

    public override async Task InterceptAsync(IAbpMethodInvocation invocation)
    {
        // Check if caching is enabled and method has [Cache] attribute
        if(!_options.Enabled || 
           invocation.Method.GetCustomAttributes(typeof(CacheAttribute), true).FirstOrDefault() 
           is not CacheAttribute attribute)
        {
            await invocation.ProceedAsync(); // 👈 No caching, proceed normally
            return;
        }
        
        var proceeded = false;

        try
        {
            // Create generic method based on return type
            var genericMethod = MethodCache.GetOrAdd(invocation.Method.ReturnType, t =>
            {
                var isGenericTask = t.IsGenericType && t.GetGenericTypeDefinition() == typeof(Task<>);
                var resultType = isGenericTask ? t.GetGenericArguments()[0] : t;
                return GetOrAddCacheAsyncMethod.MakeGenericMethod(resultType);
            });
            
            // Execute cache logic
            (var result, proceeded) = await (Task<(object, bool)>)genericMethod.Invoke(this, [invocation, attribute])!;
            invocation.ReturnValue = result; // 👈 Set cached or fresh result
        }
        catch (Exception e)
        {
            _logger.LogError(e, "Error occurred while caching method {MethodName}", invocation.Method.Name);
            
            if(e is AutoCacheExceptionWrapper exceptionWrapper)
            {
                if (_options.ThrowOnError)
                {
                    throw exceptionWrapper.OriginalException;
                }
                
                _logger.LogWarning(
                    "Cache operation failed, falling back to method execution for {MethodName}",
                    invocation.Method.Name
                );
            }

            if (!proceeded && invocation.ReturnValue == null)
            {
                await invocation.ProceedAsync(); // 👈 Fallback to actual method execution
            }
        }
    }

    private async Task<(object?, bool)> GetOrAddCacheAsync(
        IAbpMethodInvocation invocation, 
        CacheAttribute attribute)
    {
        var proceeded = false;
        var result = await _autoCacheManager.GetOrAddAsync(
            invocation.TargetObject, 
            Factory, 
            invocation.Arguments, 
            () => new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = GetExpiration(
                    attribute.AbsoluteExpirationRelativeToNow, 
                    _options.DefaultAbsoluteExpirationRelativeToNow),
                SlidingExpiration = GetExpiration(
                    attribute.SlidingExpiration, 
                    _options.DefaultSlidingExpiration)
            }, 
            attribute.InvalidateOnEntities, 
            attribute.Scope, 
            attribute.ConsiderUow, 
            attribute.AdditionalCacheKey, 
            invocation.Method.Name);
        
        return (result, proceeded);

        async Task Factory()
        {
            await invocation.ProceedAsync(); // 👈 Execute actual method on cache miss
            proceeded = true;
            return (TResult)invocation.ReturnValue;
        }
    }
    
    private static TimeSpan? GetExpiration(long milliseconds, long defaultValue)
    {
        return milliseconds switch
        {
            0 => defaultValue > 0 ? TimeSpan.FromMilliseconds(defaultValue) : null,
            < 0 => null,
            _ => TimeSpan.FromMilliseconds(milliseconds)
        };
    }
}

The interceptor intelligently determines whether to serve cached data or execute the actual method.

Step - 5: Implement the Cache Manager

The AutoCacheManager handles the actual cache operations. Create a simplified version:

using System;
using System.Runtime.CompilerServices;
using System.Threading.Tasks;
using Microsoft.Extensions.Caching.Distributed;
using Microsoft.Extensions.Logging;
using Volo.Abp.DependencyInjection;
using Volo.Abp.DynamicProxy;
using Volo.Abp.Users;

namespace AutoCache;

public class AutoCacheManager : IScopedDependency
{
    private readonly IAutoCacheKeyManager _autoCacheKeyManager;
    private readonly ICurrentUser _currentUser;
    private readonly ILogger _logger;
    private readonly IAutoCacheMetrics _metrics;
    private readonly AutoCacheOptions _options;

    public AutoCacheManager(
        IAutoCacheKeyManager autoCacheKeyManager, 
        ICurrentUser currentUser,
        ILogger logger,
        IAutoCacheMetrics metrics,
        IOptions options)
    {
        _autoCacheKeyManager = autoCacheKeyManager;
        _currentUser = currentUser;
        _logger = logger;
        _metrics = metrics;
        _options = options.Value;
    }

    public async Task GetOrAddAsync(
        object? caller,
        Func> func,
        object?[]? parameters = null,
        Func? optionsFactory = null,
        Type[]? invalidateOnEntities = null,
        AutoCacheScope scope = AutoCacheScope.Global,
        bool considerUow = false,
        string? additionalCacheKey = null,
        [CallerMemberName] string methodName = "")
    {
        if (!_options.Enabled)
        {
            return await func(); // 👈 Caching disabled, execute directly
        }
        
        var callerType = caller != null ? ProxyHelper.GetUnProxiedType(caller) : GetType();
        parameters ??= [];
        
        // Generate unique cache key based on method, parameters, and scope
        var cacheKey = GenerateCacheKey(
            callerType.Name, 
            additionalCacheKey, 
            methodName, 
            parameters, 
            scope);
        
        var (cachedResult, exception, wasHit) = await GetOrAddCacheAsync(
            cacheKey,
            func,
            optionsFactory,
            considerUow
        );
        
        // Record metrics
        if (wasHit)
        {
            _metrics.RecordHit(cacheKey);
        }
        else
        {
            _metrics.RecordMiss(cacheKey);
        }
        
        if (exception != null)
        {
            _metrics.RecordError(cacheKey, exception);
            
            if (_options.ThrowOnError)
            {
                throw exception;
            }
        }
        
        return cachedResult;
    }

    private string GenerateCacheKey(
        string callerTypeName,
        string? additionalCacheKey,
        string methodName,
        object?[] parameters,
        AutoCacheScope scope)
    {
        var keyBuilder = new StringBuilder();
        keyBuilder.Append($"{callerTypeName}:{methodName}");
        
        // Add parameters to key
        foreach (var param in parameters)
        {
            keyBuilder.Append($":{param}");
        }
        
        // Add scope-specific segments
        if (scope.HasFlag(AutoCacheScope.CurrentUser) && _currentUser.Id.HasValue)
        {
            keyBuilder.Append($":user:{_currentUser.Id}"); // 👈 User-specific cache key
        }
        
        if (scope.HasFlag(AutoCacheScope.AuthenticatedUser))
        {
            keyBuilder.Append($":auth:{_currentUser.IsAuthenticated}");
        }
        
        if (!string.IsNullOrEmpty(additionalCacheKey))
        {
            keyBuilder.Append($":{additionalCacheKey}");
        }
        
        return keyBuilder.ToString();
    }

    // Additional methods for cache retrieval and storage...
}

The manager generates unique cache keys based on method signatures, parameters, and scope settings.

Step - 6: Implement Cache Invalidation

When entities change, related caches must be cleared. Create AutoCacheInvalidationHandler.cs:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Volo.Abp.Domain.Entities;
using Volo.Abp.Domain.Entities.Events;
using Volo.Abp.EventBus;
using Volo.Abp.Uow;

namespace AutoCache;

public class AutoCacheInvalidationHandler : 
    ILocalEventHandler> 
    where TEntity : class, IEntity
{
    private readonly IAutoCacheKeyManager _autoCacheKeyManager;
    private readonly ILogger> _logger;
    private readonly IUnitOfWorkManager _unitOfWorkManager;
    
    public AutoCacheInvalidationHandler(
        IAutoCacheKeyManager autoCacheKeyManager, 
        ILogger> logger,
        IUnitOfWorkManager unitOfWorkManager)
    {
        _autoCacheKeyManager = autoCacheKeyManager;
        _logger = logger;
        _unitOfWorkManager = unitOfWorkManager;
    }

    public async Task HandleEventAsync(EntityChangedEventData eventData)
    {
        try
        {
            var entityType = typeof(TEntity);
            var context = new RemoveCacheKeyContext 
            { 
                Keys = eventData.Entity.GetKeys()! 
            };
            
            // Clear cache after unit of work completes
            if(_unitOfWorkManager.Current != null)
            {
                _unitOfWorkManager.Current.OnCompleted(async () =>
                {
                    await _autoCacheKeyManager.RemoveCacheAndCacheKeys(entityType, context); // 👈 Invalidate cache
                });
            }
            else
            {
                await _autoCacheKeyManager.RemoveCacheAndCacheKeys(entityType, context);
            }
        }
        catch (Exception e)
        {
            _logger.LogError(
                e, 
                "Error occurred while clearing cache for entity type {EntityType}", 
                typeof(TEntity).FullName
            );
        }
    }
}

This handler listens to entity change events and automatically clears related caches. The invalidation happens after the unit of work completes to ensure data consistency.

Step - 7: Configure AutoCache in Your Application

Add the AutoCacheModule to your application module dependencies:

[DependsOn(
    typeof(AutoCacheModule), // 👈 Add AutoCache module
    typeof(AbpCachingStackExchangeRedisModule),
    // ... other modules
)]
public class YourApplicationModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure(options =>
        {
            options.Enabled = true; // 👈 Enable caching
            options.DefaultAbsoluteExpirationRelativeToNow = 3600000; // 1 hour
            options.DefaultSlidingExpiration = 600000; // 10 minutes
            options.ThrowOnError = false; // Fallback to method execution on cache errors
        });
        
        // Configure Redis (if using distributed cache)
        Configure(options =>
        {
            options.KeyPrefix = "YourApp:";
        });
    }
}

Step - 8: Use Automatic Caching in Application Services

Now comes the easy part - using automatic caching! Simply add the [Cache] attribute to your methods:

using AutoCache;

[Authorize(AutoCacheDemoPermissions.Books.Default)]
public class BookAppService : ApplicationService, IBookAppService
{
    private readonly IRepository _repository;
    private readonly AutoCacheManager _autoCacheManager;

    public BookAppService(IRepository repository, AutoCacheManager autoCacheManager)
    {
        _repository = repository;
        _autoCacheManager = autoCacheManager;
    }

    // Cache this method, invalidate when Book entity changes
    [Cache(typeof(Book), Scope = AutoCacheScope.Global)]
    public virtual async Task GetAsync(Guid id)
    {
        // You can also use AutoCacheManager directly for nested caching
        var book = await _autoCacheManager.GetOrAddAsync(
            this, 
            async () => await _repository.GetAsync(id), 
            [id], // 👈 Method parameters
            invalidateOnEntities: [typeof(Book)], 
            scope: AutoCacheScope.Entity);
            
        return ObjectMapper.Map(book!);
    }

    // Cache book list, invalidate when any Book changes
    [Cache(typeof(Book))]
    public virtual async Task> GetListAsync(PagedAndSortedResultRequestDto input)
    {
        var queryable = await _repository.GetQueryableAsync();
        var query = queryable
            .OrderBy(input.Sorting.IsNullOrWhiteSpace() ? "Name" : input.Sorting)
            .Skip(input.SkipCount)
            .Take(input.MaxResultCount);

        var books = await AsyncExecuter.ToListAsync(query);
        var totalCount = await AsyncExecuter.CountAsync(queryable);

        return new PagedResultDto(
            totalCount,
            ObjectMapper.Map, List>(books)
        );
    }

    // No caching on write operations
    [Authorize(AutoCacheDemoPermissions.Books.Create)]
    public async Task CreateAsync(CreateUpdateBookDto input)
    {
        var book = ObjectMapper.Map(input);
        await _repository.InsertAsync(book); // 👈 This will trigger cache invalidation
        return ObjectMapper.Map(book);
    }
}

What Happens Here:

When GetAsync is called, the interceptor checks the cache
On cache miss, the actual method executes and the result is cached
When CreateAsync inserts a Book, the invalidation handler clears all caches related to Book
Next call to GetAsync will fetch fresh data

Advanced Features

User-Specific Caching

For user-specific data, use AutoCacheScope.CurrentUser:

[Cache(typeof(Order), Scope = AutoCacheScope.CurrentUser)]
public virtual async Task> GetMyOrdersAsync()
{
    var orders = await _orderRepository.GetListAsync(x => x.UserId == CurrentUser.Id);
    return ObjectMapper.Map, List>(orders);
}

Each user gets their own cache entry, automatically invalidated when their orders change.

Custom Cache Keys

For fine-grained control, add custom cache key segments:

[Cache(
    typeof(Product), 
    Scope = AutoCacheScope.Global,
    AdditionalCacheKey = "featured"
)]
public virtual async Task> GetFeaturedProductsAsync()
{
    // Only featured products are cached separately
    return await GetProductsByCategoryAsync("Featured");
}

Performance Metrics

Monitor cache performance using IAutoCacheMetrics:

public class CacheMonitoringService : ITransientDependency
{
    private readonly IAutoCacheMetrics _metrics;

    public CacheMonitoringService(IAutoCacheMetrics metrics)
    {
        _metrics = metrics;
    }

    public AutoCacheStatistics GetStatistics()
    {
        return _metrics.GetStatistics(); // 👈 Get hit rate, miss count, error count
    }
}

Testing the Application

1. Run the Application

abp new BookStore -u mvc -d ef
cd BookStore
dotnet run --project src/BookStore.Web

2. Test Cache Behavior

Create a simple test to verify caching:

[Fact]
public async Task Should_Cache_Book_Results()
{
    // First call - cache miss
    var book1 = await _bookAppService.GetAsync(testBookId);
    
    // Second call - cache hit (should be faster)
    var book2 = await _bookAppService.GetAsync(testBookId);
    
    book1.Name.ShouldBe(book2.Name);
}

[Fact]
public async Task Should_Invalidate_Cache_On_Update()
{
    // Cache the book
    var book1 = await _bookAppService.GetAsync(testBookId);
    
    // Update the book
    await _bookAppService.UpdateAsync(testBookId, new CreateUpdateBookDto 
    { 
        Name = "Updated Name" 
    });
    
    // Fetch again - should get updated data (cache was invalidated)
    var book2 = await _bookAppService.GetAsync(testBookId);
    
    book2.Name.ShouldBe("Updated Name");
}

3. Monitor Cache Performance

Check your application logs for cache metrics:

[INF] Cache Hit: BookAppService:GetAsync:book-id-123 (Response Time: 5ms)
[INF] Cache Miss: BookAppService:GetListAsync (Response Time: 156ms)
[INF] Cache Invalidation: Book entity changed, cleared 3 cache entries

Key Takeaways

✅ Automatic caching reduces boilerplate code - Just add [Cache] attribute to methods instead of manual cache management

✅ Smart invalidation keeps data fresh - Entity changes automatically clear related caches without manual intervention

✅ Multiple scoping options - Support for global, user-specific, authenticated, and entity-level caching strategies

✅ Built-in fallback handling - Gracefully falls back to method execution if caching fails

✅ Performance monitoring - Track cache hits, misses, and errors for optimization

Conclusion

Automatic method-level caching dramatically simplifies performance optimization in ABP Framework applications. By using attributes and interceptors, you can add sophisticated caching behavior without cluttering your business logic with cache management code.

The system we've built provides intelligent cache invalidation, multiple scoping strategies, and built-in monitoring - all while maintaining clean, readable code. Whether you're building a small application or an enterprise system, this approach scales elegantly and integrates seamlessly with ABP's architecture.

Ready to implement this in your project? The complete working implementation is available in the AbpAutoCacheDemo repository. You can clone the repository, explore the code, and even extract the src/AutoCache folder to use it as a standalone library in your own ABP applications. The main implementation commit shows all the components working together, including interceptor registration, cache key management, and automatic invalidation handlers.r you're building a small application or an enterprise system, this approach scales elegantly and integrates seamlessly with ABP's architecture.

Ready to implement this in your project? Check out the complete working example in the repository linked below, and start improving your application's performance today!

References

Building Production-Ready LLM Applications with .NET: A Practical Guide

Mon, 24 Nov 2025 07:33:03 Z

Building Production-Ready LLM Applications with .NET: A Practical Guide

Large Language Models (LLMs) have evolved rapidly, and integrating them into production .NET applications requires staying current with the latest approaches. In this article, I'll share practical tips and patterns I've learned while building LLM-powered systems, covering everything from API changes in GPT-5 to implementing efficient RAG (Retrieval Augmented Generation) architectures.

Whether you're building a chatbot, a knowledge base assistant, or integrating AI into your enterprise applications, these production-tested insights will help you avoid common pitfalls and build more reliable systems.

The Temperature Paradigm Shift: GPT-5 Changes Everything

If you've been working with GPT-4 or earlier models, you're familiar with the temperature and top_p parameters for controlling response randomness. Here's the critical update: GPT-5 no longer supports these parameters!

The Old Way (GPT-4)

var chatRequest = new ChatOptions
{
    Temperature = 0.7,  // ✅ Worked with GPT-4
    TopP = 0.9          // ✅ Worked with GPT-4
};

The New Way (GPT-5)

var chatRequest = new ChatOptions
{
    RawRepresentationFactory = (client => new ChatCompletionOptions()
    {
#pragma warning disable OPENAI001
        ReasoningEffortLevel = "minimal",
#pragma warning restore OPENAI001
    })
};

Why the change? GPT-5 incorporates an internal reasoning and verification process. Instead of controlling randomness, you now specify how much computational effort the model should invest in reasoning through the problem.

Choosing the Right Reasoning Level

Low: Quick responses for simple queries (e.g., "What's the capital of France?")
Medium: Balanced approach for most use cases
High: Complex reasoning tasks (e.g., code generation, multi-step problem solving)

Pro Tip: Reasoning tokens are included in your API costs. Use "High" only when necessary to optimize your budget.

System Prompts: The "Lost in the Middle" Problem

Here's a critical insight that can save you hours of debugging: Important rules must be repeated at the END of your prompt!

❌ What Doesn't Work

You are a helpful assistant.
RULE: Never share passwords or sensitive information.

[User Input]

✅ What Actually Works

You are a helpful assistant.
RULE: Never share passwords or sensitive information.

[User Input]

⚠️ REMINDER: Apply the rules above strictly, ESPECIALLY regarding passwords.

Why? LLMs suffer from the "Lost in the Middle" phenomenon—they pay more attention to the beginning and end of the context window. Critical instructions buried in the middle are often ignored.

RAG Architecture: The Parent-Child Pattern

Retrieval Augmented Generation (RAG) is essential for grounding LLM responses in your own data. The most effective pattern I've found is the Parent-Child approach.

How It Works

Split documents into hierarchies:
- Parent chunks: Large sections (1000-2000 tokens) for context
- Child chunks: Small segments (200-500 tokens) for precise retrieval
Store both in vector database with references
Query flow:
- Search using child chunks (higher precision)
- Return parent chunks to LLM (richer context)

The Overlap Strategy

Always use overlapping chunks to prevent information loss at boundaries!

Chunk 1: Token 0-500
Chunk 2: Token 400-900   ← 100 token overlap
Chunk 3: Token 800-1300  ← 100 token overlap

Standard recommendation: 10-20% overlap (for 500 tokens, use 50-100 token overlap)

Implementation with Semantic Kernel

using Microsoft.SemanticKernel.Text;

var chunks = TextChunker.SplitPlainTextParagraphs(
    documentText, 
    maxTokensPerParagraph: 500,
    overlapTokens: 50
);

foreach (var chunk in chunks)
{
    var embedding = await embeddingService.GenerateEmbeddingAsync(chunk);
    await vectorDb.StoreAsync(chunk, embedding);
}

PostgreSQL + pgvector: The Pragmatic Choice

For .NET developers, choosing a vector database can be overwhelming. After evaluating multiple options, PostgreSQL with pgvector is the most practical choice for most scenarios.

Why pgvector?

✅ Use existing SQL knowledge - No new query language to learn
✅ EF Core integration - Works with your existing data access layer
✅ JOIN with metadata - Combine vector search with traditional queries
✅ WHERE clause filtering - Filter by tenant, user, date, etc.
✅ ACID compliance - Transaction support for data consistency
✅ No separate infrastructure - One database for everything

Setting Up pgvector with EF Core

First, install the NuGet package:

dotnet add package Pgvector.EntityFrameworkCore

Define your entity:

using Pgvector;
using Pgvector.EntityFrameworkCore;

public class DocumentChunk
{
    public Guid Id { get; set; }
    public string Content { get; set; }
    public Vector Embedding { get; set; }  // 👈 pgvector type
    public Guid ParentChunkId { get; set; }
    public DateTime CreatedAt { get; set; }
}

Configure in DbContext:

protected override void OnModelCreating(ModelBuilder builder)
{
    builder.HasPostgresExtension("vector");
    
    builder.Entity()
        .Property(e => e.Embedding)
        .HasColumnType("vector(1536)");  // 👈 OpenAI embedding dimension
    
    builder.Entity()
        .HasIndex(e => e.Embedding)
        .HasMethod("hnsw")  // 👈 Fast approximate search
        .HasOperators("vector_cosine_ops");
}

Performing Vector Search

using Pgvector.EntityFrameworkCore;

public async Task> SearchAsync(string query)
{
    // 1. Convert query to embedding
    var queryVector = await _embeddingService.GetEmbeddingAsync(query);
    
    // 2. Search
    return await _context.DocumentChunks
        .OrderBy(c => c.Embedding.L2Distance(queryVector))  // 👈 Lower is better
        .Take(5)
        .ToListAsync();
}

Source: Pgvector.NET on GitHub

Smart Tool Usage: Make RAG a Tool, Not a Tax

A common mistake is calling RAG on every single user message. This wastes tokens and money. Instead, make RAG a tool and let the LLM decide when to use it.

❌ Expensive Approach

// Always call RAG, even for "Hello"
var context = await PerformRAG(userMessage);
var response = await chatClient.CompleteAsync($"{context}\n\n{userMessage}");

✅ Smart Approach

[KernelFunction]
[Description("Search the company knowledge base for information")]
public async Task SearchKnowledgeBase(
    [Description("The search query")] string query)
{
    var results = await _vectorDb.SearchAsync(query);
    return string.Join("\n---\n", results.Select(r => r.Content));
}

The LLM will call SearchKnowledgeBase only when needed:

"Hello" → No tool call
"What was our 2024 revenue?" → Calls tool
"Tell me a joke" → No tool call

Multilingual RAG: Query Translation Strategy

When your documents are in one language (e.g., English) but users query in another (e.g., Turkish), you need a translation strategy.

Solution Options

Option 1: Use an LLM that automatically calls tools in English

Many modern LLMs can do this if properly instructed

Option 2: Tool chain approach

[KernelFunction]
[Description("Translate text to English")]
public async Task TranslateToEnglish(string text)
{
    // Translation logic
}

[KernelFunction]
[Description("Search knowledge base (English only)")]
public async Task SearchKnowledgeBase(string englishQuery)
{
    // Search logic
}

The LLM will:

Call TranslateToEnglish("2024 geliri nedir?")
Get "What was 2024 revenue?"
Call SearchKnowledgeBase("What was 2024 revenue?")
Return results and respond in Turkish

Model Context Protocol (MCP): Beyond In-Process Tools

Microsoft and Anthropic recently released official C# SDKs for the Model Context Protocol (MCP). This is a game-changer for tool reusability.

MCP vs. Semantic Kernel Plugins

| Feature | SK Plugins | MCP Servers | |---------|-----------|-------------| | Process | In-process | Out-of-process (stdio/http) | | Reusability | Application-specific | Cross-application | | Examples | Used within your app | VS Code Copilot, Claude Desktop |

Creating an MCP Server

using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Extensions.Hosting;

var builder = Host.CreateEmptyApplicationBuilder(settings: null);

builder.Services.AddMcpServer()
.WithStdioServerTransport()
.WithToolsFromAssembly();

await builder.Build().RunAsync();

Define your tools:

[McpServerToolType]
public static class FileSystemTools
{
    [McpServerTool, Description("Read a file from the file system")]
    public static async Task ReadFile(string path)
    {
        // ⚠️ SECURITY: Always validate paths!
        if (!IsPathSafe(path)) 
            throw new SecurityException("Invalid path");
        
        return await File.ReadAllTextAsync(path);
    }
    
    private static bool IsPathSafe(string path)
    {
        // Implement path traversal prevention
        var fullPath = Path.GetFullPath(path);
        return fullPath.StartsWith(AllowedDirectory);
    }
}

Your MCP server can now be used by VS Code Copilot, Claude Desktop, or any other MCP client!

Chat History Management: Truncation + RAG Hybrid

For long conversations, storing all history in the context window becomes impractical. Here's the pattern that works:

❌ Lossy Approach

First 50 messages → Summarize with LLM → Single summary message

Problem: Detail loss (fidelity loss)

✅ Hybrid Approach

Recent messages (last 5-10): Keep in prompt for immediate context
Older messages: Store in vector database as a tool

[KernelFunction]
[Description("Search conversation history for past discussions")]
public async Task SearchChatHistory(
    [Description("What to search for")] string query)
{
    var relevantMessages = await _vectorDb.SearchAsync(query);
    return string.Join("\n", relevantMessages.Select(m => 
        $"[{m.Timestamp}] {m.Role}: {m.Content}"));
}

The LLM retrieves only relevant past context when needed, avoiding summary-induced information loss.

RAG vs. Fine-Tuning: Choose Wisely

A common misconception is using fine-tuning for knowledge injection. Here's when to use each:

| Purpose | RAG | Fine-Tuning | |---------|-----|-------------| | Goal | Memory (provide facts) | Behavior (teach style) | | Updates | Dynamic (add docs anytime) | Static (requires retraining) | | Cost | Low dev, higher inference | High dev, lower inference | | Hallucination | Reduces | Doesn't reduce | | Use Case | Company docs, FAQs | Brand voice, specific format |

Common mistake: "Let's fine-tune on our company documents" ❌
Better approach: Use RAG! ✅

Fine-tuning is for teaching the model how to respond, not what to know.

Source: Oracle - RAG vs Fine-Tuning

Bonus: Why SVG is Superior for LLM-Generated Images

When using LLMs to generate diagrams and visualizations, always request SVG format instead of PNG or JPG.

Why SVG?

✅ Text-based → LLMs produce better results
✅ Lower cost → Fewer tokens than base64-encoded images
✅ Editable → Easy to modify after generation
✅ Scalable → Perfect quality at any size
✅ Version control friendly → Works great in Git

Example Prompt

Create an architecture diagram showing PostgreSQL with pgvector integration.
Format: SVG, 800x400 pixels. Show: .NET Application → EF Core → PostgreSQL → Vector Search.
Use arrows to connect stages. Color scheme: Blue tones.

All diagrams in this article were generated as SVG, resulting in excellent quality and lower token costs!

Pro Tip: If you don't need photographs or complex renders, always choose SVG.

Architecture Roadmap: Putting It All Together

Here's the recommended stack for building production LLM applications with .NET:

Orchestration: Microsoft.Extensions.AI + Semantic Kernel (when needed)
Vector Database: PostgreSQL + Pgvector.EntityFrameworkCore
RAG Pattern: Parent-Child chunks with 10-20% overlap
Tools: MCP servers for reusability
Reasoning: ReasoningEffortLevel instead of temperature
Prompting: Critical rules at the end
Cost Optimization: Make RAG a tool, not automatic

Key Takeaways

Let me summarize the most important production tips:

Temperature is gone → Use ReasoningEffortLevel with GPT-5
Rules at the end → Combat "Lost in the Middle"
RAG as a tool → Reduce costs significantly
Parent-Child pattern → Search small, respond with large
Always use overlap → 10-20% is the standard
pgvector for most cases → Unless you have billions of vectors
MCP for reusability → One codebase, works everywhere
SVG for diagrams → Better results, lower cost
Hybrid chat history → Recent in prompt, old in vector DB
RAG > Fine-tuning → For knowledge, not behavior

Happy coding! 🚀

Building an API Key Management System with ABP Framework

Mon, 17 Nov 2025 10:45:38 Z

Building an API Key Management System with ABP Framework

API keys are one of the most common authentication methods for APIs, especially for machine-to-machine communication. In this article, I'll explain what API key authentication is, when to use it, and how to implement a complete API key management system using ABP Framework.

What is API Key Authentication?

An API key is a unique identifier used to authenticate requests to an API. Unlike user credentials (username/password) or OAuth tokens, API keys are designed for:

Programmatic access - Scripts, CLI tools, and automated processes
Service-to-service communication - Microservices authenticating with each other
Third-party integrations - External systems accessing your API
IoT devices - Embedded systems with limited authentication capabilities
Mobile/Desktop apps - Native applications that need persistent authentication

Why Use API Keys?

While modern authentication methods like OAuth2 and JWT are excellent for user authentication, API keys offer distinct advantages in certain scenarios:

Simplicity: No complex OAuth flows or token refresh mechanisms. Just include the key in your request header.

Long-lived: Unlike JWT tokens that expire in minutes/hours, API keys can remain valid for months or years, making them ideal for automated systems.

Revocable: You can instantly revoke a compromised key without affecting user credentials.

Granular Control: Different keys for different purposes (read-only, admin, specific services).

Real-World Use Cases

Here are some practical scenarios where API key authentication shines:

1. Mobile Applications

Your mobile app needs to call your backend APIs. Instead of storing user credentials or managing token refresh flows, use an API key.

// Mobile app configuration
var apiClient = new ApiClient("https://api.yourapp.com");
apiClient.SetApiKey("sk_mobile_prod_abc123...");

2. Microservice Communication

Service A needs to call Service B's protected endpoints.

// Order Service calling Inventory Service
var request = new HttpRequestMessage(HttpMethod.Get, "https://inventory-service/api/products");
request.Headers.Add("X-Api-Key", _configuration["InventoryService:ApiKey"]);

3. Third-Party Integrations

You're providing APIs to external partners or customers.

# Customer's integration script
curl -H "X-Api-Key: pk_partner_xyz789..." \
     https://api.yourplatform.com/api/orders

Implementing API Key Management in ABP Framework

Now let's see how to build a complete API key management system using ABP Framework. I've created an open-source implementation that you can use in your projects.

Project Overview

The implementation consists of:

User-based API keys - Each key belongs to a specific user
Permission delegation - Keys inherit user permissions with optional restrictions
Secure storage - Keys are hashed with SHA-256
Prefix-based lookup - Fast key resolution with caching
Web UI - Manage keys through a user-friendly interface
Multi-tenancy support - Full ABP multi-tenancy compatibility

Architecture Overview

The solution follows ABP's modular architecture with four main layers:

┌─────────────────────────────────────────────┐
│           Web Layer (UI)                    │
│  • Razor Pages for CRUD operations          │
│  • JavaScript for client interactions       │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│       AspNetCore Layer (Middleware)         │
│  • Authentication Handler                   │
│  • API Key Resolver (Header/Query)          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│     Application Layer (Business Logic)      │
│  • ApiKeyAppService (CRUD operations)       │
│  • DTO mappings and validations             │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│        Domain Layer (Core Business)         │
│  • ApiKey Entity & Manager                  │
│  • IApiKeyRepository                        │
│  • Domain services & events                 │
└─────────────────────────────────────────────┘

Key Components

1. Domain Layer - The Core Entity

public class ApiKey : FullAuditedAggregateRoot, IMultiTenant
{
    public virtual Guid? TenantId { get; protected set; }
    public virtual Guid UserId { get; protected set; }
    public virtual string Name { get; protected set; }
    public virtual string Prefix { get; protected set; }
    public virtual string KeyHash { get; protected set; }
    public virtual DateTime? ExpiresAt { get; protected set; }
    public virtual bool IsActive { get; protected set; }
    
    // Key format: {prefix}_{key}
    // Only the hash is stored, never the actual key
}

Key Design Decisions:

Prefix-based lookup: Keys have format prefix_actualkey. The prefix is indexed for fast database lookups.
SHA-256 hashing: The actual key is hashed and never stored in plain text.
User association: Each key belongs to a user, inheriting their permissions.
Soft delete: Deleted keys are marked as deleted but not removed from database for audit purposes.

2. Authentication Flow

Here's how authentication works when a request arrives:

// 1. Extract API key from request
var apiKey = httpContext.Request.Headers["X-Api-Key"].FirstOrDefault();
if (string.IsNullOrEmpty(apiKey)) return AuthenticateResult.NoResult();

// 2. Split prefix and key
var parts = apiKey.Split('_', 2);
var prefix = parts[0];
var key = parts[1];

// 3. Find key by prefix (cached)
var apiKeyEntity = await _apiKeyRepository.FindByPrefixAsync(prefix);
if (apiKeyEntity == null) return AuthenticateResult.Fail("Invalid API key");

// 4. Verify hash
var keyHash = HashHelper.ComputeSha256(key);
if (apiKeyEntity.KeyHash != keyHash) 
    return AuthenticateResult.Fail("Invalid API key");

// 5. Check expiration and active status
if (apiKeyEntity.ExpiresAt < DateTime.UtcNow || !apiKeyEntity.IsActive)
    return AuthenticateResult.Fail("API key expired or inactive");

// 6. Create claims principal with user identity
var claims = new List
{
    new Claim(AbpClaimTypes.UserId, apiKeyEntity.UserId.ToString()),
    new Claim(AbpClaimTypes.TenantId, apiKeyEntity.TenantId?.ToString() ?? ""),
    new Claim("ApiKeyId", apiKeyEntity.Id.ToString())
};

return AuthenticateResult.Success(ticket);

3. Creating and Managing API Keys

Creating a new key:

public class ApiKeyManager : DomainService
{
    public async Task<(ApiKey, string)> CreateAsync(
        Guid userId, 
        string name, 
        DateTime? expiresAt = null)
    {
        // Generate unique prefix
        var prefix = await GenerateUniquePrefixAsync();
        
        // Generate secure random key
        var key = GenerateSecureRandomString(32);
        
        // Hash the key for storage
        var keyHash = HashHelper.ComputeSha256(key);
        
        var apiKey = new ApiKey(
            GuidGenerator.Create(),
            userId,
            name,
            prefix,
            keyHash,
            expiresAt,
            CurrentTenant.Id
        );
        
        await _apiKeyRepository.InsertAsync(apiKey);
        
        // Return both entity and the full key (prefix_key)
        // This is the ONLY time the actual key is visible
        return (apiKey, $"{prefix}_{key}");
    }
}

Important: The actual key is returned only once during creation. After that, only the hash is stored.

Using API Keys in Your Application

Once created, clients can use the API key to authenticate:

HTTP Header (Recommended):

curl -H "X-Api-Key: sk_prod_abc123def456..." \
     https://api.example.com/api/products

JavaScript:

const response = await fetch('https://api.example.com/api/products', {
  headers: {
    'X-Api-Key': 'sk_prod_abc123def456...'
  }
});

C# HttpClient:

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "sk_prod_abc123def456...");
var response = await client.GetAsync("https://api.example.com/api/products");

Python:

import requests

headers = {'X-Api-Key': 'sk_prod_abc123def456...'}
response = requests.get('https://api.example.com/api/products', headers=headers)

Permission Management

API keys inherit the user's permissions, but you can further restrict them:

This allows scenarios like:

Read-only API key for reporting tools
Limited scope keys for third-party integrations
Service-specific keys with minimal permissions

// Check if current request is authenticated via API key
if (CurrentUser.FindClaim("ApiKeyId") != null)
{
    var apiKeyId = CurrentUser.FindClaim("ApiKeyId").Value;
    // Additional API key specific logic
}

Performance Considerations

The implementation uses several optimizations:

1. Prefix-based indexing: Database lookups are done by prefix (indexed column), not the full key hash.

2. Distributed caching: API keys are cached after first lookup, dramatically reducing database queries.

// Cache configuration
Configure(options =>
{
    options.KeyPrefix = "ApiKey:";
});

3. Cache invalidation: When a key is modified or deleted, cache is automatically invalidated.

Typical Performance:

Cached lookup: < 5ms
Database lookup: < 50ms
Cache hit rate: ~95%

Security Best Practices

When implementing API key authentication, follow these guidelines:

✅ Always use HTTPS - Never send API keys over unencrypted connections

✅ Use different keys per environment - Separate keys for dev, staging, production

❌ Don't log the full key - Only log the prefix for debugging

Getting Started

The complete source code is available on GitHub:

Repository: github.com/salihozkara/AbpApikeyManagement

To integrate it into your ABP project:

Clone or download the repository
Add project references to your solution
Add module dependencies to your modules
Run EF Core migrations to create the database tables
Navigate to /ApiKeyManagement to start managing keys

// In your Web module
[DependsOn(typeof(ApiKeyManagementWebModule))]
public class YourWebModule : AbpModule
{
    // ...
}

// In your HttpApi.Host module
[DependsOn(typeof(ApiKeyManagementHttpApiModule))]
public class YourHttpApiHostModule : AbpModule
{
    // ...
}

Conclusion

API key authentication remains a crucial part of modern API security, especially for machine-to-machine communication. While it shouldn't replace user authentication methods like OAuth2 for user-facing applications, it's perfect for:

Automated scripts and tools
Service-to-service communication
Third-party integrations
Long-lived access without token refresh complexity

The implementation shown here demonstrates how ABP Framework's modular architecture, DDD principles, and built-in features (multi-tenancy, caching, permissions) can be leveraged to build a production-ready API key management system.

The solution is open-source and ready to be integrated into your ABP projects. Feel free to explore the code, suggest improvements, or adapt it to your specific needs.

Resources:

GitHub Repository: salihozkara/AbpApikeyManagement
ABP Framework: abp.io
ABP Documentation: docs.abp.io

Happy coding! 🚀

What is That Domain Service in DDD for .NET Developers

Mon, 10 Nov 2025 06:37:51 Z

What is That Domain Service in DDD for .NET Developers?

When you start applying Domain-Driven Design (DDD) in your .NET projects, you'll quickly meet some core building blocks: Entities, Value Objects, Aggregates, and finally… Domain Services.

But what exactly is a Domain Service, and when should you use one?

Let's break it down with practical examples and ABP Framework implementation patterns.

The Core Idea of Domain Services

A Domain Service represents a domain concept that doesn't naturally belong to a single Entity or Value Object, but still belongs to the domain layer - not to the application or infrastructure.

In short:

If your business logic doesn't fit into a single Entity, but still expresses a business rule, that's a good candidate for a Domain Service.

Example: Money Transfer Between Accounts

Imagine a simple banking system where you can transfer money between accounts.

public class Account : AggregateRoot
{
    public decimal Balance { get; private set; }

    // Domain model should be created in a valid state.
    public Account(decimal openingBalance = 0m)
    {
        if (openingBalance < 0)
            throw new BusinessException("Opening balance cannot be negative.");
        Balance = openingBalance;
    }

    public void Withdraw(decimal amount)
    {
        if (amount <= 0)
            throw new BusinessException("Withdrawal amount must be positive.");
        if (Balance < amount)
            throw new BusinessException("Insufficient balance.");
        Balance -= amount;
    }

    public void Deposit(decimal amount)
    {
        if (amount <= 0)
            throw new BusinessException("Deposit amount must be positive.");
        Balance += amount;
    }
}

In a richer domain you might introduce a Money value object (amount + currency + rounding rules) instead of a raw decimal for stronger invariants.

Implementing a Domain Service

public class MoneyTransferManager : DomainService
{
    public void Transfer(Account from, Account to, decimal amount)
    {
        if (from is null) throw new ArgumentNullException(nameof(from));
        if (to is null) throw new ArgumentNullException(nameof(to));
        if (ReferenceEquals(from, to))
            throw new BusinessException("Cannot transfer to the same account.");
        if (amount <= 0)
            throw new BusinessException("Transfer amount must be positive.");

        from.Withdraw(amount);
        to.Deposit(amount);
    }
}

Naming Convention: ABP suggests using the Manager or Service suffix for domain services. We typically use Manager suffix (e.g., IssueManager, OrderManager).

Note: This is a synchronous domain operation. The domain service focuses purely on business rules without infrastructure concerns like database access or event publishing. For cross-cutting concerns, use Application Service layer or domain events.

Domain Service vs. Application Service

Here's a quick comparison:

| Layer | Responsibility | Example | | ----------------------- | -------------------------------------------------------------------------------- | ---------------------------- | | Domain Service | Pure business rule spanning entities/aggregates | MoneyTransferManager | | Application Service | Orchestrates use cases, handles repositories, transactions, external systems | BankAppService |

The Application Service Layer

An Application Service orchestrates the domain logic and handles infrastructure concerns:

public class BankAppService : ApplicationService
{
    private readonly IRepository _accountRepository;
    private readonly MoneyTransferManager _moneyTransferManager;

    public BankAppService(
        IRepository accountRepository,
        MoneyTransferManager moneyTransferManager)
    {
        _accountRepository = accountRepository;
        _moneyTransferManager = moneyTransferManager;
    }

    public async Task TransferAsync(Guid fromId, Guid toId, decimal amount)
    {
        var from = await _accountRepository.GetAsync(fromId);
        var to = await _accountRepository.GetAsync(toId);

        _moneyTransferManager.Transfer(from, to, amount);

        await _accountRepository.UpdateAsync(from);
        await _accountRepository.UpdateAsync(to);
    }
}

Note: Domain services are automatically registered to Dependency Injection with a Transient lifetime when inheriting from DomainService.

Benefits of ABP's DomainService Base Class

The DomainService base class gives you access to:

Localization (IStringLocalizer L) - Multi-language support for error messages
Logging (ILogger Logger) - Built-in logger for tracking operations
Local Event Bus (ILocalEventBus LocalEventBus) - Publish local domain events
Distributed Event Bus (IDistributedEventBus DistributedEventBus) - Publish distributed events
GUID Generator (IGuidGenerator GuidGenerator) - Sequential GUID generation for better database performance
Clock (IClock Clock) - Abstraction for date/time operations

Example with ABP Features

Important: While domain services can publish domain events using the event bus, they should remain focused on business rules. Consider whether event publishing belongs in the domain service or the application service based on your consistency boundaries.

public class MoneyTransferredEvent
{
    public Guid FromAccountId { get; set; }
    public Guid ToAccountId { get; set; }
    public decimal Amount { get; set; }
}

public class MoneyTransferManager : DomainService
{
    public async Task TransferAsync(Account from, Account to, decimal amount)
    {
        if (from is null) throw new ArgumentNullException(nameof(from));
        if (to is null) throw new ArgumentNullException(nameof(to));
        if (ReferenceEquals(from, to))
            throw new BusinessException(L["SameAccountTransferNotAllowed"]);
        if (amount <= 0)
            throw new BusinessException(L["InvalidTransferAmount"]);

        // Log the operation
        Logger.LogInformation(
            "Transferring {Amount} from {From} to {To}", amount, from.Id, to.Id);

        from.Withdraw(amount);
        to.Deposit(amount);

        // Publish local event for further policies (limits, notifications, audit, etc.)
        await LocalEventBus.PublishAsync(
            new MoneyTransferredEvent
            {
                FromAccountId = from.Id,
                ToAccountId = to.Id,
                Amount = amount
            }
        );
    }
}

Local Events: By default, event handlers are executed within the same Unit of Work. If an event handler throws an exception, the database transaction is rolled back, ensuring consistency.

Best Practices

1. Keep Domain Services Pure and Focused on Business Rules

Domain services should only contain business logic. They should not be responsible for application-level concerns like database transactions, authorization, or fetching entities from a repository.

// Good ✅ Pure rule: receives aggregates already loaded.
public class MoneyTransferManager : DomainService
{
    public void Transfer(Account from, Account to, decimal amount)
    {
        // Business rules and coordination
        from.Withdraw(amount);
        to.Deposit(amount);
    }
}

// Bad ❌ Mixing application and domain concerns.
// This logic belongs in an Application Service.
public class MoneyTransferManager : DomainService
{
    private readonly IRepository _accountRepository;
    
    public MoneyTransferManager(IRepository accountRepository)
    {
        _accountRepository = accountRepository;
    }

    public async Task TransferAsync(Guid fromId, Guid toId, decimal amount)
    {
        // Don't fetch entities inside a domain service.
        var from = await _accountRepository.GetAsync(fromId);
        var to = await _accountRepository.GetAsync(toId);

        from.Withdraw(amount);
        to.Deposit(amount);
    }
}

2. Leverage Entity Methods First

Always prefer encapsulating business logic within an entity's methods when the logic belongs to a single aggregate. A domain service should only be used when a business rule spans multiple aggregates.

// Good ✅ - Internal state change belongs in the entity
public class Account : AggregateRoot
{
    public decimal Balance { get; private set; }
    
    public void Withdraw(decimal amount)
    {
        if (Balance < amount)
            throw new BusinessException("Insufficient balance");
        Balance -= amount;
    }
}

// Use Domain Service only when logic spans multiple aggregates
public class MoneyTransferManager : DomainService
{
    public void Transfer(Account from, Account to, decimal amount)
    {
        from.Withdraw(amount);  // Delegates to entity
        to.Deposit(amount);     // Delegates to entity
    }
}

3. Prefer Domain Services over Anemic Entities

Avoid placing business logic that coordinates multiple entities directly into an application service. This leads to an "Anemic Domain Model," where entities are just data bags and the business logic is scattered in application services.

// Bad ❌ - Business logic is in the Application Service (Anemic Domain)
public class BankAppService : ApplicationService
{
    public async Task TransferAsync(Guid fromId, Guid toId, decimal amount)
    {
        var from = await _accountRepository.GetAsync(fromId);
        var to = await _accountRepository.GetAsync(toId);

        // This is domain logic and should be in a Domain Service
        if (ReferenceEquals(from, to))
            throw new BusinessException("Cannot transfer to the same account.");
        if (amount <= 0)
            throw new BusinessException("Transfer amount must be positive.");

        from.Withdraw(amount);
        to.Deposit(amount);
    }
}

4. Use Meaningful Names

ABP recommends naming domain services with a Manager or Service suffix based on the business concept they represent.

// Good ✅
MoneyTransferManager
OrderManager
IssueManager
InventoryAllocationService

// Bad ❌
AccountHelper
OrderProcessor

Advanced Example: Order Processing with Inventory Check

Here's a more complex scenario showing domain service interaction with domain abstractions:

// Domain abstraction - defines contract but implementation is in infrastructure
public interface IInventoryChecker : IDomainService
{
    Task IsAvailableAsync(Guid productId, int quantity);
}

public class OrderManager : DomainService
{
    private readonly IInventoryChecker _inventoryChecker;

    public OrderManager(IInventoryChecker inventoryChecker)
    {
        _inventoryChecker = inventoryChecker;
    }

    // Validates and coordinates order processing with inventory
    public async Task ProcessAsync(Order order, Inventory inventory)
    {
        // First pass: validate availability using domain abstraction
        foreach (var item in order.Items)
        {
            if (!await _inventoryChecker.IsAvailableAsync(item.ProductId, item.Quantity))
            {
                throw new BusinessException(
                    L["InsufficientInventory", item.ProductId]);
            }
        }
        
        // Second pass: perform reservations
        foreach (var item in order.Items)
        {
            inventory.Reserve(item.ProductId, item.Quantity);
        }
        
        order.SetStatus(OrderStatus.Processing);
    }
}

Domain Abstractions: The IInventoryChecker interface is a domain service contract. Its implementation can be in the infrastructure layer, but the contract belongs to the domain. This keeps the domain layer independent of infrastructure details while still allowing complex validations.

Caution: Always perform validation and action atomically within a single transaction to avoid race conditions (TOCTOU - Time Of Check Time Of Use).

Transaction Boundaries: When a domain service coordinates multiple aggregates, ensure the Application Service wraps the operation in a Unit of Work to maintain consistency. ABP's [UnitOfWork] attribute or Application Services' built-in UoW handling ensures this automatically.

Common Pitfalls and How to Avoid Them

1. Bloated Domain Services

Don't let domain services become "god objects" that do everything. Keep them focused on a single business concept.

// Bad ❌ - Too many responsibilities
public class AccountManager : DomainService
{
    public void Transfer(Account from, Account to, decimal amount) { }
    public void CalculateInterest(Account account) { }
    public void GenerateStatement(Account account) { }
    public void ValidateAddress(Account account) { }
    public void SendNotification(Account account) { }
}

// Good ✅ - Split by business concept
public class MoneyTransferManager : DomainService
{
    public void Transfer(Account from, Account to, decimal amount) { }
}

public class InterestCalculationManager : DomainService
{
    public void Calculate(Account account) { }
}

2. Circular Dependencies Between Aggregates

When domain services coordinate multiple aggregates, be careful about creating circular dependencies.

// Consider using Domain Events instead of direct coupling
public class OrderManager : DomainService
{
    public async Task ProcessAsync(Order order)
    {
        order.SetStatus(OrderStatus.Processing);
        
        // Instead of directly modifying Customer aggregate here,
        // publish an event that CustomerManager can handle
        await LocalEventBus.PublishAsync(new OrderProcessedEvent
        {
            OrderId = order.Id,
            CustomerId = order.CustomerId
        });
    }
}

3. Confusing Domain Service with Domain Event Handlers

Domain services orchestrate business operations. Domain event handlers react to state changes. Don't mix them.

// Domain Service - Orchestrates business logic
public class MoneyTransferManager : DomainService
{
    public async Task TransferAsync(Account from, Account to, decimal amount)
    {
        from.Withdraw(amount);
        to.Deposit(amount);
        await LocalEventBus.PublishAsync(
            new MoneyTransferredEvent
            {
                FromAccountId = from.Id,
                ToAccountId = to.Id,
                Amount = amount
            }
        );
    }
}

// Domain Event Handler - Reacts to domain events
public class MoneyTransferredEventHandler : 
    ILocalEventHandler,
    ITransientDependency
{
    public async Task HandleEventAsync(MoneyTransferredEvent eventData)
    {
        // Send notification, update analytics, etc.
    }
}

Testing Domain Services

Domain services are easy to test because they have minimal dependencies:

public class MoneyTransferManager_Tests
{
    [Fact]
    public void Should_Transfer_Money_Between_Accounts()
    {
        // Arrange
        var fromAccount = new Account(1000m);
        var toAccount = new Account(500m);
        var manager = new MoneyTransferManager();

        // Act
        manager.Transfer(fromAccount, toAccount, 200m);

        // Assert
        fromAccount.Balance.ShouldBe(800m);
        toAccount.Balance.ShouldBe(700m);
    }

    [Fact]
    public void Should_Throw_When_Insufficient_Balance()
    {
        var fromAccount = new Account(100m);
        var toAccount = new Account(500m);
        var manager = new MoneyTransferManager();
        
        Should.Throw(() => 
            manager.Transfer(fromAccount, toAccount, 200m));
    }

    [Fact]
    public void Should_Throw_When_Amount_Is_NonPositive()
    {
        var fromAccount = new Account(100m);
        var toAccount = new Account(100m);
        var manager = new MoneyTransferManager();
        
        Should.Throw(() => 
            manager.Transfer(fromAccount, toAccount, 0m));
        Should.Throw(() => 
            manager.Transfer(fromAccount, toAccount, -5m));
    }

    [Fact]
    public void Should_Throw_When_Same_Account()
    {
        var account = new Account(100m);
        var manager = new MoneyTransferManager();
        
        Should.Throw(() => 
            manager.Transfer(account, account, 10m));
    }
}

Integration Testing with ABP Test Infrastructure

public class MoneyTransferManager_IntegrationTests : BankingDomainTestBase
{
    private readonly MoneyTransferManager _transferManager;
    private readonly IRepository _accountRepository;

    public MoneyTransferManager_IntegrationTests()
    {
        _transferManager = GetRequiredService();
        _accountRepository = GetRequiredService>();
    }

    [Fact]
    public async Task Should_Transfer_And_Persist_Changes()
    {
        // Arrange
        var fromAccount = new Account(1000m);
        var toAccount = new Account(500m);
        
        await _accountRepository.InsertAsync(fromAccount);
        await _accountRepository.InsertAsync(toAccount);
        await UnitOfWorkManager.Current.SaveChangesAsync();

        // Act
        await _transferManager.TransferAsync(fromAccount, toAccount, 200m);
        await UnitOfWorkManager.Current.SaveChangesAsync();

        // Assert
        var updatedFrom = await _accountRepository.GetAsync(fromAccount.Id);
        var updatedTo = await _accountRepository.GetAsync(toAccount.Id);
        
        updatedFrom.Balance.ShouldBe(800m);
        updatedTo.Balance.ShouldBe(700m);
    }
}

When NOT to Use a Domain Service

Not every operation needs a domain service. Avoid over-engineering:

Simple CRUD Operations: Use Application Services directly
Single Aggregate Operations: Use Entity methods
Infrastructure Concerns: Use Infrastructure Services
Application Workflow: Use Application Services

// Don't create a domain service for this ❌
public class AccountBalanceReader : DomainService
{
    public decimal GetBalance(Account account) => account.Balance;
}

// Just use the property directly ✅
var balance = account.Balance;

Summary

Domain Services are domain-level, not application-level
They encapsulate business logic that doesn't belong to a single entity
They keep your entities clean and business logic consistent
In ABP, inherit from DomainService to get built-in features
Keep them focused, pure, and testable

Final Thoughts

Next time you're writing a business rule that doesn't clearly belong to an entity, ask yourself:

"Is this a Domain Service?"

If it's pure domain logic that coordinates multiple entities or implements a business rule, put it in the domain layer - your future self (and your team) will thank you.

Domain Services are a powerful tool in your DDD toolkit. Use them wisely to keep your domain model clean, expressive, and maintainable.

Truly Layering a .NET Application Based on DDD Principles

Mon, 15 Sep 2025 07:05:18 Z

Truly Layering a .NET Application Based on DDD Principles

Okay, so we ALL been there, right? You start new project thinking "this time will be different" - clean code, perfect architecture, everything organized. Fast forward 3 months and your codebase look like someone throw grenade into bowl of spaghetti. Business logic everywhere, your controllers doing database work, and every new feature feel like defusing bomb.

I been there too many times, and honestly, it suck. But here thing - there actually way to build .NET apps that not turn into maintenance nightmare. It called Layered Architecture + Domain-Driven Design (DDD), and once you get it, it game changer.

Let me walk you through this step by step, no fluff, just practical stuff that actually work.

Layered Architecture 101 (The Foundation)

So layered architecture basically about keeping your code organized. Instead of having everything mixed together like bad smoothie, you separate concerns into different layers. Think like organizing your room - clothes go in closet, books on shelf, etc.

Here how it typically break down:

Presentation Layer (UI): This what users actually see and click on - your ASP.NET Core MVC stuff, Razor Pages, Blazor, whatever float your boat.
Application Layer: The conductor of orchestra. It not do heavy lifting itself, but tell everyone else what to do. It like middle manager of your code.
Domain Layer: The VIP section. This where all your business rules live - entities, value objects, whole nine yards. This layer pure and not give damn about databases or UI.
Infrastructure Layer: The "how-to" guy. Database stuff, email sending, API calls - basically all technical plumbing that make everything work.

The golden rule? Dependency Rule: Layers can only talk to layers below them (or more central). UI talk to Application, Application talk to Domain, but Domain? Domain not talk to anyone. It the cool kid that everyone want to hang out with.

DDD: Where Magic Happen

Alright, so DDD not some fancy framework you install from NuGet. It more like mindset - basically saying "hey, let make our code actually reflect business we building for." Instead of having bunch of random classes, we organize everything around actual business domain.

Think like this: if you building e-commerce app, your code should scream "I'M E-COMMERCE APP" not "I'M BUNCH OF RANDOM CLASSES."

Here toolkit DDD give you (all living in your Domain Layer):

Entity: This something that have identity. Like Customer - two customers with same name still different people because they have different IDs. It like having two friends named John - they not same person.
Value Object: Opposite of entity. It defined by what it contain, not who it is. Address perfect for this - if two addresses have same street, city, and zip code, they same address. Usually immutable too.
Aggregate & Aggregate Root: This where it get interesting. Aggregate like family of related objects that stick together. Aggregate Root head of family - only one you talk to when you want change something. Like Order that contain OrderItems. You not mess with OrderItem directly, you tell Order to handle it.
Repository (Interface): Think like your data access contract. It say "here how you can get and save stuff" without caring about whether it SQL Server, MongoDB, or file on your desktop. Interface live in Domain, implementation go in Infrastructure.
Domain Service: When business logic too complex for single entity or value object, this your go-to. It like utility class but for business rules.

Putting It All Together: Real C# Code

Alright, enough theory. Let see what this actually look like in real .NET solution. You typically have projects like:

MyProject.Domain (or .Core) - The VIP section
MyProject.Application - The middle manager
MyProject.Infrastructure - The technical guy
MyProject.Web (or whatever UI you using) - The pretty face

1. The Domain Layer (MyProject.Domain) - The Heart

This where magic happen. Zero dependencies on other projects (maybe some basic utility libraries, but that it). Pure business logic, no database nonsense, no UI concerns.

// In MyProject.Domain/Orders/Order.cs
public class Order : AggregateRoot
{
    public Address ShippingAddress { get; private set; }
    private readonly List _orderItems = new();
    public IReadOnlyCollection OrderItems => _orderItems.AsReadOnly();

    // Private constructor for ORM
    private Order() { }

    public Order(Guid id, Address shippingAddress) : base(id)
    {
        ShippingAddress = shippingAddress;
    }

    public void AddOrderItem(Guid productId, int quantity, decimal price)
    {
        if (quantity <= 0)
        {
            throw new BusinessException("Quantity must be greater than zero.");
        }
        // More business rules...
        _orderItems.Add(new OrderItem(productId, quantity, price));
    }
}

// In MyProject.Domain/Orders/IOrderRepository.cs
public interface IOrderRepository
{
    Task GetAsync(Guid id);
    Task AddAsync(Order order);
    Task UpdateAsync(Order order);
}

See what I mean? The Order class all about business rules (AddOrderItem with validation and all that jazz). It not give damn about databases or how it get saved. That someone else problem.

2. The Application Layer (MyProject.Application) - The Conductor

This where we orchestrate everything. It talk to domain objects and use repositories to get/save data. Think like middle manager that coordinate work but not do heavy lifting.

// In MyProject.Application/Orders/OrderAppService.cs
public class OrderAppService
{
    private readonly IOrderRepository _orderRepository;

    public OrderAppService(IOrderRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }

    public async Task CreateOrderAsync(CreateOrderDto input)
    {
        var shippingAddress = new Address(input.Street, input.City, input.ZipCode);
        var order = new Order(Guid.NewGuid(), shippingAddress);

        foreach (var item in input.Items)
        {
            order.AddOrderItem(item.ProductId, item.Quantity, item.Price);
        }

        await _orderRepository.AddAsync(order);
    }
}

The application service coordinate everything but let domain objects handle actual business rules. Clean separation!

3. The Infrastructure Layer (MyProject.Infrastructure) - The Technical Guy

This where we implement all interfaces we defined in domain. Entity Framework Core, email services, API clients - all technical plumbing live here.

// In MyProject.Infrastructure/Orders/EfCoreOrderRepository.cs
public class EfCoreOrderRepository : IOrderRepository
{
    private readonly MyDbContext _dbContext;

    public EfCoreOrderRepository(MyDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task GetAsync(Guid id)
    {
        // EF Core logic to get the order
        return await _dbContext.Orders.FindAsync(id);
    }

    public async Task AddAsync(Order order)
    {
        await _dbContext.Orders.AddAsync(order);
    }
    
    // ... other implementations
}

ABP Framework: The Shortcut (Because We Lazy)

Look, setting all this up from scratch pain. That where ABP Framework come in clutch. It basically DDD and layered architecture on steroids, and it do all boring setup work for you.

ABP not just talk talk - it walk walk. When you create new ABP solution, boom! Perfect project structure, all layered and DDD-compliant, ready to go.

Here what you get out of box:

Base Classes: AggregateRoot, Entity, ValueObject - all with good stuff like optimistic concurrency and domain events. No more writing boilerplate.
Generic Repositories: No more writing IRepository interfaces for every single entity. ABP give you IRepository with all standard CRUD methods. Just inject it and go.
Application Services: Inherit from ApplicationService and boom - you done. It handle validation, authorization, exception handling, all that cross-cutting concern stuff without cluttering your actual business logic.

With ABP, our OrderAppService become way cleaner:

// In ABP project, this much cleaner
public class OrderAppService : ApplicationService, IOrderAppService
{
    private readonly IRepository _orderRepository;

    public OrderAppService(IRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }

    public async Task CreateAsync(CreateOrderDto input)
    {
        // ... same logic as before, but using ABP generic repository
        var order = new Order(...);
        await _orderRepository.InsertAsync(order);
    }
}

Wrapping Up

Look, I get it - this stuff take discipline and it not always fastest way to get features out door. But here thing: when you actually layer your app properly and put solid Domain Model at center, you end up with software that not suck to maintain.

Your code start speaking language of business instead of some random technical jargon. That whole point of DDD - make your code reflect what you actually building for.

Yeah, it take work upfront, but payoff huge. And frameworks like ABP make journey way less painful. Trust me, your future self will thank you when you not debugging spaghetti code at 2 AM.

What you think? You try this approach before, or you still stuck in spaghetti code phase? Let me know in comments!

WE HAD A BLAST AT BASTA! FRANKFURT 2025

Tue, 11 Mar 2025 12:42:56 Z

Our team had an amazing time at BASTA! Frankfurt 2025, held from March 3 to 8 at the Frankfurt am Main Marriott Hotel. As a sponsor for this major conference for asp.net web developers, we were thrilled to connect with so many talented participants.

Event Highlights

The conference hosted many talented developers as speakers. One of them was İsmail Çağdaş who’s a lead developer from ABP team who talked about the concepts of monoliths and microservices. He explained how modular monoliths combine the strengths of these two architectures, using the ABP Framework as an example to showcase its modularity features and demonstrate how to build and develop a modular monolith application.

ABP’S Presence

At our booth we displayed the latest features of the ABP Framework and gathered valuable feedback from especially dotnet developers. So many attendees showed interest in ABP which was very exciting. It was great engaging with so many participants who wanted to learn more about how ABP provides the infrastructure and tools to create business solutions.

We're also very grateful to our booth neighbor, Xceed and it was a lot of fun connecting with them during the conference. For those who don’t know, Xceed provides comprehensive UI components that allow developers to focus on innovation and their business requirements.

Networking and Community Engagement

We organized two raffles during the event, where attendees had the chance to win 2 great prizes. One attendee won a LEGO set and another won an Amazon Kindle. We were happy to see many people attending our raffles, it definitely made this event more fun. Congratulations to the winners and thanks to those who participated!

Looking Ahead

BASTA! Frankfurt 2025 strengthened our commitment to the developer community. We want to continue our support for asp.net core developers, helping them create asp.net applications and optimize their workflows for web applications.

Gratitude and Future Events

Thank you to the organizers, speakers, and attendees for making BASTA! Frankfurt 2025 such a fantastic experience. We look forward to future events and continued contributions to the net framework developers.

We look forward to sharing more updates with you soon. We hope to see you at our next event!

Middleware Now Supports Keyed Dependency Injection in .NET 9

Wed, 13 Nov 2024 10:15:34 Z

Middleware Now Supports Keyed Dependency Injection in .NET 9

This article explores a new feature in .NET 9 that enables keyed dependency injection in middleware. Previously, .NET 8 introduced keyed services, which allowed developers to register multiple instances of the same service type with distinct keys. Now, .NET 9 extends this feature to middleware, making it easier to inject specific services within the middleware based on defined keys. For more details, see this overview on the .NET blog.

What is Keyed Dependency Injection?

Keyed dependency injection is a technique for registering multiple service versions with unique identifiers, or “keys.” This approach is especially helpful when multiple implementations of the same service are required in different contexts. For example, you may have various logging services but want to inject a specific logger based on the application’s current needs. By using keys, developers can ensure that the appropriate service version is injected precisely where it’s needed.

Using Keyed Dependency Injection in Middleware

In .NET 9, developers can now use keyed dependency injection directly in middleware. Keyed services can be injected through the middleware constructor or via the Invoke/InvokeAsync methods, allowing for straightforward and flexible control of service instances in middleware components. Here’s an example of how to configure and use keyed dependency injection in middleware:

var builder = WebApplication.CreateBuilder(args);

// Register services with unique keys
builder.Services.AddKeyedSingleton("test");
builder.Services.AddKeyedScoped("test2");

var app = builder.Build();
app.UseMiddleware();
app.Run();

internal class MyMiddleware
{
    private readonly RequestDelegate _next;
    private readonly MySingletonClass _singletonService;

    // Constructor injection with key
    public MyMiddleware(RequestDelegate next, [FromKeyedServices("test")] MySingletonClass singletonService)
    {
        _next = next;
        _singletonService = singletonService;
    }

    // Invoke method with additional scoped service injection using key
    public Task Invoke(HttpContext context, [FromKeyedServices("test2")] MyScopedClass scopedService)
    {
        // Middleware logic here
        return _next(context);
    }
}

In this example:

MySingletonClass and MyScopedClass are registered with unique keys ("test" and "test2").
These services are injected into the middleware through both the constructor and Invoke method, based on their respective keys.

This approach allows developers to manage which service instances are available within middleware precisely.

Conclusion

Keyed dependency injection in middleware is a significant addition in .NET 9. It provides developers with more control over which services are injected based on specific keys. This enhancement enables selective service injection in middleware scenarios, allowing for more modular and maintainable applications.

References

EF Core 8 - Enhancements to JSON column mapping

Wed, 08 Nov 2023 12:56:36 Z

EF Core 8 - Enhancements to JSON column mapping

In this article, we will examine the enhancements introduced in EF Core 8 for the JSON column feature, building upon the foundation laid by JSON columns in Entity Framework Core 7.

The entity classes we will be using in the article

public class Person
{
    public int Id { get; set; }
    [Required]
    public string Name { get; set; }
    [Required]
    public ContactDetails ContactDetails { get; set; }
}

public class ContactDetails
{
    public List Addresses { get; set; } = new();
    public string? Phone { get; set; }
}

public class Address
{
    public Address(string street, string city, string postcode, string country)
    {
        Street = street;
        City = city;
        Postcode = postcode;
        Country = country;
    }

    public string Street { get; set; }
    public string City { get; set; }
    public string Postcode { get; set; }
    public string Country { get; set; }
    public bool IsMainAddress { get; set; }
}

The DbContext class we will be using in the article

public class AppDbContext : DbContext
{
    public DbSet Persons { get; set; } = null!;

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
#if SQLSERVER
        optionsBuilder.UseSqlServer("Server=localhost;Database=EfCore8Json;Trusted_Connection=True;TrustServerCertificate=True");
#elif SQLITE
        optionsBuilder.UseSqlite("Data Source=EfCore8Json.db");
#endif
        base.OnConfiguring(optionsBuilder);
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity(b =>
        {
            b.ToTable("Persons");
            b.HasKey(x => x.Id);
            b.Property(x => x.Name).IsRequired();
            b.OwnsOne(x => x.ContactDetails, cb =>
            {
                cb.ToJson();
                cb.Property(x => x.Phone);
                cb.OwnsMany(x => x.Addresses);
            });
        });

        base.OnModelCreating(modelBuilder);
    }
}

Translate element access into JSON arrays

EF Core 8 supports indexing in JSON arrays when executing queries. For example, the following query returns individuals whose first address is the main address in the database:

var query = dbContext.Persons
    .Select(x => x.ContactDetails.Addresses[0])
    .Where(x => x.IsMainAddress == true)
    .ToListAsync();

The generated SQL query is as follows when using SQL Server:

SELECT JSON_QUERY([p].[ContactDetails], '$.Addresses[0]'), [p].[Id]
FROM [Persons] AS [p]
WHERE CAST(JSON_VALUE([p].[ContactDetails], '$.Addresses[0].IsMainAddress') AS bit) = CAST(1 AS bit)

Note: If you attempt to access an index that is outside of the array, it will return null.

JSON Columns for SQLite

In EF Core 7, JSON column mapping was supported for Azure SQL/SQL Server. In EF Core 8, this support has been extended to include SQLite as well.

Queries into JSON columns

The following query returns individuals whose first address is the main address in the database:

var query = dbContext.Persons
    .Select(x => x.ContactDetails.Addresses[0])
    .Where(x => x.IsMainAddress == true)
    .ToListAsync();

The generated SQL query is as follows when using SQLite:

SELECT "p"."ContactDetails" ->> '$.Addresses[0]', "p"."Id"
FROM "Persons" AS "p"
WHERE "p"."ContactDetails" ->> '$.Addresses[0].IsMainAddress' = 0

References

EF Core 8 - Enhancements to JSON column mapping

💻 Speed Up Your ASP.NET Application 🚀

Tue, 18 Apr 2023 14:49:21 Z

How to Optimize Your ASP.NET Application for Improved Performance

If you want your ASP.NET application to perform well, you need to optimize it for speed, responsiveness, and user experience. Performance optimization is critical for factors like fast page load times, improved response efficiency, and happy users. In this article, I'll provide several tips and tricks to help you optimize performance in ASP.NET Core.

Use Response Compression in Your ASP.NET Application

You can use ASP.NET Core's built-in response compression middleware to compress the response data and reduce the amount of data that needs to be transferred over the network. To use response compression, add the following code to your application's Startup.cs file:


services.AddResponseCompression(options =>

{

    options.EnableForHttps = true;

});



app.UseResponseCompression();

🖼️ Optimize Images in Your ASP.NET Application:

Images can be a major contributor to page bloat and slow load times. Here are some tips to optimize images:

🖌️ Use a tool like ImageOptim or Kraken.io to compress and optimize images.

🖼️ Specify the width and height of images in HTML so the browser can allocate space for them before they load.

📝 Use alt attributes to provide descriptive text for images, which can improve accessibility and also help with SEO.

📜 Use lazy loading for images that are below the fold, meaning they're not visible on the initial screen view. You can use libraries like Vanilla LazyLoad to implement lazy loading.

📱 Use responsive images to serve different image sizes to different devices. This can improve page load times by reducing the size of images that are displayed on smaller devices.

💻 Example:


var lazyLoadInstance = new LazyLoad();

🧱 Optimize HTML in Your ASP.NET Application:

The structure and organization of HTML can affect the page speed. Here are some tips to optimize HTML:

📝 Use the heading tags (h1, h2, h3, etc.) in a logical and sequential order.

🔩 Use the "defer" attribute for script tags that don't need to be executed immediately. This can improve the page load times by delaying the execution of scripts until after the page has rendered.

🔩 Use the "async" attribute for script tags that can be executed asynchronously. This can further improve the page load times by allowing scripts to be downloaded and executed simultaneously.

🧱 Use semantic HTML elements (like nav, section, and article) to provide additional structure and meaning to the page.

🎨 Optimize CSS and JavaScript in Your ASP.NET Application:

CSS and JavaScript files can be a major contributor to the page load times. Here are some tips to optimize CSS and JavaScript in your ASP.NET application:

🔨 Minify and concatenate CSS and JavaScript files to reduce their size.

🔩 Use the "defer" or "async" attributes for script tags to delay or asynchronously load scripts.

🔡 Use system fonts in Your ASP.NET Application:

Loading custom fonts can be slow and increase page load times. Using system fonts can improve page speed by allowing the browser to use fonts that are already installed on the user's device.

🖼️ Use Placeholders and Progress Indicators in Your ASP.NET Application:

To improve the perceived performance of your website, you can use placeholders and progress indicators for slow-loading sections of your page. You can use JavaScript to load these sections after the initial page load.

💻 Example:






  Loading...


const placeholder = document.querySelector('#placeholder');

  fetch(placeholder.dataset.url)

    .then(response => response.text())

    .then(html => placeholder.innerHTML = html);

🔗 Use the Appropriate Link Text and ARIA Labels:

When using links, use appropriate link texts that accurately describe the content of the linked page. This can improve the accessibility and also help with SEO.

ARIA labels should also be used to provide additional context for links. This can also improve the accessibility and help with SEO.

💻 Example:


Example

Another Example

🌐 Optimize the Third-party Resources in Your ASP.NET Application:

Third-party resources like social media widgets and advertising scripts can slow down the page load times. Here are some tips to optimize third-party resources:

🔩 Use asynchronous scripts when possible.

🔍 Only load third-party resources that are necessary for the page.

By following these optimization techniques, you can significantly improve the page speed of your ASP.NET Core web application.

Optimized Web Applications with ABP Framework?

ABP Framework offers an opinionated architecture to build enterprise software solutions with ASP.NET Core best practices on top of the .NET and the ASP.NET Core platforms. It is also a powerful infrastructure to help you develop low-effort web-optimized applications.

It provides the fundamental web application infrastructure, production-ready dotnet startup templates, modules, asp.net core ui themes, tooling, guides and documentation to implement that ASP.NET core architecture properly and automate the details and repetitive work as much as possible.

If you are starting a new ASP.NET Core project and want a fast website abp.io now...

IT IS FREE AND OPEN-SOURCE!

Streamline Localization in Your ABP Project

Wed, 01 Mar 2023 14:12:25 Z

Streamline Localization in Your ABP Project

Making localization changes to an ABP project can be a daunting task, especially if you're dealing with multiple languages and translations. During development, it's easy to overlook some changes and that leads to inconsistencies across different languages. Fortunately, I have developed a tool that can help streamline the localization process and ensure consistency across different languages.

The tool is a console application that uses JSON files to manage localization keys and their translations. It addresses three common scenarios that can arise during localization:

When the argument count of a key changes, it can be difficult to update the translations for all languages. My tool solves this problem by scanning all JSON files in the project folder and identifying any keys that have mismatched argument counts. It then offers two options to the user: delete the mismatched translations or export them as a JSON file for manual editing.
When a new key is added to the project, forgetting to add its translations to all the other languages is easy. My tool helps to avoid this issue by scanning the default language's JSON file and identifying any keys that don't have translations in other languages. It then exports these keys as a JSON file that can be used to add missing translations.
When a key's name is changed, it's important to update its translations in all the other languages. My tool makes this task simple by scanning all the JSON files in the project folder and updating any translations of the old key name with the new one.

The tool also includes an export feature that allows users to modify translations outside of the application and import them back into the JSON files.

How it Helps

With my Localization Key Synchronizer tool, you can perform complex localization changes more quickly and easily than by manually sifting through files and making changes one-by-one. This can save you significant time and effort, especially if you're working with a large number of languages or translations.

How it Works

When you run the Localization Key Synchronizer tool, it presents you with three options:

Find Asynchronous Keys
Apply Changes in the Exported File
Replace Keys

If you select "Find Asynchronous Keys," the tool prompts you to enter the default language path. Once you've entered the path, the tool displays all of the JSON files in the same folder as a multi-select list. After selecting one or more files, you are asked whether you want to find keys that do not match the number of arguments, missing keys, or both. If you select "Missing Keys," the tool prompts you to enter the absolute path to export the missing keys. After you've entered the path, the export process starts, and the tool closes.

If you select "Apply Changes in the Exported File" at the main menu, the tool prompts you to enter the path to the exported file. After you've entered the path, the import process starts, and the tool closes.

If you select "Replace Keys," the tool prompts you to enter the localization folder path, the old key, the new key, and the JSON files to apply the changes to. Once you've entered all the required information and made your selections, the tool performs the replacements and closes.

Conclusion

If you're struggling to manage localization changes in an ABP project, give my Localization Key Synchronizer tool a try. It can help streamline your workflow and make the process much more manageable. You can find the tool on GitHub.

To use the tool, simply run the console application and follow the prompts. It's a user-friendly solution that helps to ensure localization consistency in your ABP project. Give it a try and let me know what you think!

JSON Columns in Entity Framework Core 7

Mon, 28 Nov 2022 08:06:21 Z

JSON Columns in Entity Framework Core 7

In this article, we will see how to use the new JSON Columns features that came with EF Core 7 in an ABP based application (with examples).

JSON Columns

Most relational databases support columns that contain JSON documents. The JSON in these columns can be drilled into with queries. This allows, for example, filtering and sorting by the elements of the documents, as well as projection of elements out of the documents into results. JSON columns allow relational databases to take on some of the characteristics of document databases, creating a useful hybrid between these two database management approaches.

EF7 contains provider-agnostic support for JSON columns, with an implementation for SQL Server. This support allows the mapping of aggregates built from .NET types to JSON documents. Normal LINQ queries can be used on the aggregates, and these will be translated to the appropriate query constructs needed to drill into the JSON. EF7 also supports updating and saving changes to JSON documents.

You can find more information about JSON columns in EF Core's documentation.

Mapping JSON Columns

In EF Core, aggregate types can be defined using OwnsOne and OwnsMany methods. OwnsOne can be used to map a single aggregate and the OwnsMany method can be used to map a collection of aggregates.

With EF 7, we have a new extension method for mapping property to a JSON Column: ToJson. We can use this method to mark a property as a JSON Column. The property can be of any type that can be serialized to JSON.

The following example shows how to map a JSON column to an aggregate type:

public class ContactDetails
{
    public Address Address { get; set; }
    public string? Phone { get; set; }
}

public class Address
{
    public Address(string street, string city, string postcode, string country)
    {
        Street = street;
        City = city;
        Postcode = postcode;
        Country = country;
    }

    public string Street { get; set; }
    public string City { get; set; }
    public string Postcode { get; set; }
    public string Country { get; set; }
}

public class Person : AggregateRoot
{
    public string Name { get; set; } = null!;
    public ContactDetails ContactDetails { get; set; } = null!;
}

Above, we have defined an aggregate type ContactDetails that contains an Address and a Phone number. The aggregate type is configured in OnModelCreating using OwnsOne and ToJson methods below.
The Address property is mapped to a JSON column using ToJson, and the Phone property is mapped to a regular column. This requires just one call to ToJson() when configuring the aggregate type:


public class MyDbContext : AbpDbContext
{
    public DbSet Persons { get; set; }

    public MyDbContext(DbContextOptions options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);

        builder.Entity(b =>
        {
            b.ToTable(MyProjectConsts.DbTablePrefix + "Persons", MyProjectConsts.DbSchema);
            b.ConfigureByConvention();
            b.OwnsOne(x=>x.ContactDetails, c =>
            {
                c.ToJson(); //mark as JSON Column
                c.OwnsOne(cd => cd.Address);
            });
        });
    }
}

Querying JSON Columns

Queries into JSON columns work just the same as querying into any other aggregate type in EF Core. That's it, just use the LINQ! Here are some examples:

var persons = await (await GetDbSetAsync()).ToListAsync();

var contacts = await (await GetDbSetAsync()).Select(person => new
{
    person,
    person.ContactDetails.Phone, //query over JSON column
    Addresses = person.ContactDetails.Address //query over JSON column
}).ToListAsync();

var addresses = await (await GetDbSetAsync()).Select(person => new
{
    person,
    Addresses = person.ContactDetails.Address //query over JSON column
}).ToListAsync();

Updating JSON Columns

You can update JSON columns the same as updating any record by using the UpdateAsync method. The following example shows how to update a JSON column:

var person = await (await GetDbSetAsync()).FirstAsync();

person.ContactDetails.Phone = "123456789";
person.ContactDetails.Address = new Address("Street", "City", "Postcode", "Country");
await UpdateAsync(person, true);

JSON Column in a Database

After you've configured the database relations, created a new migration and applied it to database you will have a database table like below:

As you can see, thanks to JSON Columns feature the ContactDetails row has JSON content and we can use it in a query or update it from our application with the LINQ JSON query support that mentioned above.

Conclusion

In this article, I've briefly introduced the JSON Columns feature that was shipped with EF Core 7. It's pretty straightforward to use JSON Columns in an ABP based application. You can see the examples above and give it a try!

The Source Code

You can find the full source code of the example application here.

ABP.IO Stories

QuickGrid in .NET 11: Sorting and Paging That Live in the URL

QuickGrid in .NET 11: Sorting and Paging That Live in the URL

Why the URL, and why it matters architecturally

The sample app

People

The URL contract

What actually renders

Your own parameters are first-class citizens

Two grids on one page

Server-side paging with GridItemsProvider

Interactive pages keep the same contract

Edge cases I tested

Accessibility and SEO

Opting out

.NET 10 vs .NET 11, and the preview trail

Known issues and production readiness

Build and verification results

Adoption checklist

References

Building a Vendor Onboarding Workflow with ABP Low-Code

Building a Vendor Onboarding Workflow with ABP Low-Code

What We Are Building

A Quick Note on How Low-Code Fits Together

Add a Code-Defined Review Template

Create the Vendor Enums

Create the VendorApplication Entity

Generate a Grid Page

Build the Create/Edit Form

Apply the Migration Before Opening the Runtime

Try It in the React Runtime

Add a Custom Summary Endpoint

Add One Runtime Model

Read the Same Data from ABP Code

Going Further

Conclusion

Further Reading

Introducing ABP Low-Code: Build Real ABP Apps in Minutes

Introducing ABP Low-Code: Build Real ABP Apps in Minutes

ABP Low-Code at a glance

Built into the ABP Platform

Edit at runtime. See it in the app.

CRUD is table stakes

One model, multiple operational screens

When low-code needs code

From code-first entity to generated page

Low-code data stays reachable from C#

Why ABP Low-Code matters

Try it yourself

Further reading

Building Dynamic XML Sitemaps with ABP Framework

Building Dynamic XML Sitemaps with ABP Framework

What is an XML Sitemap?

Why Build a Custom Sitemap Module?

Project Architecture Overview

Installation

Module Configuration

Usage Examples

Example 1: Mark Static Pages

Example 2: Add Dynamic Content from Database

Example 3: Category-Based Dynamic Content

Testing Your Sitemaps

1. Run Your Application

2. Check Generated Files

3. Verify XML Content

4. Test in Browser

Advanced Configuration

Custom Regeneration Schedule

Environment-Specific Configuration

Manual Sitemap Generation

Real-World Use Cases

E-Commerce Platform

Content Management System

Best Practices

1. Group Related Content

2. Use Filters Wisely

3. Keep URLs Clean

Troubleshooting

Sitemap Not Generated

Pages Not Appearing

Server-side paging with `GridItemsProvider`