Forem: ABP.IO

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

ABP.IO — Mon, 24 Nov 2025 07:33:03 +0000

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 :
Store both in vector database with references
Query flow :

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<DocumentChunk>()
        .Property(e => e.Embedding)
        .HasColumnType("vector(1536)"); // 👈 OpenAI embedding dimension

    builder.Entity<DocumentChunk>()
        .HasIndex(e => e.Embedding)
        .HasMethod("hnsw") // 👈 Fast approximate search
        .HasOperators("vector_cosine_ops");
}

Performing Vector Search

using Pgvector.EntityFrameworkCore;

public async Task<List<DocumentChunk>> 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<string> 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<string> TranslateToEnglish(string text)
{
    // Translation logic
}

[KernelFunction]
[Description("Search knowledge base (English only)")]
public async Task<string> 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<string> 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<string> 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! 🚀

Announcing Server-Side Rendering Support for ABP Framework Angular Applications

ABP.IO — Thu, 20 Nov 2025 06:46:59 +0000

Announcing Server-Side Rendering (SSR) Support for ABP Framework Angular Applications

We are pleased to announce that Server-Side Rendering (SSR) has become available for ABP Framework Angular applications! This highly requested feature brings major gains in performance, SEO, and user experience to your Angular applications based on ABP Framework.

What is Server-Side Rendering (SSR)?

Server-Side Rendering refers to an approach which renders your Angular application on the server as opposed to the browser. The server creates the complete HTML for a page and sends it to the client, which can then show the page to the user. This poses many advantages over traditional client-side rendering.

Why SSR Matters for ABP Angular Applications

Improved Performance

Quicker visualization of the first contentful paint (FCP): Because prerendered HTML is sent over from the server, users will see content quicker.
Better perceived performance : Even on slower devices, the page will be displaying something sooner.
Less JavaScript parsing time : For example, the initial page load will not require parsing and executing a large bundle of JavaScript.

Enhanced SEO

Improved indexing by search engines : Search engine bots are able to crawl and index your content quicker.
Improved rankings in search : The quicker the content loads and the easier it is to access, the better your SEO score.
Preview when sharing on social channels : Rich previews with the appropriate meta tags are generated when sharing links on social platforms.

Better User Experience

Support for low bandwidth : Users with slower Internet connections will have a better experience
Progressive enhancement : Users can start accessing the content before JavaScript has loaded
Better accessibility : Screen readers and other assistive technologies can access the content immediately

Getting Started with SSR

Adding SSR to an Existing Project

You can easily add SSR support to your existing ABP Angular application using the Angular CLI with ABP schematics:

Adds SSR configuration to your project

ng generate @abp/ng.schematics:ssr-add

Short form

ng g @abp/ng.schematics:ssr-add

If you have multiple projects in your workspace, you can specify which project to add SSR to:

ng g @abp/ng.schematics:ssr-add --project=my-project

If you want to skip the automatic installation of dependencies:

ng g @abp/ng.schematics:ssr-add --skip-install

What Gets Configured

When you add SSR to your ABP Angular project, the schematic automatically:

Installs necessary dependencies : Adds @angular/ssr and related packages
Creates Server Configuration : Creates server.ts and related files
Updates Project Structure :
- Creates main.server.ts to bootstrap the server
- Adds app.config.server.ts for standalone apps (or app.module.server.ts for NgModule apps)
- Configures server routes in app.routes.server.ts
Updates Build Configuration : updates angular.json to include:
- a serve-ssr target for local SSR development
- a prerender target for static site generation
- Proper output paths for browser and server bundles

Supported Configurations

The ABP SSR schematic supports both modern and legacy Angular build configurations:

Application Builder (Suggested)

The new @angular-devkit/build-angular:application builder
Optimized for Angular 17+ apps
Enhanced performance and smaller bundle sizes

Server Builder (Legacy)

The original @angular-devkit/build-angular:server builder
Designed for legacy Angular applications
Compatible with legacy applications

Running Your SSR Application

After adding SSR to your project, you can run your application in SSR mode:

# Development mode with SSR
ng serve

# Or specifically target SSR development server
npm run serve:ssr

# Build for production
npm run build:ssr

# Preview production build
npm run serve:ssr:production

Important Considerations

Browser-Only APIs

Some browser APIs are not available on the server. Use platform checks to conditionally execute code:

import { isPlatformBrowser } from '@angular/common';
import { PLATFORM_ID, inject } from '@angular/core';

export class MyComponent {
  private platformId = inject(PLATFORM_ID);

  ngOnInit() {
    if (isPlatformBrowser(this.platformId)) {
      // Code that uses browser-only APIs
      console.log('Running in browser');
      localStorage.setItem('key', 'value');
    }
  }
}

Storage APIs

localStorage and sessionStorage are not accessible on the server. Consider using:

Cookies for server-accessible data.
The state transfer API for hydration.
ABP's built-in storage abstractions.

Third-Party Libraries

Please ensure that any third-party libraries you use are compatible with SSR. These libraries can require:

Dynamic imports for browser-only code.
Platform-specific service providers.
Custom Angular Universal integration.

ABP Framework Integration

The SSR implementation is natively integrated with all of the ABP Framework features:

Authentication & Authorization : The OAuth/OpenID Connect flow functions seamlessly with ABP
Multi-tenancy : Fully supports tenant resolution and switching
Localization : Server-side rendering respects the locale
Permission Management : Permission checks work on both server and client
Configuration : The ABP configuration system is SSR-ready

Performance Tips

Utilize State Transfer : Send data from server to client to eliminate redundant HTTP requests
Optimize Images : Proper image loading strategies, such as lazy loading and responsive images.
Cache API Responses : At the server, implement proper caching strategies.
Monitor Bundle Size : Keep your server bundle optimized
Use Prerendering : The prerender target should be used for static content.

Conclusion

Server-side rendering can be a very effective feature in improving your ABP Angular application's performance, SEO, and user experience. Our new SSR schematic will make it easier than ever to add SSR to your project.

Try it today and let us know what you think!

ABP.IO Platform 10.0 Final Has Been Released!

ABP.IO — Wed, 19 Nov 2025 10:56:04 +0000

ABP.IO Platform 10.0 Final Has Been Released!

We are glad to announce that ABP 10.0 stable version has been released today.

What's New With Version 10.0?

All the new features were explained in detail in the 10.0 RC Announcement Post, so there is no need to review them again. You can check it out for more details.

Getting Started with 10.0

How to Upgrade an Existing Solution

You can upgrade your existing solutions with either ABP Studio or ABP CLI. In the following sections, both approaches are explained:

Upgrading via ABP Studio

If you are already using the ABP Studio, you can upgrade it to the latest version. ABP Studio periodically checks for updates in the background, and when a new version of ABP Studio is available, you will be notified through a modal. Then, you can update it by confirming the opened modal. See the documentation for more info.

After upgrading the ABP Studio, then you can open your solution in the application, and simply click the Upgrade ABP Packages action button to instantly upgrade your solution:

Upgrading via ABP CLI

Alternatively, you can upgrade your existing solution via ABP CLI. First, you need to install the ABP CLI or upgrade it to the latest version.

If you haven't installed it yet, you can run the following command:

dotnet tool install -g Volo.Abp.Studio.Cli

Or to update the existing CLI, you can run the following command:

dotnet tool update -g Volo.Abp.Studio.Cli

After installing/updating the ABP CLI, you can use the update command to update all the ABP related NuGet and NPM packages in your solution as follows:

abp update

You can run this command in the root folder of your solution to update all ABP related packages.

Migration Guides

There are a few breaking changes in this version that may affect your application. Please read the migration guide carefully, if you are upgrading from v9.x: ABP Version 10.0 Migration Guide

Community News

New ABP Community Articles

As always, exciting articles have been contributed by the ABP community. I will highlight some of them here:

Thanks to the ABP Community for all the content they have published. You can also post your ABP related (text or video) content to the ABP Community.

About the Next Version

The next feature version will be 10.1. You can follow the release planning here. Please submit an issue if you have any problems with this version.

Signal-Based Forms in Angular 21: Why You’ll Never Miss Reactive Forms Again

ABP.IO — Tue, 18 Nov 2025 08:32:44 +0000

Signal-Based Forms in Angular 21: Why You’ll Never Miss Reactive Forms Again

Angular 21 introduces one of the most exciting developments in the modern edition of Angular: Signal-Based Forms. Built directly on the reactive foundation of Angular signals, this new experimental API provides a cleaner, more intuitive, strongly typed, and ergonomic approach for managing form state—without the heavy boilerplate of Reactive Forms.

⚠️ Important: Signal Forms are experimental. Their API can change. Avoid using them in critical production scenarios unless you understand the risks.

Despite this, Signal Forms clearly represent Angular’s future direction.

Why Signal Forms?

Traditionally in Angular, building forms has involved several concerns:

Tracking values
Managing UI interaction states (touched, dirty)
Handling validation
Keeping UI and model in sync

Reactive Forms solved many challenges but introduced their own:

Verbosity FormBuilder API
Required subscriptions (valueChanges)
Manual cleaning
Difficult nested forms
Weak type-safety

Signal Forms solve these problems through:

1." Automatic synchronization

2." Full type safety

3." Schema-based validation

4." Fine-grained reactivity

5." Drastically reduced boilerplate

6." Natural integration with Angular Signals

1. Form Models — The Core of Signal Forms

A form model is simply a writable signal holding the structure of your form data.

import { Component, signal } from '@angular/core';
import { form, Field } from '@angular/forms/signals';

@Component({
  selector: 'app-login',
  imports: [Field],
  template: `
    <input type="email" [field]="loginForm.email" />
    <input type="password" [field]="loginForm.password" />
  `,
})
export class LoginComponent {
  loginModel = signal({
    email: '',
    password: '',
  });

  loginForm = form(this.loginModel);
}

Calling form(model) creates a Field Tree that maps directly to your model.

2. Achieving Full Type Safety

Although TypeScript can infer types from object literals, defining explicit interfaces provides maximum safety and better IDE support.

interface LoginData {
  email: string;
  password: string;
}

loginModel = signal<LoginData>({
  email: '',
  password: '',
});

loginForm = form(loginModel);

Now:

loginForm.email → FieldTree<string>
Accessing invalid fields like loginForm.username results in compile-time errors

This level of type safety surpasses Reactive Forms.

3. Reading Form Values

Read from the model (entire form):

onSubmit() {
  const data = this.loginModel();
  console.log(data.email, data.password);
}

Read from an individual field:

<p>Current email: {{ loginForm.email().value() }}</p>

Each field exposes:

value()
valid()
errors()
dirty()
touched()

All as signals.

4. Updating Form Models Programmatically

Signal Forms allow three update methods.

1. Replace the entire model

this.userModel.set({
  name: 'Alice',
  email: 'alice@example.com',
});

2. Patch specific fields

this.userModel.update(prev => ({
  ...prev,
  email: newEmail,
}));

3. Update a single field

this.userForm.email().value.set('');

This eliminates the need for:

patchValue()
setValue()
formGroup.get('field')

5. Automatic Two-Way Binding With `[field]`

The [field] directive enables perfect two-way data binding:

<input [field]="userForm.name" />

How it works:

User input → Field state → Model
Model updates → Field state → Input UI

No subscriptions.

No event handlers.

No boilerplate.

Reactive Forms could never achieve this cleanly.

6. Nested Models and Arrays

Models can contain nested object structures:

userModel = signal({
  name: '',
  address: {
    street: '',
    city: '',
  },
});

Access fields easily:

<input [field]="userForm.address.street" />

Arrays are also supported:

orderModel = signal({
  items: [
    { product: '', quantity: 1, price: 0 }
  ]
});

Field state persists even when array items move, thanks to identity tracking.

7. Schema-Based Validation

Validation is clean and centralized:

import { required, email } from '@angular/forms/signals';

const model = signal({ email: '' });

const formRef = form(model, {
  email: [required(), email()],
});

Field validation state is reactive:

formRef.email().valid()
formRef.email().errors()
formRef.email().touched()

Validation no longer scatters across components.

8. When Should You Use Signal Forms?

New Angular 21+ apps

Signal-first architecture is the new standard.

Teams wanting stronger type safety

Every field is exactly typed.

Devs tired of Reactive Form boilerplate

Signal Forms drastically simplify code.

Complex UI with computed reactive form state

Signals integrate perfectly.

❌ Avoid if:

You need long-term stability
You rely on mature Reactive Forms features
Your app must avoid experimental APIs

9. Reactive Forms vs Signal Forms

| Feature | Reactive Forms | Signal Forms | |--------|----------------|--------------| | Boilerplate | High | Very low | | Type-safety | Weak | Strong | | Two-way binding | Manual | Automatic | | Validation | Scattered | Centralized schema | | Nested forms | Verbose | Natural | | Subscriptions | Required | None | | Change detection | Zone-heavy | Fine-grained |

Signal Forms feel like the "modern Angular mode," while Reactive Forms increasingly feel legacy.

10. Full Example: Login Form

@Component({
  selector: 'app-login',
  imports: [Field],
  template: `
    <form (ngSubmit)="submit()">
      <input type="email" [field]="form.email" />
      <input type="password" [field]="form.password" />
      <button>Login</button>
    </form>
  `,
})
export class LoginComponent {
  model = signal({ email: '', password: '' });
  form = form(this.model);

  submit() {
    console.log(this.model());
  }
}

Minimal. Reactive. Completely type-safe.

Conclusion

Signal Forms in Angular 21 represent a big step forward:

Cleaner API
Stronger type safety
Automatic two-way binding
Centralized validation
Fine-grained reactivity
Dramatically better developer experience

Although these are experimental, they clearly show the future of Angular's form ecosystem. Once you get into using Signal Forms, you may never want to use Reactive Forms again.

Building an API Key Management System with ABP Framework

ABP.IO — Mon, 17 Nov 2025 10:45:38 +0000

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<Guid>, 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<Claim>
{
    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<AbpDistributedCacheOptions>(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

ABP.IO — Mon, 10 Nov 2025 06:37:51 +0000

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<Guid>
{
    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<Account, Guid> _accountRepository;
    private readonly MoneyTransferManager _moneyTransferManager;

    public BankAppService(
        IRepository<Account, Guid> 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<Account, Guid> _accountRepository;

    public MoneyTransferManager(IRepository<Account, Guid> 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<Guid>
{
    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<bool> 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<MoneyTransferredEvent>,
    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<BusinessException>(() => 
            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<BusinessException>(() => 
            manager.Transfer(fromAccount, toAccount, 0m));
        Should.Throw<BusinessException>(() => 
            manager.Transfer(fromAccount, toAccount, -5m));
    }

    [Fact]
    public void Should_Throw_When_Same_Account()
    {
        var account = new Account(100m);
        var manager = new MoneyTransferManager();

        Should.Throw<BusinessException>(() => 
            manager.Transfer(account, account, 10m));
    }
}

Integration Testing with ABP Test Infrastructure

public class MoneyTransferManager_IntegrationTests : BankingDomainTestBase
{
    private readonly MoneyTransferManager _transferManager;
    private readonly IRepository<Account, Guid> _accountRepository;

    public MoneyTransferManager_IntegrationTests()
    {
        _transferManager = GetRequiredService<MoneyTransferManager>();
        _accountRepository = GetRequiredService<IRepository<Account, Guid>>();
    }

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

UI & UX Trends That Will Shape 2026

ABP.IO — Wed, 05 Nov 2025 14:56:43 +0000

UI & UX Trends That Will Shape 2026

Cinematic, gamified, high-wow-factor websites with scroll-to-play videos or scroll-to-tell stories are wonderful to experience, but you won't find these trends in this article. If you're interested in design trends directly related to the software world, such as performance , accessibility , understandability , and efficiency , grab a cup of coffee and enjoy.

As we approach the end of 2025, I'd like to share with you the most important user interface and user experience design trends that have become more of a toolkit than a trend, and that continue to evolve and become a part of our lives. I predict we'll see a lot of them in 2026.

1. Simplicity and Speed

Designing understandable and readable applications is becoming far more important than designing in line with trends and fashion. In the software and business world, preferences are shifting more and more toward the right design over the cool design. As designers developing a product whose direct target audience is software developers, we design our products for the designers' enjoyment, but for the end user's ease of use.

Users no longer care so much about the flashiness of a website. True converts are primarily interested in your product, service, or content. What truly matters to them is how easily and quickly they can access the information they're looking for.

More users, more sales, better promotion, and a higher conversion rate... The elements that serve these goals are optimized solutions and thoughtful details in our designs, more than visual displays.

If the "loading" icon appears too often on your digital product, you might not be doing it right. If you fail to optimize speed, the temporary effect of visual displays won't be enough to convert potential users into customers. Remember, the moment people start waiting, you've lost at least half of them.

2. Dark Mode - Still, and Forever

Dark Mode is no longer an option; it's a standard. It's become a necessity, not a choice, especially for users who spend hours staring at screens and are accustomed to dark themes in code editors and terminals. However, the approach to dark mode isn't simply about inverting colors; it's much deeper than that. The key is managing contrast and depth.

The layer hierarchy established in a light-colored design doesn't lose its impact when switched to dark mode. The colors, shadows, highlights, and contrasting elements used to create an easily perceivable hierarchy should be carefully considered for each mode. Our LeptonX theme's Light, Dark, Semi-dark, and System modes offer valuable insights you might want to explore.

You might also want to take a look at the dark and light modes we designed with these elements in mind in ABP Studio and the ABP.io Documents page.

3. Bento Grid - A Timeless Trend

People don't read your website; they scan it.

Bento Grid, an indispensable trend for designers looking to manage their attention, looks set to remain a staple in 2026, just as it was in 2025. No designer should ignore the fact that many tech giants, especially Apple and Samsung, are still using bento grids on their websites. The bento grid appears not only on websites but also in operating systems, VR headset interfaces, game console interfaces, and game designs.

The golden rule is contrast and balance.

The attractiveness and effectiveness of bento designs depend on certain factors you should consider when implementing them. If you ignore these rules, even with a proven method like bento, you can still alienate users.

The bento grid is one of the best ways to display different types of content inclusively. When used correctly, it's also a great way to manipulate reading order, guiding the user's eye. Improper contrast and hierarchy can also create a negative experience. Designers should use this to guide the reader's eye: "Read here first, then read here."

When creating a bento, you inherently have to sacrifice some of your "whitespace." This design has many elements for the user to focus on, and it actually strays from our first point, "Simplicity". Bento design, whose boundaries are drawn from the outset and independent of content, requires care not to include more or less than what is necessary. Too much content makes it boring; too little content makes it very close to meaningless.

Bento grids should aim for a balanced design by using both simple text and sophisticated visuals. This visual can be an illustration, a video that starts playing when hovered over, a static image, or a large title. Only one or two cards on the screen at a time should have attention.

4. Larger Fonts, High Readability

Large fonts have been a trend for several years, and it seems web designers are becoming more and more bold. The increasing preference for larger fonts every year is a sign that this trend will continue into 2026. This trend is about more than just using large font sizes in headlines.

Creating a cohesive typographic scale and proper line height and letter spacing are critical elements to consider when creating this trend. As the font size increases, line height should decrease, and the space between letters should be narrower.

The browser default font size, which we used to see in body text and paragraphs and has now become standard, is 16 pixels. In the last few years, we've started seeing body font sizes of 17 or 18 pixels more frequently. The increasing importance of readability every year makes this more common. Font sizes in rem values, rather than px, provide the most efficient results.

5. Micro Animations

Unless you're a web design agency designing a website to impress potential clients, you should avoid excessive changes, including excessive image changes during scrolling, and scroll direction changes. There's still room for oversized images and scroll animations. But be sure to create the visuals yourself.

The trend I'm talking about here is micro animations , not macro ones. Small movements, not large ones.

The animation approach of 2025 is functional and performance-sensitive.

Microanimations exist to provide immediate feedback to the user. Instant feedback, like a button's shadow increasing when hovered over, a button's slight collapse when clicked, or a "Save" icon changing to a "Confirm" icon when saving data, keeps your designs alive.

We see the real impact of the micro-animation trend in static, non-action visuals. The use of non-button elements in your designs, accentuated by micro-movements such as scrolling or hovering, seems poised to continue to create macro effects in 2026.

6. Real Images and Human-like Touches

People quickly spot a fake. It's very difficult to convince a user who visits your website for the first time and doesn't trust you. First impressions matter.

Real photographs, actual product screenshots, and brand-specific illustrations will continue to be among the elements we want to see in trust-focused designs in 2026.

In addition to flawless work done by AI, vivid, real-life visuals, accompanied by deliberate imperfections, hand-drawn details, or designed products that convey the message, "A human made this site!", will continue to feel warmer and more welcoming.

The human touch is evident not only in the visuals but also in your content and text.

In 2026, you'll need more human-like touches that will make your design stand out among the thousands of similar websites rapidly generated by AI.

7. Accessibility - No Longer an Option, But a Legal and Ethical Obligation

Accessibility, once considered a nice-to-do thing in recent years, is now becoming a necessity in 2026 and beyond. Global regulations like the European Accessibility Act require all digital products to comply with WCAG standards.

All design and software improvements you make to ensure end users can fully perform their tasks in your products, regardless of their temporary or permanent disabilities, should be viewed as ethical and commercial requirements, not as a requirement to comply with these standards.

The foundation of accessibility in design is to use semantic HTML for screen readers, provide full keyboard control of all interactive elements, and clearly communicate the roles of complex components to the development team.

8. Intentional Friction

Steve Krug, the father of UX design, started the trend of designing everything at a hyper-usable level with his book "Don't Make Me Think." As web designers, we've embraced this idea so much that all we care about is getting the user to their destination in the shortest possible scenario and as quickly as possible. This has required so many understandability measures that, after a while, it's starting to feel like fooling the user.

In recent years, designers have started looking for ways to make things a little more challenging, rather than just getting the user to the result.

When the end user visits your website, tries to understand exactly what it is at first glance, struggles a bit, and, after a little effort, becomes familiar with how your world works, they'll be more inclined to consider themselves a part of it.

This has nothing to do with anti-usability. This philosophy is called Intentional Friction.

This isn't a flaw; it's the pinnacle of error prevention. It's a step to prevent errors from occurring on autopilot and respects the user's ability to understand complex systems. Examples include reviewing the order summary or manually typing the project name when deleting a project on GitHub.

Bonus: Where Does Artificial Intelligence Fit In?

Artificial intelligence will be an infrastructure in 2026, not a trend.

As designers, we should leverage AI not to paint us a picture, but to make workflows more intelligent. In my opinion, this is the best use case for AI.

AI can learn user behavior and adapt the interface accordingly. Real-time A/B testing can save us time by conducting a real-time content review. The ability to actively use AI in any area that allows you to accelerate your progress will take you a step further in your career.

Since your users are always human, don't be too eager to incorporate AI-generated visuals into your design. Unless you're creating and selling a ready-made theme, you should avoid AI-generated visuals, random bento grids, and randomly generated content.

You should definitely incorporate AI into your work for new content, new ideas, personal and professional development, and insights that will take your design a step further. But just as you don't design your website for designers to like, the same applies to AI. Humans, not robots, will experience your website. AI-assisted , not AI-generated, designs with a human touch are the trend I most expect seeing in 2026.

Conclusion

In the end, it's all fundamentally about respect for the user and their time. In 2026, our success as designers and developers will be measured not by how "cool" we are, but by how "efficient" and "reliable" a world we build for our users.

Thank you for your time.

Repository Pattern in ASP.NET Core

ABP.IO — Sun, 02 Nov 2025 07:48:14 +0000

Repository Pattern in the ASP.NET Core

If you’ve built a .NET app with a database, you’ve likely used Entity Framework, Dapper, or ADO.NET. They’re useful tools; still, when they live inside your business logic or controllers, the code can become harder to keep tidy and to test.

That’s where the Repository Pattern comes in.

At its core, the Repository Pattern acts as a middle layer between your domain and data access logic. It abstracts the way you store and retrieve data, giving your application a clean separation of concerns:

Separation of Concerns: Business logic doesn’t depend on the database.
Easier Testing: You can replace the repository with a fake or mock during unit tests.
Flexibility: You can switch data sources (e.g., from SQL to MongoDB) without touching business logic.

Let’s see how this works with a simple example.

A Simple Example with Product Repository

Imagine we’re building a small e-commerce app. We’ll start by defining a repository interface for managing products.

You can find the complete sample code in this GitHub repository:

https://github.com/m-aliozkaya/RepositoryPattern

Domain model and context

We start with a single entity and a matching DbContext.

Product.cs

using System.ComponentModel.DataAnnotations;

namespace RepositoryPattern.Web.Models;

public class Product
{
    public int Id { get; set; }

    [Required, StringLength(64)]
    public string Name { get; set; } = string.Empty;

    [Range(0, double.MaxValue)]
    public decimal Price { get; set; }

    [StringLength(256)]
    public string? Description { get; set; }

    public int Stock { get; set; }
}

"AppDbContext.cs

using Microsoft.EntityFrameworkCore;
using RepositoryPattern.Web.Models;

namespace RepositoryPattern.Web.Data;

public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();
}

Generic repository contract and base class

All entities share the same CRUD needs, so we define a generic interface and an EF Core implementation.

Repositories/IRepository.cs

using System.Linq.Expressions;

namespace RepositoryPattern.Web.Repositories;

public interface IRepository<TEntity> where TEntity : class
{
    Task<TEntity?> GetByIdAsync(int id, CancellationToken cancellationToken = default);
    Task<List<TEntity>> GetAllAsync(CancellationToken cancellationToken = default);
    Task<List<TEntity>> GetListAsync(Expression<Func<TEntity, bool>> predicate, CancellationToken cancellationToken = default);
    Task AddAsync(TEntity entity, CancellationToken cancellationToken = default);
    Task UpdateAsync(TEntity entity, CancellationToken cancellationToken = default);
    Task DeleteAsync(int id, CancellationToken cancellationToken = default);
}

Repositories/EfRepository.cs

using Microsoft.EntityFrameworkCore;
using RepositoryPattern.Web.Data;

namespace RepositoryPattern.Web.Repositories;

public class EfRepository<TEntity>(AppDbContext context) : IRepository<TEntity>
    where TEntity : class
{
    protected readonly AppDbContext Context = context;

    public virtual async Task<TEntity?> GetByIdAsync(int id, CancellationToken cancellationToken = default)
        => await Context.Set<TEntity>().FindAsync([id], cancellationToken);

    public virtual async Task<List<TEntity>> GetAllAsync(CancellationToken cancellationToken = default)
        => await Context.Set<TEntity>().AsNoTracking().ToListAsync(cancellationToken);

    public virtual async Task<List<TEntity>> GetListAsync(
        System.Linq.Expressions.Expression<Func<TEntity, bool>> predicate,
        CancellationToken cancellationToken = default)
        => await Context.Set<TEntity>()
            .AsNoTracking()
            .Where(predicate)
            .ToListAsync(cancellationToken);

    public virtual async Task AddAsync(TEntity entity, CancellationToken cancellationToken = default)
    {
        await Context.Set<TEntity>().AddAsync(entity, cancellationToken);
        await Context.SaveChangesAsync(cancellationToken);
    }

    public virtual async Task UpdateAsync(TEntity entity, CancellationToken cancellationToken = default)
    {
        Context.Set<TEntity>().Update(entity);
        await Context.SaveChangesAsync(cancellationToken);
    }

    public virtual async Task DeleteAsync(int id, CancellationToken cancellationToken = default)
    {
        var entity = await GetByIdAsync(id, cancellationToken);
        if (entity is null)
        {
            return;
        }

        Context.Set<TEntity>().Remove(entity);
        await Context.SaveChangesAsync(cancellationToken);
    }
}

Reads use AsNoTracking() to avoid tracking overhead, while write methods call SaveChangesAsync to keep the sample straightforward.

Product-specific repository

Products need one extra query: list the items that are almost out of stock. We extend the generic repository with a dedicated interface and implementation.

Repositories/IProductRepository.cs

using RepositoryPattern.Web.Models;

namespace RepositoryPattern.Web.Repositories;

public interface IProductRepository : IRepository<Product>
{
    Task<List<Product>> GetLowStockProductsAsync(int threshold, CancellationToken cancellationToken = default);
}

Repositories/ProductRepository.cs

using Microsoft.EntityFrameworkCore;
using RepositoryPattern.Web.Data;
using RepositoryPattern.Web.Models;

namespace RepositoryPattern.Web.Repositories;

public class ProductRepository(AppDbContext context) : EfRepository<Product>(context), IProductRepository
{
    public Task<List<Product>> GetLowStockProductsAsync(int threshold, CancellationToken cancellationToken = default) =>
        Context.Products
            .AsNoTracking()
            .Where(product => product.Stock <= threshold)
            .OrderBy(product => product.Stock)
            .ToListAsync(cancellationToken);
}

🧩 A Note on Unit of Work

The Repository Pattern is often used together with the Unit of Work pattern to manage transactions efficiently.

💡 *If you want to dive deeper into the Unit of Work pattern, check out our separate blog post dedicated to that topic. https://abp.io/community/articles/lv4v2tyf

Service layer and controller

Controllers depend on a service, and the service depends on the repository. That keeps HTTP logic and data logic separate.

Services/ProductService.cs

using RepositoryPattern.Web.Models;
using RepositoryPattern.Web.Repositories;

namespace RepositoryPattern.Web.Services;

public class ProductService(IProductRepository productRepository)
{
    private readonly IProductRepository _productRepository = productRepository;

    public Task<List<Product>> GetProductsAsync(CancellationToken cancellationToken = default) =>
        _productRepository.GetAllAsync(cancellationToken);

    public Task<List<Product>> GetLowStockAsync(int threshold, CancellationToken cancellationToken = default) =>
        _productRepository.GetLowStockProductsAsync(threshold, cancellationToken);

    public Task<Product?> GetByIdAsync(int id, CancellationToken cancellationToken = default) =>
        _productRepository.GetByIdAsync(id, cancellationToken);

    public Task CreateAsync(Product product, CancellationToken cancellationToken = default) =>
        _productRepository.AddAsync(product, cancellationToken);

    public Task UpdateAsync(Product product, CancellationToken cancellationToken = default) =>
        _productRepository.UpdateAsync(product, cancellationToken);

    public Task DeleteAsync(int id, CancellationToken cancellationToken = default) =>
        _productRepository.DeleteAsync(id, cancellationToken);
}

Controllers/ProductsController.cs

using Microsoft.AspNetCore.Mvc;
using RepositoryPattern.Web.Models;
using RepositoryPattern.Web.Services;

namespace RepositoryPattern.Web.Controllers;

public class ProductsController(ProductService productService) : Controller
{
    private readonly ProductService _productService = productService;

    public async Task<IActionResult> Index(CancellationToken cancellationToken)
    {
        const int lowStockThreshold = 5;
        var products = await _productService.GetProductsAsync(cancellationToken);
        var lowStock = await _productService.GetLowStockAsync(lowStockThreshold, cancellationToken);

        return View(new ProductListViewModel(products, lowStock, lowStockThreshold));
    }

    // remaining CRUD actions call through ProductService in the same way
}

The controller never reaches for AppDbContext. Every operation travels through the service, which keeps tests simple and makes future refactors easier.

Dependency registration and seeding

The last step is wiring everything up in Program.cs.

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseInMemoryDatabase("ProductsDb"));
builder.Services.AddScoped(typeof(IRepository<>), typeof(EfRepository<>));
builder.Services.AddScoped<IProductRepository, ProductRepository>();
builder.Services.AddScoped<ProductService>();

The sample also seeds three products so the list page shows data on first run.

Run the site with:

dotnet run --project RepositoryPattern.Web

How ABP approaches the same idea

ABP includes generic repositories by default (IRepository<TEntity, TKey>), so you often skip writing the implementation layer shown above. You inject the interface into an application service, call methods like InsertAsync or CountAsync, and ABP’s Unit of Work handles the transaction. When you need custom queries, you can still derive from EfCoreRepository<TEntity, TKey> and add them.

For more details, check out the official ABP documentation on repositories: https://abp.io/docs/latest/framework/architecture/domain-driven-design/repositories

Closing note

This setup keeps data access tidy without being heavy. Start with the generic repository, add small extensions per entity, pass everything through services, and register the dependencies once. Whether you hand-code it or let ABP supply the repository, the structure stays the same and your controllers remain clean.

Return Code vs Exceptions: Which One is Better?

ABP.IO — Fri, 31 Oct 2025 12:40:39 +0000

Return Code vs Exceptions: Which One is Better?

Alright, so this debate pops up every few months on dev subreddits and forums

Should you use return codes or exceptions for error handling?

And honestly, there’s no %100 right answer here! Both have pros/cons, and depending on the language or context, one might make more sense than the other. Let’s see...

1. Return Codes --- Said to be "Old School Way" ---

Return codes (like 0 for success, -1 for failure, etc.) are the OG method. You mostly see them everywhere in C and C++. They’re super explicit, the function literally returns the result of the operation.

➕ Advantages of returning codes:

You always know when something went wrong
No hidden control flow — what you see is what you get
Usually faster (no stack unwinding, no exception overhead)
Easy to use in systems programming, embedded stuff, or performance-critical code

➖ Disadvantages of returning codes:

It’s easy to forget to check the return value (and boom, silent failure 😬)
Makes code noisy... Everry function call followed by if (result != SUCCESS) gets annoying
No stack trace or context unless you manually build one

For example:

try
{
    await SendEmailAsync();
}
catch (Exception e)
{
    Log.Exception(e.ToString());
    return -1;
}

Looks fine… until you forget one of those if conditions somewhere.

2. Exceptions --- The Fancy & Modern Way ---

Exceptions came in later, mostly with higher-level languages like Java, C#, and Python. The idea is that you throw an error and handle it somewhere else.

➕ Advantages of throwing exceptions:

Cleaner code... You can focus on the happy path and handle errors separately
Can carry detailed info (stack traces, messages, inner exceptions...)
Easier to handle complex error propagation

➖ Disadvantages of throwing exceptions:

Hidden control flow — you don’t always see what might throw
Performance hit (esp. in tight loops or low-level systems)
Overused in some codebases (“everything throws everything”)

Example:

try
{
    await SendEmailAsync();
}
catch (Exception e)
{
    Log.Exception(e.ToString());
    throw e;
}

Way cleaner, but if SendEmailAsync() is deep in your call stack and it fails, it can be tricky to know exactly what went wrong unless you log properly.

And Which One’s Better? ⚖️

Depends on what you’re building.

Low-level systems, drivers, real-time stuff 👉 Return codes. Performance and control matter more.
Application-level, business logic, or high-level APIs 👉 Exceptions. Cleaner and easier to maintain.

And honestly, mixing both sometimes makes sense. For example, you can use return codes internally and exceptions at the boundary of your API to surface meaningful errors to the user.

Conclusion

Return codes = simple, explicit, but messy.t Exceptions = clean, powerful, but can bite you. Use what fits your project and your team’s sanity level 😅.

5 Things You Should Keep in Mind When Deploying to a Clustered Environment

ABP.IO — Thu, 30 Oct 2025 07:38:37 +0000

5 Things You Should Keep in Mind When Deploying to a Clustered Environment

Let’s be honest — moving from a single server to a cluster sounds simple on paper.

You just add a few more machines, right?

In practice, it’s the moment when small architectural mistakes start to grow legs.

Below are a few things that experienced engineers usually double-check before pressing that “Deploy” button.

1️⃣ Managing State the Right Way

Each request in a cluster might hit a different machine.

If your application keeps user sessions or cache in memory, that data probably won’t exist on the next node.

That’s why many teams decide to push state out of the app itself.

A few real-world tips:

Keep sessions in Redis or something similar instead of local memory.
Design endpoints so they don’t rely on earlier requests.
Don’t assume the same server will handle two requests in a row — it rarely does.

2️⃣ Shared Files and Where to Put Them

Uploading files to local disk? That’s going to hurt in a cluster.

Other nodes can’t reach those files, and you’ll spend hours wondering why images disappear.

Better habits:

Push uploads to S3 , Azure Blob , or Google Cloud Storage.
Send logs to a shared location instead of writing to local files.
Keep environment configs in a central place so each node starts with the same settings.

3️⃣ Database Connections Aren’t Free

Every node opens its own database connections.

Ten nodes with twenty connections each — that’s already two hundred open sessions.

The database might not love that.

What helps:

Put a cap on your connection pools.
Avoid keeping transactions open for too long.
Tune indexes and queries before scaling horizontally.

4️⃣ Logging and Observability Matter More Than You Think

When something breaks in a distributed system, it’s never obvious which server was responsible.

That’s why observability isn’t optional anymore.

Consider this:

Stream logs to ELK , Datadog , or Grafana Loki.
Add a trace ID to every incoming request and propagate it across services.
Watch key metrics with Prometheus and visualize them in Grafana dashboards.

5️⃣ Background Jobs and Message Queues

If more than one node runs the same job, you might process the same data twice — or delete something by mistake.

You don’t want that kind of excitement in production.

A few precautions:

Use a distributed lock or leader election system.
Make jobs idempotent , so running them twice doesn’t break data.
Centralize queue consumers or use a proper task scheduler.

Wrapping Up

Deploying to a cluster isn’t only about scaling up — it’s about staying stable when you do.

Systems that handle state, logging, and background work correctly tend to age gracefully.

Everything else eventually learns the hard way.

A cluster doesn’t fix design flaws — it magnifies them.

Optimize Your .NET App for Production - Complete Checklist (Part 2)

ABP.IO — Wed, 22 Oct 2025 07:19:10 +0000

If you’ve landed directly on this article, note that it’s part-2 of the series. You can read part-1 here: Optimize Your .NET App for Production (Part 1)

6) Telemetry (Logs, Metrics, Traces)

The below code adds OpenTelemetry to collect app logs, metrics, and traces in .NET.

builder.Services.AddOpenTelemetry()
  .UseOtlpExporter()
  .WithMetrics(m => m.AddAspNetCoreInstrumentation().AddHttpClientInstrumentation())
  .WithTracing(t => t.AddAspNetCoreInstrumentation().AddHttpClientInstrumentation());

UseOtlpExporter() Tells it where to send telemetry. Usually that’s an OTLP collector (like Grafana , Jaeger, Tempo, Azure Monitor). So you can visualize metrics and traces in dashboards.
WithMetrics() means it'll collects metrics. These metrics are Request rate (RPS), Request duration (latency), GC pauses, Exceptions, HTTP client timings.
.WithTracing(...) means it'll collect distributed traces. That's useful when your app calls other APIs or microservices. You can see the full request path from one service to another with timings and bottlenecks.

.NET Diagnostic Tools

When your app is on-air, you should know about the below tools. You know in airplanes there's black box recorder which is used to understand why the airplane crashed. For .NET below are our black box recorders. They capture what happened without attaching a debugger.

| Tool | What It Does | When to Use | | --------------------- | --------------------------------------- | ---------------------------- | | dotnet-counters | Live metrics like CPU, GC, request rate | Monitor running apps | | dotnet-trace | CPU sampling & performance traces | Find slow code | | dotnet-gcdump | GC heap dumps (allocations) | Diagnose memory issues | | dotnet-dump | Full process dumps | Investigate crashes or hangs | | dotnet-monitor | HTTP service exposing all the above | Collect telemetry via API |

7) Build & Run .NET App in Docker the Right Way

A multi-stage build is a Docker technique where you use one image for building your app and another smaller image for running it. Why we do multi-stage build, because the .NET SDK image is big but has all the build tools. The .NET Runtime image is small and optimized for production. You copy only the published output from the build stage into the runtime stage.

# build
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY . .
RUN dotnet restore
RUN dotnet publish -c Release -o /app/out -p:PublishTrimmed=true -p:PublishSingleFile=true -p:ReadyToRun=true

# run
FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080
COPY --from=build /app/out .
ENTRYPOINT ["./YourApp"] # or ["dotnet","YourApp.dll"]

I'll explain what these Docker file commands;

Stage1: Build

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS buildUses the .NET SDK image including compilers and tools. The AS build name lets you reference this stage later.
WORKDIR /srcSets the working directory inside the container.
COPY . .Copies your source code into the container.
RUN dotnet restoreRestores NuGet packages.
RUN dotnet publish ...Builds the project in Release mode, optimizes it for production, and outputs it to /app/out. The flags;

Stage 2: Run

FROM mcr.microsoft.com/dotnet/aspnet:9.0Uses a lighter runtime image which no compiler, just the runtime.
WORKDIR /appWhere your app will live inside the container.
ENV ASPNETCORE_URLS=http://+:8080Makes the app listen on port 8080 (and all network interfaces).
EXPOSE 8080Documents the port your container uses (for Docker/K8s networking).
COPY --from=build /app/out .Copies the published output from the build stage to this final image.
ENTRYPOINT ["./YourApp"]Defines the command that runs when the container starts. If you published as a single file, it’s ./YourApp. f not, use dotnet YourApp.dll.

8) Security

HTTPS Everywhere Even Behind Proxy

Even if your app runs behind a reverse proxy like Nginx, Cloudflare or a load balancer, always enforce HTTPS. Why? Because internal traffic can still be captured if you don't use SSL and also cookies, HSTS, browser APIs require HTTPS. In .NET, you can easily enforce HTTPS like this:

app.UseHttpsRedirection();

Use HSTS in Production

HSTS (HTTP Strict Transport Security) tells browsers:

Always use HTTPS for this domain — don’t even try HTTP again!

Once you set, browsers cache this rule, so users can’t accidentally hit the insecure version. You can easily enforce this as below:

if (!app.Environment.IsDevelopment())
{
    app.UseHsts();
}

When you use HSTS, it sends browser this HTTP header: Strict-Transport-Security: max-age=31536000; includeSubDomains. Browser will remember this setting for 1 year (31,536,000 seconds) that this site must only use HTTPS. And includeSubDomains option applies the rule to all subdomains as well (eg: api.abp.io, cdn.abp.io, account.abp.io etc..)

Store Secrets on Environment Variables or Secret Stores

Never store passwords, connection strings, or API keys in your code or Git. Then where should we keep them?

Best/practical way is Environment variables. You can easily sett an environment variable in a Unix-like system as below:
And you can easily access these environment variables from your .NET app like this:

Or Secret stores like: Azure Key Vault, AWS Secrets Manager, HashiCorp Vault

Add Rate-Limiting to Public Endpoints

Don't forget there'll be not naive guys who will use your app! We've many times faced this issue in the past on our public front-facing websites. So protect your public APIs from abuse, bots, and DDoS. Use rate-limiting!!! Stop brute-force attacks, prevent your resources from exhaustion...

In .NET, there's a built-in rate-limit feature for .NET (System.Threading.RateLimiting):

builder.Services.AddRateLimiter(_ => _
    .AddFixedWindowLimiter("default", options =>
    {
        options.PermitLimit = 100;
        options.Window = TimeSpan.FromMinutes(1);
    }));

app.UseRateLimiter();

Also there's an open-source rate-limiting library -> github.com/stefanprodan/AspNetCoreRateLimit
Another one -> nuget.org/packages/Polly.RateLimiting

Secure Cookies

Cookies are often good targets for attacks. You must secure them properly otherwise you can face cookie stealing or CSRF attack.

options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
options.Cookie.SameSite = SameSiteMode.Strict; // or Lax

SecurePolicy = Always -> only send cookies over HTTPS
SameSite=Lax/Strict -> prevent CSRF (Cross-Site Request Forgery)
- Strict = safest
- Lax = good balance for login sessions

9) Startup/Cold Start

Keep Tiered JIT On

The JIT (Just-In-Time) compiler converts your app’s Intermediate Language (IL) into native CPU instructions when the code runs. Tiered JIT means the runtime uses 2 stages of compilation. Actually this setting is enabled by default in modern .NET. So just keep it on.

Tier 0 (Quick JIT):Fast, low-optimization compile → gets your app running ASAP. (Used at startup.)
Tier 1 (Optimized JIT):Later, the runtime re-compiles hot methods (frequently used ones) with deeper optimizations for speed.

Use PGO (Profile-Guided Optimization)

PGO lets .NET learn from real usage of your app. It profiles which functions are used most often, then re-optimizes the build for that pattern. You can think of it as the runtime saying:

I’ve seen what your app actually does... I’ll rearrange and optimize code paths accordingly.

In .NET 8+, you don’t have to manually enable PGO (Profile-Guided Optimization). The JIT collects runtime profiling data (e.g. which types are common, branch predictions) and uses it to generate more optimized code later. In .NET 9, PGO has been improved: the JIT uses PGO data for more patterns (like type checks / casts) and makes better decisions.

10) Graceful Shutdown

When we break up with our lover, we often argue and regret it later. When an application breaks up with an operating system, it should be done well 😘 ... When your app stops, maybe you deploy a new version or Kubernetes restarts a pod... the OS sends a signal called SIGTERM (terminate). A graceful shutdown means handling that signal properly, finishing what’s running, cleaning up, and exiting cleanly (like an adult)!

var app = builder.Build();
var lifetime = app.Services.GetRequiredService<IHostApplicationLifetime>();
lifetime.ApplicationStopping.Register(() =>
{
    // stop accepting, finish in-flight, flush telemetry
});
app.Run();

On K8s, set terminationGracePeriodSeconds and wire readiness /startup probes.

11) Load Test

Sometimes arguing with our lover is good. We can see her/his face before marrying 😀 Use k6 or bombardier and test with realistic payloads and prod-like limits. Don't be surprise later when your app is running on prod! These topics should be tested: CPU % , Time in GC , LOH Allocations , ThreadPool Queue Length and Socket Exhaustion.

About K6

A modern load testing tool, using Go and JavaScript.
29K stars on GitHub
GitHub address: https://github.com/grafana/k6

About Bombardier

Fast cross-platform HTTP benchmarking tool written in Go.
7K stars on GitHub
GitHub address: https://github.com/codesenberg/bombardier

Summary

In summary, I listed 11 items for optimizing a .NET application for production; Covering build configuration, hosting setup, runtime behavior, data access, telemetry, containerization, security, startup performance and reliability under load. By applying the checklist from Part 1 and Part 2 of this series, leveraging techniques like trimmed releases, server GC, minimal payloads, pooled DbContexts, OpenTelemetry, multi-stage Docker builds, HTTPS enforcement, and proper shutdown handling—you’ll improve your app’s durability, scalability and maintainability under real-world traffic and production constraints. Each item is a checkpoint and you’ll be able to deliver a robust, high-performing .NET application ready for live users.

🎉 Want top-tier .NET performance without the headaches? Try ABP Framework for best-performance and skip all the hustles of .NET app development.

Optimize Your .NET App for Production - Complete Checklist (Part 1)

ABP.IO — Wed, 22 Oct 2025 07:00:25 +0000

Optimize Your .NET App for Production (Complete Checklist)

I see way too many .NET apps go to prod like it’s still “F5 on my laptop.” Here’s the checklist I wish someone shoved me years ago. It’s opinionated, pragmatic, copy-pasteable.

1) Publish Command and CSPROJ Settings

Never go to production with debug build! See the below command which publishes properly a .NET app for production.

dotnet publish -c Release -o out -p:PublishTrimmed=true -p:PublishSingleFile=true -p:ReadyToRun=true

csproj for the optimum production publish:

<PropertyGroup>
  <PublishReadyToRun>true</PublishReadyToRun>
  <PublishTrimmed>true</PublishTrimmed>
  <InvariantGlobalization>true</InvariantGlobalization>
  <TieredCompilation>true</TieredCompilation>
</PropertyGroup>

PublishTrimmed It's trimmimg assemblies. What's that!? It removes unused code from your application and its dependencies, hence it reduces the output files.
PublishReadyToRun When you normally build a .NET app, your C# code is compiled into IL (Intrmediate Language). When your app runs, the JIT Compiler turns that IL code into native CPU commands. But this takes much time on startup. When you enable PublishReadyToRun, the build process precompiles your IL into native code and it's called AOT (Ahead Of Time). Hence your app starts faster... But the downside is; the output files are now a bit bigger. Another thing; it'll compile only for a specific OS like Windows and will not run on Linux anymore.
Self-contained When you publish your .NET app this way, it ncludes the .NET runtime inside your app files. It will run even on a machine that doesn’t have .NET installed. The output size gets larger, but the runtime version is exactly what you built with.

2) Kestrel Hosting

By default, ASP.NET Core app listen only localhost, it means it accepts requests only from inside the machine. When you deploy to Docker or Kubernetes, the container’s internal network needs to expose the app to the outside world. To do this you can set it via environment variable as below:

ASPNETCORE_URLS=http://0.0.0.0:8080

Also if you’re building an internall API or a containerized microservice which is not multilngual, then add also the below setting. it disables operating system's globalization to reduce image size and dependencies..

DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1

Clean Program.cs startup! Here's a minimal Program.cs which includes just the essential middleware and settings:

var builder = WebApplication.CreateBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

builder.Services.AddResponseCompression();
builder.Services.AddResponseCaching();
builder.Services.AddHealthChecks();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/error");
    app.UseHsts();
}

app.UseResponseCompression();
app.UseResponseCaching();

app.MapHealthChecks("/health");
app.MapGet("/error", () => Results.Problem(statusCode: 500));

app.Run();

3) Garbage Collection and ThreadPool

GC Memory Cleanup Mode

GC (Garbage Collection) is how .NET automatically frees memory. There are two main modes:

Workstation GC: good for desktop apps (focuses on responsiveness)
Server GC: good for servers (focuses on throughput)

The below environment variable is telling the .NET runtime to use the Server Garbage Collector (Server GC) instead of the Workstation GC. Because our ASP.NET Core app must be optmized for servers not personal computers.

COMPlus_gcServer=1

GC Limit Memory Usage

Use at max 60% of the total available memory for the managed heap (the memory that .NET’s GC controls). So if your container or VM has, let's say 4 GB of RAM, .NET will try to keep the GC heap below 2.4 GB (60% of 4 GB). Especially when you run your app in containers, don’t let the GC assume host memory:

COMPlus_GCHeapHardLimitPercent=60

Thread Pool Warm-up

When your .NET app runs, it uses a thread pool. This is for handling background work like HTTP requests, async tasks, I/O things... By default, the thread pool starts small and grows dynamically as load increases. That’s good for desktop apps but for server apps it's too slow! Because during sudden peek of traffic, the app might waste time creating threads instead of handling requests. So below code keeps at least 200 worker threads and 200 I/O completion threads ready to go even if they’re idle.

ThreadPool.SetMinThreads(200, 200);

4) HTTP Performance

HTTP Response Compression

AddResponseCompression() enables HTTP response compression. It shrinks your outgoing responses before sending them to the client. Making smaller payloads for faster responses and uses less bandwidth. Default compression method is Gzip. You can also add Brotli compression. Brotli is great for APIs returning JSON or text. If your CPU is already busy, keep the default Gzip method.

builder.Services.AddResponseCompression(options =>
{
    options.Providers.Add<BrotliCompressionProvider>();
    options.EnableForHttps = true;
});

HTTP Response Caching

Use caching for GET endpoints where data doesn’t change often (e.g., configs, reference data). ETags and Last-Modified headers tell browsers or proxies skip downloading data that hasn’t changed.

ETag = a version token for your resource.
Last-Modified = timestamp of last change.

If a client sends If-None-Match: "abc123" and your resource’s ETag hasn’t changed, .NET automatically returns 304 Not Modified.

HTTP/2 or HTTP/3

These newer protocols make web requests faster and smoother. It's good for microservices or frontends making many API calls.

HTTP/2 : multiplexing (many requests over one TCP connection).
HTTP/3 : uses QUIC (UDP) for even lower latency.

You can enable them on your reverse proxy (Nginx, Caddy, Kestrel)... .NET supports both out of the box if your environment allows it.

Minimal Payloads with DTOs

The best practise here is; Never send/recieve your entire database entity, use DTOs. In the DTOs include only the fields the client actually needs by doing so you will keep the responses smaller and even safer. Also, prefer System.Text.Json (now it’s faster than Newtonsoft.Json) and for very high-traffic APIs, use source generation to remove reflection overhead.

//define your entity DTO
[JsonSerializable(typeof(MyDto))]
internal partial class MyJsonContext : JsonSerializerContext { }

//and simply serialize like this    
var json = JsonSerializer.Serialize(dto, MyJsonContext.Default.MyDto)

5) Data Layer (Mostly Where Most Apps Slow Down!)

Reuse `DbContext` via Factory (Pooling)

Creating a new DbContext for every query is expensive! Use IDbContextFactory<TContext>, it gives you pooled DbContext instances from a pool that reuses objects instead of creating them from scratch.

services.AddDbContextFactory<AppDbContext>(options =>
    options.UseSqlServer(connectionString));

Then inject the factory:

using var db = _contextFactory.CreateDbContext();

Also, ensure your database server (SQL Server, PostgreSQL....) has connection pooling enabled.

N+1 Query Problem

The N+1 problem occurs when your app runs one query for the main data , then N more queries for related entities. That kills performance!!!

Bad-Practise:

var users = await context.Users.Include(u => u.Orders).ToListAsync();

Good-Practise: Project to DTOs using .Select() so EF-Core generates a single optimized SQL query:

var users = await context.Users.Select(u => new UserDto
   {
        Id = u.Id,
        Name = u.Name,
        OrderCount = u.Orders.Count
    }).ToListAsync();

Indexes

Use EF Core logging, SQL Server Profiler, or EXPLAIN (Postgres/MySQL) to find slow queries. Add missing indexes only where needed. For example at this page, he wrote an SQL query which lists missing index list (also there's another version at Microsoft Docs). This perf improvement is mostly applied after running the app for a period of time.

Migrations

In production run migrations manually, never do it on app startup. That way you can review schema changes, back up data and avoid breaking the live DB.

Resilience with Polly

Use Polly for retries, timeouts and circuit breakers for your DB or HTTP calls. Handles short outages gracefully

To keep the article short and for the better readability I spitted it into 2 parts 👉 Continue with the second part here...