DEV Community: Ravi Vishwakarma

Building an AI Agent in .NET Using Microsoft Agent Framework and Clean Architecture

Ravi Vishwakarma — Thu, 22 Oct 2026 04:12:09 +0000

Introduction

Artificial Intelligence is changing how we build modern applications. Traditionally, an application follows predefined business rules to process requests, retrieve data, and return responses. With AI-powered applications, we can go a step further by allowing a Large Language Model (LLM) to understand user intent and choose appropriate actions through controlled application tools.

For example, imagine an e-commerce customer asking:

"Can you tell me where my order is and when it will arrive?"

A traditional application might require the customer to navigate to an order-tracking page, enter an order number, and interpret the result.

An AI-powered customer support agent can understand the question, identify the required information, invoke a C# method to retrieve the order status, and explain the result in natural language.

In this article, we'll explore how to design such an AI agent in .NET using the Microsoft Agent Framework, Clean Architecture, Ollama, and ASP.NET Core Web API.

We'll also discuss why separating AI integration from business logic is important and how this architecture can be extended to other applications.

1. What Is an AI Agent?

An AI agent is an AI-powered system that can interpret a request, decide which available action may help, invoke permitted tools, and use their results to complete a task.

A standard LLM integration commonly follows this flow:

Receive a user prompt.
Send the prompt to the model.
Receive a generated response.
Return the response to the user.

An agent can follow a more interactive workflow:

Receive the user's request.
Understand the user's intent.
Select an appropriate tool when necessary.
Invoke the tool with structured arguments.
Use the tool's result to formulate a response.

For example, a customer asks:

"What's the delivery status of order 1052?"

The AI model may decide that it needs order information and select a tool named GetOrderStatus.

The application executes the corresponding C# method, retrieves the authorized order information, and returns the result to the agent. The agent then generates a user-friendly answer.

The important distinction is that the LLM does not automatically gain access to your database. It can use only the capabilities that your application exposes and permits.

2. Understanding the Microsoft Agent Framework

The Microsoft Agent Framework provides building blocks for developing AI agents and workflows in .NET and other supported environments.

Instead of manually implementing every part of an agent interaction, developers can use framework capabilities to configure agents, connect models, expose functions as tools, and coordinate interactions.

A typical integration involves three components:

Chat client: Communicates with the underlying language model.
Agent: Defines the AI assistant's behavior and available capabilities.
Tools: Expose application functions that the agent can request the model to use.

For a customer support application, the chat client connects to a model, the agent receives instructions about its role, and the tools provide access to approved business operations.

For example, the agent may be allowed to:

Retrieve order status.
Check product availability.
Look up shipping information.
Retrieve an order's delivery estimate.

It should not receive unrestricted access to every database table or business operation.

Important: Framework APIs and package names can change between versions. The implementation should follow the documentation for the specific Microsoft Agent Framework version being used.

3. Why Use Clean Architecture?

Clean Architecture organizes an application into layers with clearly defined responsibilities. Its primary goal is to keep core business rules independent of infrastructure and external frameworks.

This becomes particularly useful when integrating AI because AI providers, model APIs, and agent frameworks can change over time.

For example, you might begin with a local model running through Ollama. Later, you may decide to use a hosted model provider.

If the application is designed properly, changing the AI integration should not require rewriting your order-management business logic.

A typical solution can be organized into four projects.

3.1 Domain Layer

The Domain Layer contains the core business concepts and rules.

For an e-commerce application, it may include:

Order
Product
Customer
Order status
Business rules governing orders

Example:

namespace MyApp.Domain.Entities;

public class Order
{
    public int Id { get; private set; }

    public string Status { get; private set; }

    public Order(int id, string status)
    {
        Id = id;
        Status = status;
    }
}

This is a simplified example of an order entity.

The Domain Layer should not depend on the Microsoft Agent Framework, Ollama SDKs, HTTP clients, or database-specific implementations.

Why?

Because business rules should remain usable even if the application changes its AI provider or persistence technology.

3.2 Application Layer

The Application Layer contains use cases and coordinates business operations.

For example, retrieving an order's status is an application use case. It should not need to know how an AI agent is configured.

We can define a repository abstraction:

using MyApp.Domain.Entities;

namespace MyApp.Application.Abstractions;

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(
        int orderId,
        CancellationToken cancellationToken);
}

Next, create an application service:

using MyApp.Application.Abstractions;

namespace MyApp.Application.Orders;

public sealed class GetOrderStatusService
{
    private readonly IOrderRepository _repository;

    public GetOrderStatusService(IOrderRepository repository)
    {
        _repository = repository;
    }

    public async Task<string?> ExecuteAsync(
        int orderId,
        CancellationToken cancellationToken)
    {
        var order = await _repository.GetByIdAsync(
            orderId,
            cancellationToken);

        return order?.Status;
    }
}

This service coordinates the use case without knowing whether the request originated from a web controller, a background process, or an AI agent.

In a production application, you would also validate the order ID and enforce the appropriate customer authorization rules.

3.3 Infrastructure Layer

The Infrastructure Layer contains implementations that depend on external technologies.

Examples include:

Database repositories.
AI model clients.
Microsoft Agent Framework integration.
External APIs.
Email services.

The infrastructure repository implements the application abstraction:

using MyApp.Application.Abstractions;
using MyApp.Domain.Entities;

namespace MyApp.Infrastructure.Persistence;

public sealed class OrderRepository : IOrderRepository
{
    public Task<Order?> GetByIdAsync(
        int orderId,
        CancellationToken cancellationToken)
    {
        // Query the actual database here.
        throw new NotImplementedException();
    }
}

The implementation is intentionally incomplete because the actual database technology and schema determine how the query should be written.

The AI agent configuration also belongs in this layer, keeping framework-specific details outside the Domain Layer.

3.4 API Layer

The API Layer exposes HTTP endpoints to clients.

It receives requests, validates their transport-level requirements, invokes the appropriate application component, and returns HTTP responses.

For example:

public sealed record CustomerQuestion(string Message);

An ASP.NET Core controller can expose an endpoint that delegates the question to an application-level agent abstraction.

[ApiController]
[Route("api/support")]
public class SupportController : ControllerBase
{
    private readonly ICustomerSupportAgent _agent;

    public SupportController(ICustomerSupportAgent agent)
    {
        _agent = agent;
    }

    [HttpPost("ask")]
    public async Task<IActionResult> Ask(
        [FromBody] CustomerQuestion request,
        CancellationToken cancellationToken)
    {
        var response = await _agent.AskAsync(
            request.Message,
            cancellationToken);

        return Ok(new { response });
    }
}

Here, ICustomerSupportAgent represents an application-owned abstraction. It must be defined and implemented as part of the solution.

This example illustrates the architectural boundary rather than a complete, directly runnable project.

The controller does not need to know which LLM provider is being used or how tools are registered.

4. Understanding the Complete Request Flow

Let's combine the layers into a single workflow.

Suppose the customer asks:

"What's the status of my order 1052?"

The request travels through the following steps:

The API receives the customer's question.
The application invokes the customer-support agent abstraction.
The Infrastructure Layer sends the relevant conversation and instructions to the configured model.
The model determines that order information is required and requests the appropriate tool.
The framework invokes the registered C# tool.
The tool calls the Application Layer.
The application service retrieves data through the repository abstraction.
The result is returned to the agent.
The model generates a natural-language answer.
The API returns the answer to the client.

For example, if the database reports that an order has shipped, the final answer might be:

"Your order has been shipped and is currently in transit."

This answer is based on retrieved application data rather than the model guessing the order's status.

5. What Are AI Tools in .NET?

One of the most important concepts in agent development is tool calling, often called function calling.

A tool is a function that an AI model can request the application to execute.

The function itself runs within your application. The model generally determines which tool to request and what arguments to provide; your framework and application execute the actual code.

Consider a simplified C# method:

public async Task<string> GetOrderStatusAsync(
    int orderId,
    CancellationToken cancellationToken)
{
    var status = await _orderStatusService.ExecuteAsync(
        orderId,
        cancellationToken);

    return status ?? "Order not found.";
}

This method could serve as the basis for an agent tool.

However, defining a normal C# method does not automatically make it available to the LLM. The method must be registered or exposed using the framework's supported tool mechanism.

The tool should also have a clear name, a meaningful description, well-defined parameters, and a controlled return value.

For example:

Tool name: GetOrderStatus
Description: Retrieves the status of an order the current customer is authorized to access.
Parameter: orderId
Result: The order status or a safe not-found response.

Good descriptions help the model understand when a tool is appropriate. They do not replace authorization or input validation.

6. Why Tool Descriptions and Annotations Matter

When registering a tool, descriptive metadata helps the model understand its purpose.

Compare these two descriptions:

Poor description:

"Gets data."

Better description:

"Retrieves the current status of an order using its ID. Use this tool when a customer asks about order progress."

The second description provides clearer guidance about the tool's intended use.

Depending on the framework version, C# methods can be exposed using function factories, method annotations, or other supported registration mechanisms.

Conceptually, the registration process looks like this:

// Illustrative pseudocode, not a complete framework API call.

var tools = new[]
{
    CreateTool(
        method: GetOrderStatusAsync,
        description: "Retrieve the current status of an order.")
};

// Register the tools with the configured agent.

The exact implementation depends on the Microsoft Agent Framework version and the specific tool-registration API.

The principle remains the same: expose a small set of well-defined operations rather than allowing the model to execute arbitrary code.

7. Configuring Ollama for Local AI Execution

Ollama allows developers to run supported language models locally.

This can be useful during development because you can experiment with agent behavior without necessarily sending every prompt to a hosted model provider.

A typical setup involves:

Installing Ollama.
Downloading a model supported by your environment.
Starting the local model service.
Configuring the .NET application to use the local endpoint.
Creating the chat client and agent using compatible framework integrations.

The application configuration might contain settings such as:

{
  "AI": {
    "Provider": "Ollama",
    "Model": "your-local-model",
    "Endpoint": "http://localhost:11434"
  }
}

The model name is a placeholder. Use a model that is actually installed and compatible with the selected integration.

In a real application, environment-specific settings should be managed appropriately. Credentials, if required, should be stored in environment variables or a secrets manager rather than committed to source control.

Also remember that local execution has hardware requirements. Model size, available memory, inference speed, and tool-calling support all affect the experience.

8. The Agent Factory Pattern

Creating an agent may require several configuration steps:

Creating a chat client.
Selecting the model.
Setting system instructions.
Registering tools.
Configuring execution options.
Creating the agent instance.

Repeating these steps in controllers or application services makes the code difficult to maintain.

An agent factory centralizes the creation process.

Conceptually:

public interface ICustomerSupportAgentFactory
{
    ICustomerSupportAgent Create();
}

The infrastructure project can implement this factory using the chosen AI framework.

The API or application layer depends on an application-owned abstraction instead of directly constructing framework-specific agents.

This provides several benefits:

Centralized agent configuration.
Easier testing.
Reduced duplication.
Clear separation of responsibilities.
Simpler changes to provider-specific implementation.

Not every application needs to create a new agent instance for every request. Depending on the framework's lifecycle and thread-safety requirements, a configured agent may be reused. Conversation-specific state should be handled separately and safely.

9. Dependency Injection in ASP.NET Core

ASP.NET Core provides built-in dependency injection.

Instead of creating repositories, application services, or AI clients manually inside controllers, you register them with the service container.

For example:

builder.Services.AddScoped<
    GetOrderStatusService>();

builder.Services.AddScoped<
    IOrderRepository,
    OrderRepository>();

The agent abstraction and its factory would also be registered according to their implementations and lifecycle requirements.

For example, an infrastructure extension method might look like this:

public static class DependencyInjection
{
    public static IServiceCollection AddAiInfrastructure(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // Register the AI client, tools, agent factory,
        // and agent abstraction here.

        return services;
    }
}

The method is a structural example; the actual registrations depend on the chosen framework APIs.

In Program.cs, the API project can then call:

builder.Services.AddAiInfrastructure(
    builder.Configuration);

This keeps the application startup file from becoming crowded with model configuration and tool-registration details.

10. Keeping AI Dependencies Out of the Domain Layer

This is one of the most important Clean Architecture principles in an AI application.

Suppose your domain entity directly references a class from an AI framework.

// Avoid this architectural approach.

public class Order
{
    // Domain properties should not depend on
    // AI framework-specific classes.
}

The problem is not that a domain entity cannot contain business logic. The problem is introducing an unnecessary dependency on an external AI technology.

If you later replace the AI framework, your domain model should not require changes simply because an infrastructure dependency changed.

A cleaner dependency direction is:

The Domain Layer contains core business concepts.
The Application Layer contains use cases and abstractions.
The Infrastructure Layer implements external integrations.
The API Layer exposes endpoints and composes the application.

Infrastructure depends on application abstractions, not the other way around.

This makes it easier to unit-test business logic without starting an LLM, connecting to a real database, or making network requests.

11. Security Considerations for AI Agents

An AI agent introduces additional security considerations because it can select from application capabilities based on natural-language input.

The model should never be treated as an authorization mechanism.

For example, a customer may ask:

"Show me the details of order 2000."

Even if the model correctly identifies the order-status tool, the application must verify that the current customer is allowed to access that order.

Important safeguards include:

Authentication: Identify the current user through your normal authentication mechanism.

Authorization: Check access permissions inside the application service or another trusted enforcement layer.

Input validation: Validate order IDs and other arguments supplied to tools.

Least privilege: Expose only the operations required by the agent.

Sensitive-data protection: Return only the fields needed to answer the question.

Controlled side effects: Require appropriate authorization and confirmation before performing actions such as cancelling orders, issuing refunds, or changing account information.

Logging and monitoring: Record useful operational details without unnecessarily logging passwords, tokens, personal information, or sensitive prompts.

A tool description may tell the model not to access another customer's order, but the application must enforce that restriction in code.

12. Testing an AI Agent Application

Testing should cover the ordinary .NET application as well as the AI integration.

Unit tests

Test application services independently.

For example, verify that GetOrderStatusService returns the correct status when a repository provides an order and handles missing orders appropriately.

Use a mock or fake repository to avoid requiring a real database.

Integration tests

Verify that the infrastructure repository communicates correctly with the database and that dependency injection is configured as expected.

Tool tests

Test tool argument validation, authorization, successful results, error handling, and unexpected inputs.

Agent behavior tests

Evaluate whether the model selects the correct tool for representative user questions and produces responses consistent with the tool results.

Because model outputs may vary, avoid relying exclusively on exact-string comparisons. Test important behavioral properties and security boundaries.

End-to-end tests

Test the entire request path, from the HTTP endpoint through tool execution to the final response.

This combination helps identify problems in business logic, infrastructure configuration, tool selection, and model behavior.

13. Applying This Architecture to Other .NET Applications

The same design can be used in applications beyond e-commerce.

For example, a blogging platform could expose controlled tools for retrieving articles, finding related content, or retrieving authorized engagement statistics.

A developer-support application could retrieve documentation and code examples.

An internal business application could help employees find information from authorized company systems.

The key design principle is to keep the AI agent as an orchestration component rather than making it the owner of business rules or data access.

The model interprets requests, the application enforces rules, and the infrastructure connects to external systems.

Conclusion

Building an AI agent in .NET involves more than connecting a language model to an API endpoint. A maintainable solution needs clear architectural boundaries, controlled tools, dependency injection, provider configuration, security controls, and appropriate testing.

The Microsoft Agent Framework can help with agent and tool orchestration. Ollama can provide a local model execution option. ASP.NET Core exposes the application over HTTP, while Clean Architecture keeps the domain and application logic independent of AI-specific implementation details.

When these components are designed together, developers can add AI capabilities without tightly coupling their core business logic to a particular model provider or framework.

The key takeaway: Let the AI model decide which permitted tool may help, but let your .NET application remain responsible for business rules, authorization, data integrity, and execution.

Further Learning

Microsoft Agent Framework documentation: https://learn.microsoft.com/en-us/agent-framework/
Ollama documentation: https://docs.ollama.com/
ASP.NET Core documentation: https://learn.microsoft.com/en-us/aspnet/core/
Clean Architecture principles: https://learn.microsoft.com/en-us/dotnet/architecture/

Note: The code examples in this article illustrate the architecture and responsibilities of each layer. The agent registration and Ollama integration should be completed using the APIs available in your selected Microsoft Agent Framework version.

How to Find and Fix Memory Leaks in .NET Projects

Ravi Vishwakarma — Wed, 30 Sep 2026 03:12:28 +0000

Memory leaks in .NET applications can be confusing.

After all, .NET has a Garbage Collector (GC) that automatically removes objects that are no longer needed. So developers often ask:

“If .NET has garbage collection, how can a memory leak happen?”

The answer is that the Garbage Collector can only collect objects that are no longer reachable.

If an object is still referenced somewhere in your application—even accidentally—the GC considers it alive and cannot reclaim its memory.

This article presents a practical workflow for finding memory leaks in .NET applications using tools such as dotnet-counters, dotnet-dump, and dotnet-gcdump.

What Is a Memory Leak in .NET?

A memory leak in .NET usually doesn't mean that memory is completely lost forever.

Instead, it often means:

Objects that are no longer logically needed are still reachable through references, so the GC cannot collect them.

For example:

public class CustomerService
{
    private static readonly List<Customer> _customers = new();

    public void AddCustomer(Customer customer)
    {
        _customers.Add(customer);
    }
}

If customers are continuously added to this static collection and never removed, the list keeps references to them.

Even if the application no longer needs those customers:

Static Collection
      │
      ├── Customer
      ├── Customer
      ├── Customer
      ├── Customer
      └── ...

The GC sees that the objects are still reachable.

Therefore:

Object is referenced
        ↓
GC considers it alive
        ↓
Object is NOT collected
        ↓
Memory usage continues growing

Over time, this can lead to high memory consumption and eventually an OutOfMemoryException.

The Memory-Leak Investigation Workflow

A useful investigation can be divided into six steps:

Monitor
   ↓
Capture
   ↓
Analyze
   ↓
Find Roots
   ↓
Fix
   ↓
Verify

Let's go through each step.

1. Confirm That It's Actually a Memory Leak

The first mistake developers often make is assuming:

“Memory usage is high, therefore there is a memory leak.”

That's not necessarily true.

.NET applications naturally use memory for:

JIT compilation
object allocations
caches
thread stacks
runtime structures
temporary objects
garbage collection
native allocations

Memory usage increasing temporarily doesn't automatically indicate a leak.

The important question is:

Does memory continue growing when the application performs the same workload repeatedly?

Monitor the application

One useful tool is:

dotnet-counters monitor -p <PID>

For example:

dotnet-counters monitor -p 12345

You can monitor metrics related to:

GC activity
allocation rate
managed heap size
CPU
exceptions
thread pool activity

Suppose your application processes 1,000 requests.

You observe:

Initial memory:    300 MB

After 1,000 requests:   420 MB
After 2,000 requests:   550 MB
After 3,000 requests:   690 MB
After 4,000 requests:   830 MB

If memory consistently grows and does not return to a stable range after garbage collection, you have a reason to investigate further.

Important distinction

A healthy application can have:

Memory
  │       ┌─────┐
  │   ┌───┘     └───┐
  │───┘             └───
  └──────────────────────── Time

The GC periodically reclaims memory.

A problematic application may look more like:

Memory
  │
  │             /
  │          /
  │       /
  │    /
  │___/________________ Time

The second pattern is much more suspicious.

2. Capture a Memory Dump

Once you've confirmed that memory is behaving suspiciously, the next step is to capture the state of the process.

A memory dump gives you a snapshot of what objects exist in memory and how they are connected.

You can use:

dotnet-dump collect -p <PID>

For example:

dotnet-dump collect -p 12345

This produces a dump file that can be analyzed later.

Think of a memory dump as taking a photograph of your application's memory:

Running Application
        │
        ▼
   Memory Dump
        │
        ▼
Objects + References + Runtime State

For a production application, it's often useful to capture dumps at different points in time.

For example:

Dump 1 → Baseline
Dump 2 → After application load
Dump 3 → After several hours

This allows you to compare what changed.

3. Find Out What's Using the Memory

After obtaining a dump, you can analyze it with dotnet-dump.

Start the analyzer:

dotnet-dump analyze dump.dmp

Inside the analysis environment, commands such as:

dumpheap -stat

can help you understand what types are consuming memory.

You might see something conceptually like:

Type                         Count          Size

System.String                1,500,000      120 MB
MyApp.Customer               500,000         40 MB
MyApp.Order                  300,000         35 MB
MyApp.SomeCacheItem          250,000         30 MB

Now you have a much better question to ask.

Instead of:

"Why is my application using 500 MB?"

You can ask:

"Why are there 250,000 SomeCacheItem objects?"

That's a much more useful debugging direction.

4. Finding the Object That's Keeping Memory Alive

Finding a large object type is only half the investigation.

Suppose you discover:

MyApp.Customer
Count: 500,000

The next question is:

Why haven't these customers been collected?

This is where GC roots become extremely important.

You can investigate an object's reference chain using:

gcroot <address>

Conceptually, you might discover something like:

GC Root
  ↓
Singleton
  ↓
CustomerService
  ↓
List<Customer>
  ↓
Customer

Now you've found the actual problem.

The customer object isn't being collected because a long-lived object still holds a reference to it.

Understanding GC Roots

A GC root is an object or reference from which the GC can determine that other objects are still reachable.

Examples include:

static fields
active threads
local variables on active stacks
runtime handles
other GC roots

Consider:

public class CustomerCache
{
    private static readonly List<Customer> Customers = new();
}

The static field can keep the list alive.

The list keeps the customers alive.

Therefore:

Static Field
     ↓
List<Customer>
     ↓
Customer
     ↓
Customer
     ↓
Customer

The customers remain reachable.

This is why simply finding a large object isn't enough.

You need to understand:

Who is keeping this object alive?

5. Compare Memory Over Time

One memory dump gives you a snapshot.

Two or more dumps can tell you a story.

For example:

Dump 1 — Before Load

Customer       10,000
Order           5,000
CacheItem       2,000

Dump 2 — After Load

Customer       50,000
Order          20,000
CacheItem      10,000

Dump 3 — After More Processing

Customer      150,000
Order          40,000
CacheItem      60,000

The important observation isn't just that memory increased.

It's that certain object populations are continuously accumulating.

This gives you a much stronger lead.

A Practical Example: Static Collection Leak

Consider this code:

public class CustomerRepository
{
    private static readonly List<Customer> _customers = new();

    public void Add(Customer customer)
    {
        _customers.Add(customer);
    }
}

Imagine your application processes customers continuously:

for (int i = 0; i < 1_000_000; i++)
{
    repository.Add(new Customer());
}

The objects are still referenced by:

_customers

Therefore the GC cannot remove them.

The memory usage can continue increasing.

A possible solution

If the collection isn't supposed to retain every customer forever, change the lifecycle.

For example, use a bounded cache, remove entries when appropriate, or avoid storing objects globally.

The exact fix depends on why the collection exists.

Common Causes of Memory Leaks in .NET

Several patterns repeatedly appear during memory investigations.

1. Static Collections

This is one of the easiest ways to accidentally retain objects.

private static readonly List<MyObject> _items = new();

If _items continually grows, objects inside it remain reachable.

Consider whether the data really needs application-wide lifetime.

2. Event Subscriptions

Events can also cause unexpected object retention.

For example:

publisher.SomeEvent += subscriber.HandleEvent;

If publisher has a longer lifetime than subscriber, the publisher can keep the subscriber alive.

Conceptually:

Long-lived Publisher
        │
        │ event
        ▼
Short-lived Subscriber

If the subscription is never removed:

publisher.SomeEvent -= subscriber.HandleEvent;

the subscriber may remain reachable longer than intended.

This is especially important when objects subscribe to events but have shorter lifetimes than the event publisher.

3. Unbounded Caches

Caching isn't automatically a memory leak.

But an unbounded cache can become a serious memory problem.

For example:

private readonly Dictionary<string, object> _cache = new();

If every request adds another item:

_cache[key] = value;

and nothing is ever removed, the cache can grow indefinitely.

A cache should normally have an appropriate strategy such as:

expiration
maximum size
eviction
invalidation
appropriate lifetime

The correct strategy depends on the application's requirements.

4. Singleton References

Singletons live for a very long time—often for the lifetime of the application.

That makes them particularly important during memory-leak investigations.

Imagine:

public class MySingleton
{
    private readonly List<RequestData> _requests = new();

    public void Add(RequestData data)
    {
        _requests.Add(data);
    }
}

If the singleton continuously stores request-specific objects:

Application Lifetime
       │
       ▼
   Singleton
       │
       ▼
RequestData
RequestData
RequestData
RequestData
...

those request objects may effectively have application lifetime too.

5. Background Services

Background services can also accidentally retain data.

For example:

public class Worker : BackgroundService
{
    private readonly List<object> _items = new();

    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            _items.Add(GetData());

            await Task.Delay(1000, stoppingToken);
        }
    }
}

The loop continuously adds objects to _items.

Unless the collection is periodically cleaned or bounded, memory consumption can keep increasing.

Background services deserve special attention because they can run continuously for hours, days, or months.

6. Closures and Long-Lived Delegates

Closures can sometimes retain objects longer than expected.

For example:

var largeObject = CreateLargeObject();

someLongLivedCallback += () =>
{
    Process(largeObject);
};

The callback captures largeObject.

If someLongLivedCallback lives for a very long time, the captured object may also remain alive.

The important question is always:

What reference is preventing the object from becoming unreachable?

Memory Leak vs High Memory Usage

These two concepts shouldn't be confused.

High memory usage

An application might legitimately use a lot of memory:

Large workload
     ↓
More objects
     ↓
Higher memory usage

But after the workload finishes and objects become unreachable, GC can reclaim them.

Memory leak

With a leak:

Objects become logically unnecessary
             ↓
But references still exist
             ↓
Objects remain reachable
             ↓
GC cannot collect them
             ↓
Memory continues accumulating

That's why simply looking at the process's memory number isn't enough.

A Better Way to Think About Memory Leaks

Instead of asking:

"Why is memory usage high?"

ask these questions:

1. What objects are consuming the memory?

Use heap analysis.

2. Are these objects expected to exist?

Determine whether the object population is legitimate.

3. Why are there so many instances?

Look at allocation patterns and application behavior.

4. Why aren't they being collected?

Investigate references and GC roots.

5. What is keeping them alive?

Follow the reference chain.

6. Is that reference intentional?

This is the key question.

The Complete Investigation Process

Here's a practical workflow you can use in real .NET projects:

┌──────────────────────┐
│ 1. Monitor           │
│ dotnet-counters      │
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│ 2. Confirm Growth    │
│ Is memory increasing │
│ over time?           │
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│ 3. Capture Dump      │
│ dotnet-dump collect  │
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│ 4. Analyze Heap      │
│ dumpheap -stat       │
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│ 5. Find References   │
│ gcroot <address>     │
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│ 6. Identify Cause    │
│ Static? Event?       │
│ Cache? Singleton?    │
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│ 7. Fix               │
│ Remove unintended    │
│ references           │
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│ 8. Verify            │
│ Monitor again        │
│ and compare dumps    │
└──────────────────────┘

Don't Just Look at the Biggest Object

This is an important lesson.

Suppose your dump shows:

String        200 MB
Customer       80 MB
Order          70 MB
CacheItem      50 MB

It may be tempting to immediately investigate String.

But strings could simply be legitimate application data.

Instead, ask:

Which object population is unexpectedly growing?

For example, if CacheItem grows from:

5 MB → 15 MB → 50 MB → 100 MB

while the workload remains similar, that is much more interesting.

Memory debugging is therefore not just about finding the largest object.

It's about finding the unexpectedly retained object.

Fixing the Leak Is Only Half the Job

After making a change, don't immediately assume the problem is solved.

Repeat the same workload.

For example:

Before Fix

Initial:       300 MB
After load:    700 MB
After more:    1.1 GB

After the fix:

Initial:       300 MB
After load:    450 MB
After more:    470 MB
After more:    460 MB

The second pattern suggests that memory is reaching a more stable range.

You can also take another dump and compare the object population.

Practical Checklist

When investigating a suspected .NET memory leak, use this checklist:

Confirm

Is memory actually growing over time?
Does the growth happen under a repeatable workload?
Is the application experiencing GC pressure?
Is the growth expected for the workload?

Capture

Capture a memory dump.
Record when the dump was taken.
Capture a baseline dump.
Capture another dump after the memory grows.

Analyze

Inspect heap statistics.
Find unexpectedly large object populations.
Identify objects that continue accumulating.
Investigate their reference chains.

Find the Root

Look for:

Static collections
Event subscriptions
Unbounded caches
Singleton references
Background services
Long-lived delegates
Long-lived tasks
Unexpected object ownership

Verify

Apply the fix.
Run the same workload again.
Monitor memory.
Capture another dump if necessary.
Compare object counts over time.

Final Takeaway

Finding a memory leak in .NET isn't simply about asking:

"Why is memory usage high?"

A better investigation is:

"Which objects are growing, why are they still reachable, and what is keeping them alive?"

The general workflow is:

Monitor
   ↓
Capture
   ↓
Analyze
   ↓
Find Roots
   ↓
Fix
   ↓
Verify

Tools such as:

dotnet-counters
dotnet-dump

can help you move from a vague symptom—"our application is using too much memory"—to a concrete explanation such as:

Static Collection
       ↓
List<Customer>
       ↓
500,000 Customers
       ↓
Objects remain reachable
       ↓
GC cannot collect them

Once you understand the reference chain, memory leaks become much less mysterious.

The key principle is simple:

Don't ask only what is using memory. Ask what is keeping that memory alive.

Transaction with Dapper in ASP.NET Core API: A Beginner’s Guide

Ravi Vishwakarma — Tue, 22 Sep 2026 17:20:36 +0000

When developing an ASP.NET Core Web API, we often need to perform multiple database operations as part of a single business operation.

For example, suppose we are creating an order. We may need to:

Insert the order.
Insert order items.
Reduce product stock.
Save payment information.

What happens if the order is inserted successfully but updating the product stock fails?

Now the database contains incomplete data.

This is where database transactions become important.

In this article, we will learn how to use transactions with Dapper in ASP.NET Core Web API from the beginning, assuming you have little or no previous experience with transactions.

What is Dapper?

Dapper is a lightweight Object-Relational Mapper (ORM) for .NET.

It allows us to execute SQL queries while reducing the amount of database-related code we need to write.

For example, without Dapper, you may need to write a lot of code to execute SQL commands and convert database results into C# objects.

With Dapper, we can write:

var users = await connection.QueryAsync<User>(
    "SELECT * FROM Users"
);

Dapper executes the SQL query and maps the result to the User class.

Dapper does not hide SQL from you. Instead, it gives you a simple and fast way to work with SQL.

What is a Database Transaction?

A transaction is a group of database operations that should be treated as one unit of work.

The basic idea is:

Operation 1
    +
Operation 2
    +
Operation 3
    =
One Transaction

Either all operations succeed or all operations are rolled back.

For example:

Create Order
     |
     v
Create Order Items
     |
     v
Update Product Stock
     |
     v
Commit

If something fails:

Create Order
     |
     v
Create Order Items
     |
     v
Update Product Stock
     |
     X Error
     |
     v
Rollback

The database returns to the state it had before the transaction started.

Why Do We Need Transactions?

Imagine an e-commerce application.

A customer purchases:

Product: Laptop
Quantity: 1
Price: ₹50,000

Your API performs three operations:

INSERT INTO Orders

Then:

INSERT INTO OrderItems

Then:

UPDATE Products
SET Stock = Stock - 1

Suppose the first two queries succeed but the third query fails.

You would have:

Order created       Yes
Order item created  Yes
Stock updated       No

This creates inconsistent data.

A transaction prevents this situation.

With a transaction:

Start Transaction

    Create Order
          |
    Create Order Item
          |
    Update Stock
          |
       Success
          |
       COMMIT

If any operation fails:

Start Transaction

    Create Order
          |
    Create Order Item
          |
    Update Stock
          |
       Error
          |
      ROLLBACK

ACID Properties

Database transactions are generally described using four important properties called ACID.

1. Atomicity

All operations should succeed or all should fail.

For example:

Insert Order
Insert Order Item
Update Stock

If stock update fails, the order and order item should also be rolled back.

2. Consistency

The database should remain in a valid state before and after the transaction.

3. Isolation

One transaction should not improperly interfere with another transaction.

For example, two customers should not be able to purchase the last available product simultaneously.

4. Durability

Once a transaction is committed, the changes should remain saved even if the application restarts.

How Transactions Work with Dapper

Dapper itself does not provide a completely separate transaction system.

Instead, Dapper works with the transaction functionality provided by the database connection.

For SQL Server, we can use:

var transaction = connection.BeginTransaction();

Then pass the transaction to Dapper:

await connection.ExecuteAsync(
    sql,
    parameters,
    transaction
);

At the end:

transaction.Commit();

If something goes wrong:

transaction.Rollback();

Creating an ASP.NET Core Web API Project

Let's create a simple ASP.NET Core Web API.

You can create the project using:

dotnet new webapi -n DapperTransactionApi

Move into the project:

cd DapperTransactionApi

Install Dapper:

dotnet add package Dapper

For SQL Server, install:

dotnet add package Microsoft.Data.SqlClient

Database Setup

For this example, we will create two tables:

Orders
OrderItems

Our SQL database can contain the following tables.

Orders Table

CREATE TABLE Orders
(
    Id INT IDENTITY(1,1) PRIMARY KEY,
    CustomerName NVARCHAR(100) NOT NULL,
    TotalAmount DECIMAL(18,2) NOT NULL,
    CreatedAt DATETIME2 NOT NULL
);

OrderItems Table

CREATE TABLE OrderItems
(
    Id INT IDENTITY(1,1) PRIMARY KEY,
    OrderId INT NOT NULL,
    ProductName NVARCHAR(200) NOT NULL,
    Quantity INT NOT NULL,
    Price DECIMAL(18,2) NOT NULL,

    CONSTRAINT FK_OrderItems_Orders
        FOREIGN KEY (OrderId)
        REFERENCES Orders(Id)
);

Create the Connection String

Open:

appsettings.json

Add your SQL Server connection string:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=ShopDb;Trusted_Connection=True;TrustServerCertificate=True;"
  }
}

If you are using SQL Server authentication:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=ShopDb;User Id=sa;Password=YourPassword;TrustServerCertificate=True;"
  }
}

Never hard-code database passwords directly into your source code in a production application.

Create Order Models

Create a folder:

Models

Create:

Order.cs

namespace DapperTransactionApi.Models;

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

    public string CustomerName { get; set; } = string.Empty;

    public decimal TotalAmount { get; set; }

    public DateTime CreatedAt { get; set; }
}

Now create:

OrderItem.cs

namespace DapperTransactionApi.Models;

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

    public int OrderId { get; set; }

    public string ProductName { get; set; } = string.Empty;

    public int Quantity { get; set; }

    public decimal Price { get; set; }
}

Create Request Models

For creating an order, we can create:

CreateOrderRequest.cs

namespace DapperTransactionApi.Models;

public class CreateOrderRequest
{
    public string CustomerName { get; set; } = string.Empty;

    public decimal TotalAmount { get; set; }

    public List<CreateOrderItemRequest> Items { get; set; } = [];
}

Create:

CreateOrderItemRequest.cs

namespace DapperTransactionApi.Models;

public class CreateOrderItemRequest
{
    public string ProductName { get; set; } = string.Empty;

    public int Quantity { get; set; }

    public decimal Price { get; set; }
}

Create Database Connection

Create a folder:

Data

Then create:

DbConnectionFactory.cs

using Microsoft.Data.SqlClient;
using System.Data;

namespace DapperTransactionApi.Data;

public class DbConnectionFactory
{
    private readonly IConfiguration _configuration;

    public DbConnectionFactory(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public IDbConnection CreateConnection()
    {
        return new SqlConnection(
            _configuration.GetConnectionString("DefaultConnection")
        );
    }
}

Register the Connection Factory

Open:

Program.cs

Add:

builder.Services.AddScoped<DbConnectionFactory>();

Your basic setup can look like:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddScoped<DbConnectionFactory>();

var app = builder.Build();

app.MapControllers();

app.Run();

Creating an Order with a Transaction

Now comes the important part.

Create:

Controllers/OrdersController.cs

using Dapper;
using DapperTransactionApi.Data;
using DapperTransactionApi.Models;
using Microsoft.AspNetCore.Mvc;

namespace DapperTransactionApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly DbConnectionFactory _connectionFactory;

    public OrdersController(DbConnectionFactory connectionFactory)
    {
        _connectionFactory = connectionFactory;
    }

    [HttpPost]
    public async Task<IActionResult> CreateOrder(
        CreateOrderRequest request)
    {
        using var connection = _connectionFactory.CreateConnection();

        await connection.OpenAsync();

        using var transaction = connection.BeginTransaction();

        try
        {
            var orderSql = """
                INSERT INTO Orders
                (
                    CustomerName,
                    TotalAmount,
                    CreatedAt
                )
                OUTPUT INSERTED.Id
                VALUES
                (
                    @CustomerName,
                    @TotalAmount,
                    @CreatedAt
                );
                """;

            var orderId = await connection.ExecuteScalarAsync<int>(
                orderSql,
                new
                {
                    request.CustomerName,
                    request.TotalAmount,
                    CreatedAt = DateTime.UtcNow
                },
                transaction
            );

            var itemSql = """
                INSERT INTO OrderItems
                (
                    OrderId,
                    ProductName,
                    Quantity,
                    Price
                )
                VALUES
                (
                    @OrderId,
                    @ProductName,
                    @Quantity,
                    @Price
                );
                """;

            foreach (var item in request.Items)
            {
                await connection.ExecuteAsync(
                    itemSql,
                    new
                    {
                        OrderId = orderId,
                        item.ProductName,
                        item.Quantity,
                        item.Price
                    },
                    transaction
                );
            }

            transaction.Commit();

            return Ok(new
            {
                message = "Order created successfully",
                orderId
            });
        }
        catch (Exception ex)
        {
            transaction.Rollback();

            return StatusCode(500, new
            {
                message = "Order creation failed",
                error = ex.Message
            });
        }
    }
}

Understanding the Code Step by Step

Let's understand what is happening.

Step 1: Create Database Connection

using var connection = _connectionFactory.CreateConnection();

This creates a connection to SQL Server.

Step 2: Open the Connection

await connection.OpenAsync();

The connection is now ready for database operations.

Step 3: Start Transaction

using var transaction = connection.BeginTransaction();

This is the most important line.

From this point, database operations can participate in the transaction.

Step 4: Insert the Order

We execute:

INSERT INTO Orders

using Dapper:

var orderId = await connection.ExecuteScalarAsync<int>(
    orderSql,
    parameters,
    transaction
);

Notice this:

transaction

We pass the transaction to Dapper.

This means the query belongs to our transaction.

Why Does ExecuteScalarAsync Return the Order ID?

Our SQL contains:

OUTPUT INSERTED.Id

Suppose the database generates:

Order ID = 101

Then:

ExecuteScalarAsync<int>()

returns:

We can then use this ID when inserting order items.

Step 5: Insert Order Items

We loop through all items:

foreach (var item in request.Items)

Then insert each item:

await connection.ExecuteAsync(
    itemSql,
    parameters,
    transaction
);

Again, we pass:

transaction

Therefore, these inserts belong to the same transaction.

Step 6: Commit the Transaction

If everything works:

transaction.Commit();

The database permanently saves all changes.

The flow becomes:

Create Order
     |
     v
Create Order Item 1
     |
     v
Create Order Item 2
     |
     v
Create Order Item 3
     |
     v
Commit

Step 7: Rollback on Error

Suppose the second order item fails.

The code enters:

catch

Then:

transaction.Rollback();

This cancels all changes made by the transaction.

For example:

Order Inserted
     |
Item 1 Inserted
     |
Item 2 Failed
     |
Rollback

After rollback:

Order Inserted = No
Item 1 Inserted = No
Item 2 Inserted = No

This is the main purpose of a transaction.

Important: Every Query Must Use the Transaction

This is a common beginner mistake.

Correct:

await connection.ExecuteAsync(
    sql,
    parameters,
    transaction
);

Incorrect:

await connection.ExecuteAsync(
    sql,
    parameters
);

If you forget to pass the transaction, that query may not participate in your transaction.

The safe pattern is:

connection
+
transaction
+
Dapper query

Example API Request

We can call:

POST /api/orders

with:

{
  "customerName": "Shyam",
  "totalAmount": 1500,
  "items": [
    {
      "productName": "T-Shirt",
      "quantity": 2,
      "price": 500
    },
    {
      "productName": "Jeans",
      "quantity": 1,
      "price": 500
    }
  ]
}

The API performs:

BEGIN TRANSACTION

Insert Order
       |
       v
Get Order ID
       |
       v
Insert T-Shirt
       |
       v
Insert Jeans
       |
       v
COMMIT

What Happens If an Error Occurs?

Suppose the Jeans insertion fails.

Without a transaction:

Order       -> Created
T-Shirt     -> Created
Jeans       -> Failed

This is bad because the database contains partial data.

With a transaction:

Order       -> Created
T-Shirt     -> Created
Jeans       -> Failed
                 |
                 v
              Rollback

Final database state:

Order       -> Not Created
T-Shirt     -> Not Created
Jeans       -> Not Created

The database remains consistent.

Transaction with Product Stock

A real e-commerce application usually needs more than two queries.

For example:

Create Order
     |
Create Order Items
     |
Reduce Product Stock
     |
Create Payment Record
     |
Commit

All of these operations can be placed inside one transaction.

For example:

using var transaction = connection.BeginTransaction();

try
{
    // Create order

    // Create order items

    // Update product stock

    // Create payment record

    transaction.Commit();
}
catch
{
    transaction.Rollback();

    throw;
}

This is a common pattern in real-world applications.

Transaction Isolation Levels

SQL Server supports different transaction isolation levels.

For example:

using System.Data;

using var transaction =
    connection.BeginTransaction(
        IsolationLevel.ReadCommitted
    );

Some common isolation levels are:

ReadUncommitted
ReadCommitted
RepeatableRead
Serializable
Snapshot

For beginners, ReadCommitted is usually a good starting point to understand.

The correct isolation level depends on your application's concurrency requirements.

Using TransactionScope

Another option in .NET is:

TransactionScope

For example:

using var scope = new TransactionScope(
    TransactionScopeAsyncFlowOption.Enabled
);

try
{
    // Database operations

    scope.Complete();
}
catch
{
    // Transaction automatically rolls back
}

However, when using Dapper with a single database connection, explicitly using:

connection.BeginTransaction()

is often easier to understand and control.

Should We Put Transactions in Controllers?

For small learning projects, putting transaction code in a controller is understandable.

However, in a production application, it is better to separate responsibilities.

A common architecture is:

Controller
     |
     v
Service
     |
     v
Repository
     |
     v
Dapper
     |
     v
SQL Server

For example:

OrdersController
       |
       v
OrderService
       |
       v
OrderRepository
       |
       v
SQL Server

The service layer can control the business transaction.

Recommended Production Structure

A larger ASP.NET Core project could look like:

DapperTransactionApi
│
├── Controllers
│   └── OrdersController.cs
│
├── Services
│   └── OrderService.cs
│
├── Repositories
│   └── OrderRepository.cs
│
├── Models
│   ├── Order.cs
│   ├── OrderItem.cs
│   └── CreateOrderRequest.cs
│
├── Data
│   └── DbConnectionFactory.cs
│
├── appsettings.json
└── Program.cs

This makes the application easier to maintain.

Common Mistakes Beginners Make

1. Forgetting to Commit

If you start a transaction:

var transaction = connection.BeginTransaction();

you need to commit it:

transaction.Commit();

Otherwise, your changes may not become permanent.

2. Forgetting Rollback

Always handle exceptions:

try
{
    // operations

    transaction.Commit();
}
catch
{
    transaction.Rollback();

    throw;
}

3. Not Passing the Transaction to Dapper

Wrong:

await connection.ExecuteAsync(
    sql,
    parameters
);

Correct:

await connection.ExecuteAsync(
    sql,
    parameters,
    transaction
);

4. Opening Multiple Connections

Avoid doing this unnecessarily:

Connection 1 -> Insert Order

Connection 2 -> Insert Order Item

A transaction belongs to a particular database connection.

For a simple transaction, use the same connection:

Connection
    |
    +--- Transaction
           |
           +--- Query 1
           +--- Query 2
           +--- Query 3

5. Keeping Transactions Open for Too Long

Transactions consume database resources.

Avoid:

Begin Transaction

Wait for external API
Wait for user
Perform calculations
Wait for another service

Commit

Instead, keep the transaction as short as reasonably possible.

Begin Transaction
    |
    Database operations
    |
Commit

Transaction vs Normal Database Operations

Without transaction:

Query 1 -> Success
Query 2 -> Success
Query 3 -> Failed

The first two changes may remain in the database.

With transaction:

Query 1 -> Success
Query 2 -> Success
Query 3 -> Failed
                 |
                 v
              Rollback

Everything is reverted.

When Should You Use a Transaction?

Use transactions when multiple database operations must succeed together.

Common examples include:

E-commerce

Create Order
Create Order Items
Update Stock
Create Payment

Banking

Debit Account A
Credit Account B
Create Transaction Record

Wallet

Deduct User Wallet
Add Merchant Wallet
Create Payment Record

Booking System

Create Booking
Reserve Seat
Create Payment Record

Inventory

Create Purchase
Add Stock
Create Stock History

When Do You Not Need a Transaction?

You usually don't need an explicit transaction for a single simple database operation.

For example:

SELECT * FROM Products

or:

UPDATE Products
SET Name = @Name
WHERE Id = @Id

If there is only one independent operation, an explicit transaction may add unnecessary complexity.

Dapper Transaction Best Practices

For production applications, follow these practices:

1. Use parameterized queries

Good:

var sql = """
    SELECT *
    FROM Products
    WHERE Id = @Id
    """;

await connection.QueryAsync<Product>(
    sql,
    new { Id = productId }
);

Avoid building SQL using string concatenation:

var sql =
    "SELECT * FROM Products WHERE Id = " + productId;

Parameterized queries help protect against SQL injection.

2. Keep transactions short

Do only the required database operations inside the transaction.

3. Use async APIs

For ASP.NET Core applications:

await connection.ExecuteAsync(...);

is preferable to blocking database calls.

4. Handle exceptions properly

Use:

try
{
    // transaction operations

    transaction.Commit();
}
catch
{
    transaction.Rollback();

    throw;
}

5. Keep business logic outside the controller

For larger applications, use:

Controller
Service
Repository
Database

instead of putting everything into the controller.

Complete Transaction Flow

The complete flow can be visualized as:

                HTTP Request
                     |
                     v
              OrdersController
                     |
                     v
                OrderService
                     |
                     v
               Open Connection
                     |
                     v
              Begin Transaction
                     |
          +----------+----------+
          |          |          |
          v          v          v
      Insert       Insert     Update
       Order      Items       Stock
          |          |          |
          +----------+----------+
                     |
                     v
               Everything OK?
                  /       \
                Yes        No
                 |          |
                 v          v
              COMMIT     ROLLBACK
                 |          |
                 +-----+----+
                       |
                       v
                   API Response

This is the basic concept you should remember.

Final Example to Remember

If you are new to transactions, remember this simple pattern:

using var connection = _connectionFactory.CreateConnection();

await connection.OpenAsync();

using var transaction = connection.BeginTransaction();

try
{
    await connection.ExecuteAsync(
        sql1,
        parameters1,
        transaction
    );

    await connection.ExecuteAsync(
        sql2,
        parameters2,
        transaction
    );

    await connection.ExecuteAsync(
        sql3,
        parameters3,
        transaction
    );

    transaction.Commit();
}
catch
{
    transaction.Rollback();

    throw;
}

Think of it like this:

BEGIN
  |
  +-- Query 1
  |
  +-- Query 2
  |
  +-- Query 3
  |
  +-- Success --> COMMIT
  |
  +-- Error   --> ROLLBACK

Once you understand this pattern, you can use Dapper transactions for orders, payments, wallets, bookings, inventory, and many other business operations.

Conclusion

Transactions are an important part of building reliable ASP.NET Core Web APIs.

When multiple database operations belong to the same business operation, a transaction ensures that the database does not end up with partially completed data.

With Dapper, the basic transaction pattern is straightforward:

Open Connection
       ↓
Begin Transaction
       ↓
Execute Dapper Queries
       ↓
If Successful → Commit
       ↓
If Failed → Rollback

The most important thing to remember is that every Dapper query that should participate in the transaction must use the same database connection and transaction object.

Once this concept is clear, you can move toward a cleaner architecture using:

Controller
    ↓
Service
    ↓
Repository
    ↓
Dapper
    ↓
SQL Server

This approach is particularly useful when building production-level ASP.NET Core APIs such as e-commerce, payment, inventory, booking, and wallet systems.

Design Patterns in .NET Core

Ravi Vishwakarma — Tue, 15 Sep 2026 02:34:23 +0000

If you are learning .NET Core / ASP.NET Core, you will eventually hear a term called Design Pattern.

At first, it may sound complicated:

"What exactly is a design pattern? Why do we need it? Is it some kind of framework?"

Don't worry. It is actually much simpler than it sounds.

In this article, we will learn Design Patterns in .NET Core from the beginning, assuming you are a beginner in programming architecture.

1. What is a Design Pattern?

A Design Pattern is a commonly used solution to a common programming problem.

Think about building a house.

You don't invent everything from zero every time you build a house. There are already common ways to design:

Doors
Windows
Rooms
Electrical wiring
Plumbing

You can change the details, but the basic approaches are already known.

Design patterns work similarly in software development.

They give us a proven approach for solving common software design problems.

Simple Definition

A Design Pattern is a reusable solution or approach for solving a commonly occurring software design problem.

It is important to understand that a design pattern is not ready-made code.

It is more like a blueprint or idea that tells us how different classes and objects should work together.

2. Why Do We Need Design Patterns?

Imagine you are creating a small application.

Initially, you may write everything in one class:

public class OrderService
{
    public void CreateOrder()
    {
        // Create order

        // Save order

        // Send email

        // Send SMS

        // Process payment

        // Generate invoice
    }
}

It works.

But what happens when your application becomes large?

You might have:

Order
Payment
Email
SMS
Invoice
Product
User
Notification
Database
Reports

If everything is inside a few large classes, the application becomes difficult to:

Understand
Test
Maintain
Modify
Debug
Extend

This is where design patterns become useful.

3. Benefits of Design Patterns

Design patterns can help us write code that is:

1. Maintainable

It becomes easier to modify existing code.

2. Reusable

The same design approach can be used in different parts of an application.

3. Testable

Dependencies can be replaced with mocks or fake implementations.

4. Scalable

The architecture can handle increasing application complexity.

5. Understandable

Developers who know common patterns can understand the architecture more quickly.

4. Types of Design Patterns

Design patterns are commonly divided into three major categories.

Design Patterns
│
├── Creational Patterns
│
├── Structural Patterns
│
└── Behavioral Patterns

Let's understand each category.

5. Creational Design Patterns

Creational patterns deal with object creation.

Instead of creating objects everywhere in your application, these patterns provide better ways to create and manage objects.

Common examples include:

Singleton
Factory
Abstract Factory
Builder
Prototype

6. Singleton Pattern

The Singleton Pattern ensures that a class has only one instance, or one shared instance, during the intended lifetime.

Simple Example

Suppose your application has a configuration manager.

You don't necessarily want every part of the application to create a completely separate configuration object.

Conceptually:

Application
     |
     v
Configuration
     |
     +---- Controller
     +---- Service
     +---- Repository

All can use the same configured instance.

Singleton in .NET Core

ASP.NET Core has built-in Dependency Injection.

We can register a service as Singleton:

builder.Services.AddSingleton<IConfigurationService, ConfigurationService>();

Now .NET manages the instance for us.

Example:

public interface IConfigurationService
{
    string GetValue(string key);
}

Implementation:

public class ConfigurationService : IConfigurationService
{
    public string GetValue(string key)
    {
        return $"Value for {key}";
    }
}

Registration:

builder.Services.AddSingleton<IConfigurationService, ConfigurationService>();

Then we can inject it:

public class HomeController : Controller
{
    private readonly IConfigurationService _configurationService;

    public HomeController(
        IConfigurationService configurationService)
    {
        _configurationService = configurationService;
    }

    public IActionResult Index()
    {
        var value = _configurationService.GetValue("AppName");

        return Ok(value);
    }
}

Important

In modern .NET applications, you generally should not manually implement Singleton with static variables when the built-in Dependency Injection container can manage the lifetime.

7. Dependency Injection and Design Patterns

One of the most important concepts in ASP.NET Core is Dependency Injection (DI).

Suppose we have:

public class OrderService
{
    private PaymentService _paymentService;

    public OrderService()
    {
        _paymentService = new PaymentService();
    }
}

There is a problem.

OrderService is directly creating PaymentService.

This creates tight coupling.

Instead:

public class OrderService
{
    private readonly IPaymentService _paymentService;

    public OrderService(IPaymentService paymentService)
    {
        _paymentService = paymentService;
    }
}

Now OrderService doesn't care how the payment service is created.

ASP.NET Core provides it through DI.

Registration:

builder.Services.AddScoped<IPaymentService, PaymentService>();

This makes our application easier to test and maintain.

8. Factory Pattern

The Factory Pattern is used when we want to create objects without exposing the exact object creation logic to the calling code.

Imagine we support multiple payment methods:

Payment
│
├── Credit Card
├── UPI
├── PayPal
└── Wallet

Without a Factory:

if (paymentType == "UPI")
{
    // Create UPI payment
}
else if (paymentType == "Card")
{
    // Create card payment
}
else if (paymentType == "PayPal")
{
    // Create PayPal payment
}

As payment methods increase, this code becomes messy.

Factory Example

Create an interface:

public interface IPayment
{
    void Pay(decimal amount);
}

UPI:

public class UpiPayment : IPayment
{
    public void Pay(decimal amount)
    {
        Console.WriteLine($"Paid ₹{amount} using UPI");
    }
}

Card:

public class CardPayment : IPayment
{
    public void Pay(decimal amount)
    {
        Console.WriteLine($"Paid ₹{amount} using Card");
    }
}

Factory:

public class PaymentFactory
{
    public IPayment CreatePayment(string type)
    {
        return type.ToLower() switch
        {
            "upi" => new UpiPayment(),
            "card" => new CardPayment(),
            _ => throw new ArgumentException("Invalid payment type")
        };
    }
}

Usage:

var factory = new PaymentFactory();

IPayment payment = factory.CreatePayment("upi");

payment.Pay(1000);

Output:

Paid ₹1000 using UPI

The calling code doesn't need to know how UpiPayment is created.

9. Builder Pattern

The Builder Pattern is useful when creating a complex object with many optional properties.

For example:

var user = new User
{
    Name = "Rahul",
    Email = "rahul@example.com",
    Phone = "9999999999",
    Address = "Delhi",
    Age = 25
};

This may become difficult when an object has many configuration options.

A Builder can make the creation process clearer.

Example:

public class UserBuilder
{
    private readonly User _user = new();

    public UserBuilder SetName(string name)
    {
        _user.Name = name;
        return this;
    }

    public UserBuilder SetEmail(string email)
    {
        _user.Email = email;
        return this;
    }

    public UserBuilder SetAge(int age)
    {
        _user.Age = age;
        return this;
    }

    public User Build()
    {
        return _user;
    }
}

Usage:

var user = new UserBuilder()
    .SetName("Rahul")
    .SetEmail("rahul@example.com")
    .SetAge(25)
    .Build();

This is especially useful when object construction has multiple steps or optional configuration.

10. Structural Design Patterns

Structural patterns deal with how classes and objects are connected.

Common examples include:

Adapter
Decorator
Facade
Proxy
Composite

Let's understand the most useful ones.

11. Adapter Pattern

Suppose your application expects:

public interface IPayment
{
    void Pay(decimal amount);
}

But you have an external payment SDK that provides:

public class ExternalPayment
{
    public void MakePayment(decimal amount)
    {
        Console.WriteLine($"Payment completed: {amount}");
    }
}

Our application expects:

Pay()

but the external library provides:

MakePayment()

We can use an Adapter.

public class PaymentAdapter : IPayment
{
    private readonly ExternalPayment _externalPayment;

    public PaymentAdapter(ExternalPayment externalPayment)
    {
        _externalPayment = externalPayment;
    }

    public void Pay(decimal amount)
    {
        _externalPayment.MakePayment(amount);
    }
}

Now our application can use:

IPayment payment =
    new PaymentAdapter(new ExternalPayment());

payment.Pay(500);

The Adapter converts one interface into another interface that our application expects.

12. Decorator Pattern

The Decorator Pattern allows us to add additional behavior to an existing object without changing its original class.

Suppose we have:

public interface IOrderService
{
    void CreateOrder();
}

Basic implementation:

public class OrderService : IOrderService
{
    public void CreateOrder()
    {
        Console.WriteLine("Order created");
    }
}

Now we want logging.

Instead of modifying OrderService, we can create a decorator:

public class LoggingOrderService : IOrderService
{
    private readonly IOrderService _orderService;

    public LoggingOrderService(IOrderService orderService)
    {
        _orderService = orderService;
    }

    public void CreateOrder()
    {
        Console.WriteLine("Creating order...");

        _orderService.CreateOrder();

        Console.WriteLine("Order creation completed");
    }
}

Now:

LoggingOrderService
        |
        v
   OrderService

The original service remains unchanged.

13. Facade Pattern

A Facade provides a simple interface to a complicated system.

Imagine placing an order requires:

Order Service
      |
      +-- Payment Service
      |
      +-- Inventory Service
      |
      +-- Notification Service
      |
      +-- Invoice Service

Instead of the controller calling all of these services individually, we can create:

public class OrderFacade
{
    public void PlaceOrder()
    {
        // Payment
        // Inventory
        // Invoice
        // Notification
    }
}

The controller simply does:

_orderFacade.PlaceOrder();

The complexity is hidden behind the Facade.

14. Behavioral Design Patterns

Behavioral patterns focus on how objects communicate and how responsibilities are distributed.

Common examples include:

Strategy
Observer
Command
Chain of Responsibility
Mediator
State

15. Strategy Pattern

The Strategy Pattern is very useful in real-world applications.

Suppose an e-commerce application has different discount strategies:

Discount
│
├── Festival Discount
├── VIP Discount
├── Coupon Discount
└── No Discount

Instead of writing:

if (type == "festival")
{
}
else if (type == "vip")
{
}
else if (type == "coupon")
{
}

we can create different strategies.

Interface:

public interface IDiscountStrategy
{
    decimal CalculateDiscount(decimal amount);
}

Festival:

public class FestivalDiscount : IDiscountStrategy
{
    public decimal CalculateDiscount(decimal amount)
    {
        return amount * 0.20m;
    }
}

VIP:

public class VipDiscount : IDiscountStrategy
{
    public decimal CalculateDiscount(decimal amount)
    {
        return amount * 0.30m;
    }
}

Now our application can select the required strategy.

public class DiscountService
{
    private readonly IDiscountStrategy _strategy;

    public DiscountService(IDiscountStrategy strategy)
    {
        _strategy = strategy;
    }

    public decimal GetDiscount(decimal amount)
    {
        return _strategy.CalculateDiscount(amount);
    }
}

The important idea is:

We can change the algorithm without changing the main business logic.

16. Observer Pattern

The Observer Pattern is useful when one event needs to notify multiple objects.

Imagine an order is created.

We may need to:

Order Created
     |
     +---- Send Email
     |
     +---- Send SMS
     |
     +---- Send Push Notification
     |
     +---- Update Analytics

Instead of tightly connecting everything to the Order class, we can use an event/observer approach.

In .NET, this concept appears in many forms, including:

Events
Event handlers
Messaging systems
Domain events
Pub/Sub systems

For example:

public class OrderService
{
    public event EventHandler? OrderCreated;

    public void CreateOrder()
    {
        Console.WriteLine("Order Created");

        OrderCreated?.Invoke(this, EventArgs.Empty);
    }
}

Another component can subscribe:

orderService.OrderCreated += SendEmail;

This allows one event to notify multiple listeners.

17. Repository Pattern

If you work with ASP.NET Core and Entity Framework Core, you will often hear about the Repository Pattern.

The idea is to separate database access from business logic.

Without separation:

public class ProductService
{
    public Product GetProduct(int id)
    {
        // Direct database code
    }
}

With a repository:

Controller
    |
    v
Service
    |
    v
Repository
    |
    v
Database

Interface:

public interface IProductRepository
{
    Product? GetById(int id);

    IEnumerable<Product> GetAll();
}

Implementation:

public class ProductRepository : IProductRepository
{
    private readonly AppDbContext _context;

    public ProductRepository(AppDbContext context)
    {
        _context = context;
    }

    public Product? GetById(int id)
    {
        return _context.Products
            .FirstOrDefault(x => x.Id == id);
    }

    public IEnumerable<Product> GetAll()
    {
        return _context.Products.ToList();
    }
}

Then the service uses the abstraction:

public class ProductService
{
    private readonly IProductRepository _repository;

    public ProductService(IProductRepository repository)
    {
        _repository = repository;
    }

    public Product? GetProduct(int id)
    {
        return _repository.GetById(id);
    }
}

18. Important Note About Repository Pattern in EF Core

There is an important architectural discussion here.

Entity Framework Core already provides abstractions such as:

DbContext
DbSet<T>

So adding a generic repository on top of EF Core is not automatically a best practice.

For simple applications, directly using DbContext inside application services can be perfectly reasonable.

Repositories become more useful when they provide meaningful domain-specific data-access behavior or when the architecture has a clear reason for the abstraction.

Don't create a pattern just because someone says:

"Every .NET project must have Repository Pattern."

Patterns should solve problems, not create extra code.

19. Unit of Work Pattern

The Unit of Work Pattern groups multiple database operations into one logical transaction.

Imagine creating an order:

Create Order
     |
     +-- Save Order
     |
     +-- Update Inventory
     |
     +-- Create Payment Record

We generally want these changes to succeed together.

Conceptually:

BEGIN TRANSACTION

Create Order
Update Inventory
Create Payment

COMMIT

If something fails:

ROLLBACK

EF Core's DbContext already provides behavior that can cover Unit-of-Work responsibilities in many applications.

Therefore, just like Repository Pattern, don't add a separate Unit of Work abstraction automatically.

20. Dependency Injection Lifetimes in ASP.NET Core

ASP.NET Core provides three common DI lifetimes.

Singleton

One instance for the application's service container lifetime.

builder.Services.AddSingleton<IMyService, MyService>();

Use it for services that are:

Stateless
Thread-safe
Safe to share

Scoped

One instance per scope.

In a typical ASP.NET Core web request, that usually means one instance per HTTP request.

builder.Services.AddScoped<IMyService, MyService>();

This is commonly used for services working with:

DbContext
Business Services
Repositories

Transient

A new instance is created each time it is requested.

builder.Services.AddTransient<IMyService, MyService>();

Useful for lightweight, stateless services where sharing an instance is unnecessary.

21. Design Patterns and SOLID Principles

Design patterns work very closely with SOLID principles.

SOLID stands for:

S → Single Responsibility Principle

O → Open/Closed Principle

L → Liskov Substitution Principle

I → Interface Segregation Principle

D → Dependency Inversion Principle

For example, consider:

public class OrderService
{
    public void CreateOrder()
    {
        // Order logic
        // Payment logic
        // Email logic
        // Invoice logic
    }
}

This class has too many responsibilities.

The Single Responsibility Principle suggests separating these concerns.

We might have:

OrderService
PaymentService
EmailService
InvoiceService

Then Dependency Injection connects them.

This produces a cleaner architecture.

22. How Patterns Fit Together in a Real ASP.NET Core Application

A production application might look something like this:

                 Client
                   |
                   v
              Controller
                   |
                   v
             Application
               Service
                   |
          +--------+--------+
          |        |        |
          v        v        v
      Repository Payment  Notification
          |        |        |
          v        v        v
       Database   Gateway   Email/SMS

Different patterns may be used at different levels.

For example:

Dependency Injection
        ↓
Service Layer
        ↓
Repository
        ↓
Database

And inside the service:

Strategy
Factory
Facade
Decorator

The exact architecture depends on the application.

23. Example: E-Commerce Application

Let's take a practical example.

Suppose we are building an e-commerce application.

A customer places an order.

The flow could be:

Customer
   |
   v
OrderController
   |
   v
OrderService
   |
   +---- Discount Strategy
   |
   +---- Payment Factory
   |
   +---- Inventory Repository
   |
   +---- Notification Service
   |
   v
Database

Step 1 — Controller

Receives the HTTP request.

[HttpPost]
public IActionResult CreateOrder(CreateOrderRequest request)
{
    _orderService.CreateOrder(request);

    return Ok();
}

Step 2 — Service

Handles business logic.

public void CreateOrder(CreateOrderRequest request)
{
    // Validate order

    // Calculate discount

    // Process payment

    // Update inventory

    // Save order

    // Notify customer
}

Step 3 — Repository

Handles database-related operations.

_repository.Save(order);

Step 4 — Strategy

Calculates the appropriate discount.

var discount = strategy.CalculateDiscount(amount);

Step 5 — Factory

Creates the appropriate payment implementation.

var payment = paymentFactory.CreatePayment("upi");

Now every component has a clear responsibility.

24. Which Design Patterns Should a Beginner Learn First?

Don't try to memorize 20+ patterns at once.

Start with these:

Level 1 — Must Know

1. Dependency Injection
2. Factory
3. Strategy
4. Repository
5. Singleton

Level 2 — Learn Next

6. Decorator
7. Adapter
8. Facade
9. Builder
10. Unit of Work

Level 3 — Advanced

11. Mediator
12. Command
13. Observer
14. Chain of Responsibility
15. State

The exact order can vary depending on the type of project you are building.

25. Don't Overuse Design Patterns

This is one of the most important lessons.

A beginner may learn design patterns and then think:

"I need to use a pattern everywhere."

That's a mistake.

For example, if your application has:

public class Calculator
{
    public int Add(int a, int b)
    {
        return a + b;
    }
}

You probably don't need:

CalculatorFactory
CalculatorRepository
CalculatorStrategy
CalculatorFacade
CalculatorBuilder
CalculatorManager
CalculatorProvider

That would make simple code unnecessarily complicated.

A good developer asks:

"What problem am I solving?"

Then chooses a pattern if it actually helps.

26. Design Pattern vs Framework Feature

Another important point:

A framework feature and a design pattern are not always the same thing.

For example, ASP.NET Core provides:

Dependency Injection
Middleware
Configuration
Logging
Routing
Authentication
Authorization

Some of these features are implemented using established software design concepts and patterns internally.

As a developer, you don't always need to manually implement the underlying pattern.

For example, instead of manually implementing Singleton, ASP.NET Core DI can manage service lifetimes:

builder.Services.AddSingleton<IMyService, MyService>();

Use the framework's capabilities when they already solve the problem well.

27. A Simple Rule to Remember

You can remember design patterns like this:

CREATIONAL
"How should I create objects?"

        ↓

Factory
Builder
Singleton


STRUCTURAL
"How should objects/classes be connected?"

        ↓

Adapter
Decorator
Facade


BEHAVIORAL
"How should objects communicate or behave?"

        ↓

Strategy
Observer
Command
Mediator

This simple classification makes it much easier to understand them.

28. Final Example

Let's imagine we are building a food delivery application.

We might have:

                API
                 |
                 v
             Controller
                 |
                 v
             OrderService
                 |
       +---------+---------+
       |         |         |
       v         v         v
   Strategy    Factory   Repository
       |         |         |
       v         v         v
  Discount    Payment    Database
              Gateway

Here:

Dependency Injection
connects our components.

Strategy Pattern
handles different discount algorithms.

Factory Pattern
creates different payment implementations.

Repository Pattern
separates data access.

Decorator Pattern
can add logging, caching, etc.

Facade Pattern
can simplify complicated workflows.

This is how patterns can work together in a real application.

Conclusion

Design Patterns are not magic code and they are not rules that every .NET Core application must follow.

They are proven approaches for solving recurring software design problems.

If you are a beginner in .NET Core, don't try to memorize every pattern.

First understand:

Problem
   ↓
Why is the current code difficult?
   ↓
What responsibility should be separated?
   ↓
Which pattern can help?
   ↓
Implement only what is necessary

Start with Dependency Injection, Factory, Strategy, Repository, and Singleton, then gradually learn more advanced patterns such as Decorator, Adapter, Facade, Mediator, and Command.

The real goal is not to say:

"I know 20 design patterns."

The real goal is to be able to say:

"I understand the problem, and I know which design approach will make my code cleaner, maintainable, testable, and easier to extend."

That is what good software design is about.

How Many Ways to Create Middleware in ASP.NET Core?

Ravi Vishwakarma — Tue, 08 Sep 2026 03:46:48 +0000

Middleware is one of the most important concepts in ASP.NET Core. Whether you are building authentication, logging, exception handling, request validation, performance monitoring, or custom security rules, middleware gives you a place to execute logic while an HTTP request moves through the application pipeline.

In modern ASP.NET Core, there are three common ways to create custom middleware:

Inline middleware using app.Use(...)
Convention-based middleware using a middleware class
Middleware using IMiddleware

ASP.NET Core also provides methods such as Run() and Map() for terminating or branching the request pipeline. These are useful when designing middleware pipelines, but they are not separate custom middleware implementation patterns.

Let's understand each approach with practical examples.

What Is Middleware?

Middleware is software that is assembled into the ASP.NET Core request pipeline.

A request passes through middleware components one after another. Each middleware can:

Inspect the request
Modify the request
Perform some work before the next middleware
Call the next middleware
Inspect or modify the response
Stop the request from continuing

A simple pipeline looks like this:

Client
   |
   v
Middleware 1
   |
   v
Middleware 2
   |
   v
Middleware 3
   |
   v
Endpoint
   |
   v
HTTP Response

A middleware can execute code both before and after the next middleware.

For example:

Request
  |
  v
[Middleware A]  ---> before logic
  |
  v
[Middleware B]  ---> before logic
  |
  v
[Endpoint]
  |
  v
[Middleware B]  ---> after logic
  |
  v
[Middleware A]  ---> after logic
  |
  v
Response

That behavior is one of the main reasons middleware is so powerful.

1. Inline Middleware Using `app.Use()`

The simplest way to create middleware is to write it directly in Program.cs using app.Use().

This approach is ideal for:

Small pieces of logic
Prototypes
Simple logging
Adding headers
Quick request checks
Logic that is used only once

Example

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

// Inline middleware
app.Use(async (context, next) =>
{
    // This code executes BEFORE the next middleware.
    Console.WriteLine($"Request: {context.Request.Method} {context.Request.Path}");

    // Call the next middleware in the pipeline.
    await next();

    // This code executes AFTER the next middleware has completed.
    Console.WriteLine($"Response Status Code: {context.Response.StatusCode}");
});

app.MapGet("/", () =>
{
    return "Hello from ASP.NET Core!";
});

app.Run();

Here, the lambda supplied to app.Use() becomes part of the request pipeline.

How it works

Suppose the browser requests:

GET /

The middleware executes this code first:

Console.WriteLine($"Request: {context.Request.Method} {context.Request.Path}");

Then:

await next();

passes control to the next component.

After the next component finishes, execution returns to:

Console.WriteLine($"Response Status Code: {context.Response.StatusCode}");

So the execution flow is:

Request
   |
   v
Log Request
   |
   v
Next Middleware / Endpoint
   |
   v
Log Response
   |
   v
Response

Adding a Custom Response Header

An inline middleware can also modify the response.

app.Use(async (context, next) =>
{
    // Add a custom HTTP response header.
    context.Response.Headers["X-Application"] = "My ASP.NET Core App";

    // Continue processing the request.
    await next();
});

Now the response contains:

X-Application: My ASP.NET Core App

Advantages of Inline Middleware

Inline middleware is:

Very easy to write
Convenient for small tasks
Good for application-specific logic
Requires no additional class

Disadvantages

For large applications, too much middleware inside Program.cs can make the file difficult to maintain.

For example, this becomes difficult to manage:

app.Use(async (context, next) =>
{
    // 100 lines of logic...
});

app.Use(async (context, next) =>
{
    // Another 150 lines...
});

When middleware becomes reusable or complex, a separate middleware class is usually a better choice.

2. Convention-Based Middleware Using a Middleware Class

The second and most common approach is to create a dedicated middleware class.

Microsoft's ASP.NET Core documentation describes this as convention-based middleware. Typically, the middleware class receives a RequestDelegate and exposes an Invoke or InvokeAsync method.

This approach is ideal when:

Middleware contains significant logic
Middleware should be reusable
You want a clean Program.cs
You want dependency injection for services used during request processing

Step 1: Create the middleware class

Create a file called:

RequestLoggingMiddleware.cs

Then add:

public class RequestLoggingMiddleware
{
    // _next represents the next middleware in the pipeline.
    private readonly RequestDelegate _next;

    // ASP.NET Core passes the next RequestDelegate through the constructor.
    public RequestLoggingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // InvokeAsync is called for every request that reaches this middleware.
    public async Task InvokeAsync(HttpContext context)
    {
        // Code before _next() runs on the way INTO the pipeline.
        Console.WriteLine(
            $"Incoming Request: {context.Request.Method} {context.Request.Path}");

        // Call the next middleware.
        await _next(context);

        // Code after _next() runs on the way OUT of the pipeline.
        Console.WriteLine(
            $"Response Status: {context.Response.StatusCode}");
    }
}

The key elements are:

private readonly RequestDelegate _next;

and:

public async Task InvokeAsync(HttpContext context)

The _next delegate is what allows your middleware to pass control to the next component.

Registering the Middleware

In modern ASP.NET Core, you can add it using:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

// Add the custom middleware to the request pipeline.
app.UseMiddleware<RequestLoggingMiddleware>();

app.MapGet("/", () => "Hello World!");

app.Run();

UseMiddleware<TMiddleware>() adds the middleware type to the application's request pipeline.

Creating an Extension Method

A very common practice is to create an extension method for your middleware.

Create:

RequestLoggingMiddlewareExtensions.cs

public static class RequestLoggingMiddlewareExtensions
{
    public static IApplicationBuilder UseRequestLogging(
        this IApplicationBuilder app)
    {
        // Register our custom middleware.
        return app.UseMiddleware<RequestLoggingMiddleware>();
    }
}

Now Program.cs becomes cleaner:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

// Register custom middleware through the extension method.
app.UseRequestLogging();

app.MapGet("/", () => "Hello World!");

app.Run();

This style is especially useful in larger applications and reusable libraries.

Injecting Services into Convention-Based Middleware

One of the powerful features of ASP.NET Core middleware is dependency injection.

For example, suppose we want to use ILogger<T>.

public class RequestLoggingMiddleware
{
    private readonly RequestDelegate _next;

    public RequestLoggingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(
        HttpContext context,
        ILogger<RequestLoggingMiddleware> logger)
    {
        // ILogger is injected into InvokeAsync.
        logger.LogInformation(
            "Request started: {Method} {Path}",
            context.Request.Method,
            context.Request.Path);

        // Continue to the next middleware.
        await _next(context);

        // Log after the next middleware has completed.
        logger.LogInformation(
            "Request completed with status code {StatusCode}",
            context.Response.StatusCode);
    }
}

ASP.NET Core supports dependency injection into the middleware invocation method for convention-based middleware. This can be useful when you need request-scoped services.

Important: Middleware Constructor Lifetime Considerations

A common mistake is injecting a scoped service directly into the constructor of conventional middleware.

For example:

public class MyMiddleware
{
    private readonly RequestDelegate _next;
    private readonly MyScopedService _service;

    public MyMiddleware(
        RequestDelegate next,
        MyScopedService service) // Be careful with scoped dependencies here.
    {
        _next = next;
        _service = service;
    }
}

Middleware instances activated by the conventional UseMiddleware pattern are not created in the same per-request manner as IMiddleware.

For request-scoped services, a safer pattern is often to inject the service into InvokeAsync():

public async Task InvokeAsync(
    HttpContext context,
    MyScopedService service)
{
    // The scoped service is available during the request.
    service.DoSomething();

    await _next(context);
}

This distinction becomes especially important when middleware depends on scoped services such as a database context. Microsoft's documentation specifically highlights per-request activation as a benefit of IMiddleware.

3. Middleware Using `IMiddleware`

The third approach is to implement the IMiddleware interface.

This is particularly useful when you want:

Strongly typed middleware
Middleware activated through dependency injection
Per-request middleware activation
Constructor injection of scoped services

Microsoft documents IMiddleware as a factory-based middleware activation mechanism. IMiddleware is activated per request, allowing scoped dependencies to be injected into the constructor.

Creating an `IMiddleware`

Let's create a middleware called:

AuthenticationMiddleware.cs

public class AuthenticationMiddleware : IMiddleware
{
    private readonly IUserService _userService;

    // IUserService can be injected through the constructor.
    public AuthenticationMiddleware(IUserService userService)
    {
        _userService = userService;
    }

    public async Task InvokeAsync(
        HttpContext context,
        RequestDelegate next)
    {
        // Read the user ID from a request header.
        var userId = context.Request.Headers["X-User-Id"]
            .FirstOrDefault();

        // Check whether the user exists.
        var userExists = await _userService.UserExistsAsync(userId);

        if (!userExists)
        {
            // Stop the pipeline when authentication fails.
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;

            await context.Response.WriteAsync("Unauthorized");

            return;
        }

        // User is valid, so continue to the next middleware.
        await next(context);
    }
}

Notice the important difference.

We don't need:

private readonly RequestDelegate _next;

Instead, the next delegate is supplied to:

InvokeAsync(
    HttpContext context,
    RequestDelegate next)

The interface requires the request-handling method:

Task InvokeAsync(HttpContext context, RequestDelegate next)

according to the ASP.NET Core IMiddleware contract.

Registering `IMiddleware` with Dependency Injection

Unlike a typical convention-based middleware class, an IMiddleware implementation must be registered in the dependency injection container.

For example:

var builder = WebApplication.CreateBuilder(args);

// Register the dependent service.
builder.Services.AddScoped<IUserService, UserService>();

// Register the middleware.
// Scoped or transient registration is appropriate for IMiddleware.
builder.Services.AddTransient<AuthenticationMiddleware>();

var app = builder.Build();

// Add the middleware to the pipeline.
app.UseMiddleware<AuthenticationMiddleware>();

app.MapGet("/", () => "Hello World!");

app.Run();

ASP.NET Core's middleware factory resolves IMiddleware implementations from the dependency injection container and creates them for the request. Microsoft documents Scoped or Transient registration for factory-activated middleware.

`IMiddleware` vs Convention-Based Middleware

At first glance, these two approaches look very similar.

Convention-based middleware

public class LoggingMiddleware
{
    private readonly RequestDelegate _next;

    public LoggingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        await _next(context);
    }
}

`IMiddleware`

public class LoggingMiddleware : IMiddleware
{
    public async Task InvokeAsync(
        HttpContext context,
        RequestDelegate next)
    {
        await next(context);
    }
}

The major difference is how the middleware instance is activated.

With IMiddleware, ASP.NET Core uses IMiddlewareFactory and the dependency injection container to create the middleware instance. This provides per-request activation and makes constructor injection of scoped services possible.

4. What About `Run()`?

You may also see:

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello World!");
});

Is this another way to create middleware?

Technically, Run() adds a terminal request delegate to the pipeline, but it is usually better described as a pipeline termination mechanism, not a separate custom middleware implementation pattern.

For example:

app.Use(async (context, next) =>
{
    Console.WriteLine("Before terminal middleware");

    await next();

    Console.WriteLine("This will not run because Run() is terminal.");
});

app.Run(async context =>
{
    // This is the final handler.
    await context.Response.WriteAsync("Request handled here.");
});

Run() does not call the next component because it is terminal.

So:

Use()
 |
 v
Run()
 |
 v
Response

rather than:

Use()
 |
 v
Use()
 |
 v
Endpoint

ASP.NET Core's middleware documentation describes Run as a terminal delegate in the pipeline.

5. What About `Map()`?

Another useful method is:

app.Map("/admin", adminApp =>
{
    adminApp.Run(async context =>
    {
        await context.Response.WriteAsync(
            "This is the admin pipeline.");
    });
});

Map() creates a branch in the middleware pipeline based on the request path.

For example:

                    +--> /admin --> Admin Pipeline
                    |
Request --> Main Pipeline
                    |
                    +--> Other Paths --> Main Pipeline

A complete example:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.Use(async (context, next) =>
{
    Console.WriteLine("Main pipeline");

    await next();
});

// Create a separate middleware pipeline for /admin.
app.Map("/admin", adminApp =>
{
    adminApp.Use(async (context, next) =>
    {
        // This middleware runs only for /admin requests.
        Console.WriteLine("Admin pipeline");

        await next();
    });

    adminApp.Run(async context =>
    {
        // Final response for the /admin branch.
        await context.Response.WriteAsync("Admin area");
    });
});

app.Run(async context =>
{
    // Requests that don't use the /admin branch end up here.
    await context.Response.WriteAsync("Main application");
});

Map() is therefore best thought of as a pipeline branching mechanism, rather than a fourth custom middleware class pattern.

Comparison of the Three Main Middleware Approaches

Approach	Best For	Dependency Injection	Reusable	Complexity
`app.Use()`	Small/simple logic	Yes	Low	Very Low
Middleware class	Reusable business/application middleware	Yes	High	Medium
`IMiddleware`	DI-heavy/request-scoped middleware	Excellent	High	Medium

Which Approach Should You Use?

Use `app.Use()` for small logic

For example:

app.Use(async (context, next) =>
{
    // Simple request logging.
    Console.WriteLine(context.Request.Path);

    await next();
});

This is perfect when the middleware is short and only needed in one location.

Use a middleware class for reusable middleware

For example:

public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;

    public ExceptionHandlingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Custom exception handling logic.
        await _next(context);
    }
}

This is generally the best default for reusable custom middleware.

Use `IMiddleware` when constructor injection and request activation matter

For example:

public class TenantMiddleware : IMiddleware
{
    private readonly ITenantService _tenantService;

    public TenantMiddleware(ITenantService tenantService)
    {
        // The tenant service can be injected through DI.
        _tenantService = tenantService;
    }

    public async Task InvokeAsync(
        HttpContext context,
        RequestDelegate next)
    {
        // Resolve the current tenant.
        await _tenantService.ResolveTenantAsync(context);

        // Continue the request pipeline.
        await next(context);
    }
}

This pattern is particularly useful when middleware depends on scoped services and you want the middleware itself to be resolved by the DI container per request.

Middleware Execution Order Matters

One of the most important things to understand is that middleware executes in the order in which it is added.

Consider:

app.Use(async (context, next) =>
{
    Console.WriteLine("Middleware A - Before");

    await next();

    Console.WriteLine("Middleware A - After");
});

app.Use(async (context, next) =>
{
    Console.WriteLine("Middleware B - Before");

    await next();

    Console.WriteLine("Middleware B - After");
});

app.Run(async context =>
{
    Console.WriteLine("Endpoint");

    await context.Response.WriteAsync("Hello");
});

The output will be:

Middleware A - Before
Middleware B - Before
Endpoint
Middleware B - After
Middleware A - After

This happens because middleware forms a nested request/response pipeline.

Think of it like this:

A Before
   |
   +---- B Before
            |
            +---- Endpoint
            |
          B After
   |
A After

Therefore, middleware order can affect authentication, authorization, exception handling, routing, CORS, static files, caching, and other parts of the application.

A Real-World Example

Suppose we want to add a correlation ID to every request.

Using a middleware class:

public class CorrelationIdMiddleware
{
    private readonly RequestDelegate _next;

    public CorrelationIdMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Try to read an existing correlation ID.
        var correlationId =
            context.Request.Headers["X-Correlation-Id"]
                .FirstOrDefault();

        // Generate one if the client did not provide it.
        if (string.IsNullOrWhiteSpace(correlationId))
        {
            correlationId = Guid.NewGuid().ToString();
        }

        // Store the ID in HttpContext so other components can access it.
        context.Items["CorrelationId"] = correlationId;

        // Add the correlation ID to the response.
        context.Response.Headers["X-Correlation-Id"] = correlationId;

        // Continue processing the request.
        await _next(context);
    }
}

var app = builder.Build();

// Add correlation ID middleware early in the pipeline.
app.UseMiddleware<CorrelationIdMiddleware>();

app.MapControllers();

app.Run();

Now every request can have a consistent correlation ID, which is useful for logging and distributed tracing.

A Simple Mental Model

A good way to remember ASP.NET Core middleware is:

Middleware = Request + Logic + Next + Response

Conceptually:

public async Task InvokeAsync(
    HttpContext context,
    RequestDelegate next)
{
    // 1. Logic before the next middleware

    await next(context);

    // 2. Logic after the next middleware
}

And if you don't call next():

public async Task InvokeAsync(
    HttpContext context,
    RequestDelegate next)
{
    // Stop the pipeline.
    context.Response.StatusCode = 403;

    await context.Response.WriteAsync("Forbidden");

    // No next() call means later middleware won't execute.
}

This is how middleware can act as a gatekeeper.

Final Answer: How Many Ways?

For practical ASP.NET Core development, there are three primary ways to create custom middleware:

1. Inline middleware

app.Use(async (context, next) =>
{
    // Middleware logic
    await next();
});

Best for small, one-off pieces of logic.

2. Convention-based middleware class

public class MyMiddleware
{
    private readonly RequestDelegate _next;

    public MyMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Middleware logic
        await _next(context);
    }
}

Registered with:

app.UseMiddleware<MyMiddleware>();

Best for reusable custom middleware.

3. `IMiddleware`

public class MyMiddleware : IMiddleware
{
    public async Task InvokeAsync(
        HttpContext context,
        RequestDelegate next)
    {
        // Middleware logic
        await next(context);
    }
}

Registered through dependency injection:

builder.Services.AddTransient<MyMiddleware>();

Then:

app.UseMiddleware<MyMiddleware>();

Best when middleware needs DI-driven activation and especially when constructor injection of scoped services is important.

Methods such as Run() and Map() are also important when building the pipeline, but they are better understood as terminal and branching pipeline operations, not additional custom middleware implementation styles.

Conclusion

ASP.NET Core middleware is flexible because you can choose the implementation style according to the complexity of your application.

For quick logic, use:

app.Use(...)

For reusable custom middleware, create a middleware class and use:

app.UseMiddleware<MyMiddleware>()

For DI-driven middleware with per-request activation, implement:

IMiddleware

Once you understand HttpContext, RequestDelegate, next(), middleware ordering, and the difference between conventional and factory-based activation, you can build everything from simple logging middleware to sophisticated authentication, exception handling, tenant resolution, request tracing, and security components.

In most real-world applications, a good rule is: start with app.Use() for very small middleware, move to a dedicated middleware class as the logic grows, and consider IMiddleware when dependency-injection lifetime management is an important part of the design.

Happy Coding!

API Gateway with Ocelot in ASP.NET Core

Ravi Vishwakarma — Wed, 02 Sep 2026 16:30:02 +0000

If you are building a small application with one API, you probably don't need an API Gateway.

But as your application grows, you may end up with multiple APIs:

User API
Product API
Order API
Payment API
Notification API

Now imagine a frontend application that needs information from all these APIs.

Instead of the frontend calling every service directly, we can introduce an API Gateway.

In this article, we'll learn what an API Gateway is and how to build one using Ocelot with ASP.NET Core.

What is an API Gateway?

Let's start with the basic question.

What problem does an API Gateway solve?

Suppose we have three APIs:

User API       → http://localhost:5001
Product API    → http://localhost:5002
Order API      → http://localhost:5003

Without an API Gateway, our frontend might communicate directly with all three APIs:

             ┌─────────────┐
             │   Frontend  │
             └──────┬──────┘
                    │
          ┌─────────┼─────────┐
          ↓         ↓         ↓
      User API  Product API  Order API

This can become difficult to manage.

The frontend needs to know:

Where each API is located
Which port each API uses
Which endpoint belongs to which service
How authentication works for each service
How to handle failures

An API Gateway provides a single entry point.

             ┌─────────────┐
             │   Frontend  │
             └──────┬──────┘
                    │
                    ↓
             ┌─────────────┐
             │ API Gateway │
             └──────┬──────┘
                    │
          ┌─────────┼─────────┐
          ↓         ↓         ↓
      User API  Product API  Order API

Now the frontend only needs to communicate with the Gateway.

What is an API Gateway?

An API Gateway is a server that sits between clients and backend services.

The client sends a request to the Gateway, and the Gateway forwards that request to the appropriate backend service.

For example:

Client
   │
   │ GET /products
   ↓
API Gateway
   │
   │ forwards request
   ↓
Product API

The Product API might actually be running at:

http://localhost:5002/api/products

But the client doesn't need to know that.

It can simply call:

http://localhost:5000/products

The Gateway takes care of the routing.

What is Ocelot?

Now that we understand API Gateways, let's talk about Ocelot.

Ocelot is an API Gateway framework designed for .NET applications.

It helps us implement common API Gateway functionality such as:

Request routing
Authentication and authorization integration
Load balancing
Rate limiting
Request aggregation
Service discovery integration
Middleware-based processing

For a beginner, the most important feature to understand first is routing.

In simple terms:

Ocelot receives a request and decides which backend API should receive it.

A Simple Example

Let's say we have the following services.

User API

http://localhost:5001

Product API

http://localhost:5002

API Gateway

http://localhost:5000

We want clients to call:

GET http://localhost:5000/users

and have Ocelot forward the request to:

GET http://localhost:5001/users

Similarly:

GET http://localhost:5000/products

should be forwarded to:

GET http://localhost:5002/products

The architecture looks like this:

                     Client
                       │
                       │
                       ▼
              ┌─────────────────┐
              │   API Gateway   │
              │    Ocelot       │
              │ localhost:5000  │
              └────────┬────────┘
                       │
              ┌────────┴────────┐
              │                 │
              ▼                 ▼
        ┌───────────┐     ┌───────────┐
        │ User API  │     │Product API │
        │  :5001    │     │   :5002   │
        └───────────┘     └───────────┘

Why Do We Need an API Gateway?

You might be wondering:

Why can't my frontend just call the APIs directly?

It can.

An API Gateway isn't mandatory.

But it becomes useful when you have multiple backend services.

Here are some common benefits.

1. Single Entry Point

Instead of exposing multiple APIs to clients:

User API
Product API
Order API
Payment API

you expose one endpoint:

API Gateway

The client only needs to know about the Gateway.

2. Hide Internal Services

Suppose your Product API is running internally at:

http://product-service:5002

You probably don't want clients to know about your internal infrastructure.

The Gateway can expose:

GET /products

while internally forwarding it to:

http://product-service:5002/products

3. Centralized Authentication

Authentication can be handled at the Gateway level.

For example:

Client
   │
   │ JWT Token
   ↓
API Gateway
   │
   │ Validate/authorize request
   ↓
Product API

This can reduce the amount of repeated gateway-level logic across services.

However, in a production system, backend services should still enforce their own authorization and trust boundaries rather than assuming that the Gateway alone provides security.

4. Centralized Rate Limiting

Suppose a client sends thousands of requests.

The Gateway can apply rate-limiting policies before requests reach your backend services.

Client
   │
   │ 10,000 requests
   ↓
API Gateway
   │
   │ Rate limit
   ↓
Backend APIs

This can help protect your services.

Creating an Ocelot API Gateway

Let's build a simple example.

We'll assume you already have the .NET SDK installed.

You can check it with:

dotnet --version

Step 1: Create an ASP.NET Core Project

Create a new Web API project:

dotnet new webapi -n ApiGateway

Move into the project:

cd ApiGateway

Step 2: Install Ocelot

Install the Ocelot NuGet package:

dotnet add package Ocelot

After installing it, restore the packages:

dotnet restore

Step 3: Create the Ocelot Configuration File

Ocelot needs to know where requests should be sent.

We'll create a file called:

ocelot.json

Add it to the project root.

For example:

ApiGateway
│
├── Program.cs
├── ApiGateway.csproj
├── appsettings.json
└── ocelot.json

Step 4: Configure a Route

Let's assume our Product API is running at:

http://localhost:5002

We want the Gateway to expose:

/products

Create the following configuration:

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/products",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 5002
        }
      ],
      "UpstreamPathTemplate": "/products",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:5000"
  }
}

Don't worry if this looks confusing.

Let's understand each property.

Understanding Ocelot Configuration

UpstreamPathTemplate

"UpstreamPathTemplate": "/products"

Upstream means the request coming into the Gateway.

So the client calls:

GET /products

DownstreamPathTemplate

"DownstreamPathTemplate": "/api/products"

Downstream means the request going from the Gateway to your backend service.

So Ocelot forwards:

/products

to:

/api/products

DownstreamHostAndPorts

"DownstreamHostAndPorts": [
  {
    "Host": "localhost",
    "Port": 5002
  }
]

This tells Ocelot where the backend API is located.

In this example:

localhost:5002

DownstreamScheme

"DownstreamScheme": "http"

This specifies the protocol used to communicate with the downstream service.

For example:

http

or:

https

UpstreamHttpMethod

"UpstreamHttpMethod": [ "GET" ]

This tells Ocelot that this route accepts a GET request.

For example:

GET /products

will match the route.

Step 5: Configure Program.cs

Now we need to tell ASP.NET Core to use Ocelot.

For a minimal hosting model, your Program.cs can look like this:

using Ocelot.DependencyInjection;
using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile(
    "ocelot.json",
    optional: false,
    reloadOnChange: true);

builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

await app.UseOcelot();

app.Run();

That's the basic Ocelot setup.

Let's understand what is happening.

What Does AddOcelot Do?

This line:

builder.Services.AddOcelot(builder.Configuration);

registers Ocelot with the ASP.NET Core dependency injection system.

It tells the application:

I want to use Ocelot as part of this application.

What Does UseOcelot Do?

This line:

await app.UseOcelot();

adds Ocelot's middleware to the request pipeline.

When a request arrives, Ocelot gets the opportunity to process it.

For example:

GET /products
       │
       ▼
   Ocelot Middleware
       │
       ▼
http://localhost:5002/api/products

Step 6: Make Sure ocelot.json Is Copied

Depending on your project configuration, make sure ocelot.json is available when the application runs.

You can add this to your .csproj file if needed:

<ItemGroup>
  <None Update="ocelot.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

This ensures the configuration file is copied to the output directory.

Step 7: Run the Gateway

Start the Gateway:

dotnet run

Let's assume it starts on:

http://localhost:5000

Now call:

GET http://localhost:5000/products

Ocelot receives the request.

It looks at ocelot.json.

It finds this route:

/products

Then it forwards the request to:

http://localhost:5002/api/products

The flow is:

GET /products
     │
     ▼
┌──────────────┐
│ API Gateway  │
│   Ocelot     │
└──────┬───────┘
       │
       │ forwards
       ▼
┌──────────────────────┐
│ Product API          │
│ /api/products        │
│ localhost:5002       │
└──────────────────────┘

The response then travels back through the Gateway to the client.

Adding More APIs

Now let's say we have an Order API running on:

http://localhost:5003

We can add another route.

Our ocelot.json could look like this:

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/products",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 5002
        }
      ],
      "UpstreamPathTemplate": "/products",
      "UpstreamHttpMethod": [ "GET" ]
    },
    {
      "DownstreamPathTemplate": "/api/orders",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 5003
        }
      ],
      "UpstreamPathTemplate": "/orders",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:5000"
  }
}

Now we have:

GET /products
     ↓
Product API :5002

GET /orders
     ↓
Order API :5003

The frontend still communicates with only:

API Gateway :5000

POST, PUT and DELETE Routes

Ocelot isn't limited to GET requests.

For example, suppose we want to create a product.

We can configure:

{
  "DownstreamPathTemplate": "/api/products",
  "DownstreamScheme": "http",
  "DownstreamHostAndPorts": [
    {
      "Host": "localhost",
      "Port": 5002
    }
  ],
  "UpstreamPathTemplate": "/products",
  "UpstreamHttpMethod": [ "POST" ]
}

Now:

POST /products

can be forwarded to:

POST /api/products

Similarly, you can configure routes for:

GET
POST
PUT
PATCH
DELETE

depending on what your backend API supports.

Understanding Upstream vs Downstream

This is one of the most important concepts to understand when learning Ocelot.

Remember:

Upstream

Request coming into the Gateway.

Client → Gateway

Example:

/products

Downstream

Request going from the Gateway to the service.

Gateway → Product API

Example:

/api/products

Think about it like this:

              UPSTREAM
Client ─────────────────────► Gateway
                                  │
                                  │
                                  ▼
                            DOWNSTREAM
                              Product API

If you remember only one thing about Ocelot routing, remember:

Upstream = client-facing route
Downstream = backend service route

Routing with Route Parameters

You can also use route parameters.

Suppose the Product API has:

GET /api/products/10

We can expose:

GET /products/10

using:

{
  "DownstreamPathTemplate": "/api/products/{productId}",
  "DownstreamScheme": "http",
  "DownstreamHostAndPorts": [
    {
      "Host": "localhost",
      "Port": 5002
    }
  ],
  "UpstreamPathTemplate": "/products/{productId}",
  "UpstreamHttpMethod": [ "GET" ]
}

Now:

GET /products/10

gets forwarded as:

GET /api/products/10

The {productId} value is passed through.

API Gateway with Authentication

Another common requirement is authentication.

For example, your application may use JWT authentication.

The request could look like:

Client
  │
  │ Authorization: Bearer <token>
  ▼
API Gateway
  │
  │ authenticated request
  ▼
Product API

Ocelot can integrate with ASP.NET Core authentication and authorization.

The exact configuration depends on your authentication provider and Ocelot version, but conceptually the Gateway can protect routes such as:

/products
/orders
/payments

while leaving public routes such as:

/login
/register

available without authentication.

API Gateway Is More Than Just Routing

At first, it is useful to think of Ocelot as a router.

But an API Gateway can become an important part of your architecture.

For example:

                    Client
                      │
                      ▼
              ┌───────────────┐
              │ API Gateway   │
              │    Ocelot     │
              └───────┬───────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
        ▼             ▼             ▼
     User API     Product API    Order API

The Gateway can provide capabilities around:

Routing
Authentication
Authorization
Rate limiting
Load balancing
Logging
Monitoring
Request transformation
Service discovery

But you don't necessarily need all of these features on day one.

Start with routing.

API Gateway vs Reverse Proxy

As a beginner, you may hear another term: reverse proxy.

They are related, but not exactly the same concept.

A reverse proxy generally receives requests and forwards them to backend servers.

An API Gateway is more focused on APIs and can provide additional API-specific capabilities such as:

Authentication
Authorization
Rate limiting
Request transformation
API composition
Service discovery

Ocelot is commonly used as an API Gateway in .NET-based architectures.

API Gateway vs Load Balancer

These concepts can also overlap.

A load balancer primarily distributes traffic across multiple backend instances.

For example:

             Load Balancer
              /    |    \
             /     |     \
          API 1   API 2   API 3

An API Gateway can also perform load balancing in appropriate architectures, but its responsibilities can be broader.

For example:

                 API Gateway
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
    Routing       Security      Rate Limit
        │
        ▼
   Backend APIs

So don't think of an API Gateway as simply another name for a load balancer.

A Real-World Example

Imagine an e-commerce application.

We have:

User Service
Product Service
Order Service
Payment Service
Notification Service

Without a Gateway:

Mobile App
   │
   ├── User Service
   ├── Product Service
   ├── Order Service
   ├── Payment Service
   └── Notification Service

With an API Gateway:

                  Mobile App
                      │
                      ▼
               ┌─────────────┐
               │ API Gateway │
               │   Ocelot    │
               └──────┬──────┘
                      │
       ┌──────────────┼───────────────┐
       │              │               │
       ▼              ▼               ▼
   User Service  Product Service  Order Service
                                      │
                                      ▼
                               Payment Service

The mobile application doesn't need to understand the internal architecture.

It only needs to know the Gateway.

For example:

GET /users/10
GET /products
GET /orders/100
POST /orders

Ocelot decides where those requests should go.

Common Beginner Mistakes

Mistake 1: Confusing Upstream and Downstream

Remember:

Upstream   = Client → Gateway
Downstream = Gateway → Service

Mistake 2: Thinking the Gateway Contains Business Logic

The API Gateway generally shouldn't contain your application's core business logic.

For example, calculating an order's business rules should normally belong to the Order service, not the Gateway.

The Gateway should primarily coordinate communication and cross-cutting concerns.

Mistake 3: Exposing Every Internal API

One purpose of a Gateway is to provide a controlled entry point.

You don't necessarily need to expose every internal service directly to external clients.

Mistake 4: Putting Everything in the Gateway

An API Gateway can become a bottleneck if you keep adding business logic and application-specific responsibilities to it.

A good rule is:

Keep the Gateway focused on traffic management and cross-cutting concerns.

When Should You Use an API Gateway?

You may want an API Gateway when:

You have multiple backend services.
You are building a microservices architecture.
Multiple clients need to access your services.
You want a single public API endpoint.
You need centralized API-level concerns such as routing or rate limiting.
You want to hide internal service locations from clients.

For a simple application with one Web API, introducing an API Gateway may add unnecessary complexity.

Ocelot Request Flow

Let's summarize everything with one diagram.

                    Client
                       │
                       │ GET /products
                       ▼
              ┌──────────────────┐
              │   API Gateway    │
              │      Ocelot      │
              └────────┬─────────┘
                       │
                       │ Reads ocelot.json
                       │
                       ▼
              ┌──────────────────┐
              │ Route Matching   │
              └────────┬─────────┘
                       │
                       │ /products
                       ▼
              ┌──────────────────┐
              │ Product API      │
              │ :5002            │
              │ /api/products    │
              └────────┬─────────┘
                       │
                       │ Response
                       ▼
              ┌──────────────────┐
              │   API Gateway    │
              └────────┬─────────┘
                       │
                       ▼
                    Client

This is the fundamental idea behind Ocelot.

Complete Minimal Example

For reference, our basic Gateway consists of two important files.

Program.cs

using Ocelot.DependencyInjection;
using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile(
    "ocelot.json",
    optional: false,
    reloadOnChange: true);

builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

await app.UseOcelot();

app.Run();

ocelot.json

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/products",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 5002
        }
      ],
      "UpstreamPathTemplate": "/products",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:5000"
  }
}

That's enough to understand the basic Ocelot Gateway concept.

Conclusion

An API Gateway is essentially a single entry point between clients and backend services.

Instead of your frontend communicating directly with many services:

Frontend → User API
Frontend → Product API
Frontend → Order API

you can use:

Frontend
    │
    ▼
API Gateway
    │
    ├── User API
    ├── Product API
    └── Order API

Ocelot makes it relatively straightforward to implement this pattern in ASP.NET Core.

The most important concepts to remember are:

API Gateway = single entry point for clients.
Ocelot = a .NET API Gateway framework.
Upstream = the route exposed by the Gateway.
Downstream = the backend service that receives the request.
ocelot.json = where Ocelot routing configuration is defined.
AddOcelot() = registers Ocelot.
UseOcelot() = adds Ocelot to the request pipeline.

Once you understand routing, you can move on to more advanced topics such as JWT authentication, authorization, rate limiting, load balancing, service discovery, request aggregation, Docker, and Kubernetes.

The key idea is simple:

The client talks to the Gateway. The Gateway talks to the services.

How Do You Delete Billions of WhatsApp Statuses Every Day Without Bringing Your Database to Its Knees?

Ravi Vishwakarma — Sat, 22 Aug 2026 17:55:29 +0000

Imagine you run a messaging app used by billions of people.

Every day, people upload photos, videos, and text as Status updates. But there is one important rule: a Status should disappear after about 24 hours.

Now imagine you have to clean up billions of expired Statuses every day.

Your first thought might be:

“Easy. Just run a query that deletes everything older than 24 hours.”

Something like:

DELETE FROM statuses
WHERE expires_at < NOW();

Simple, right?

Unfortunately, at WhatsApp's scale, this can be a terrible idea.

A giant delete can put enormous pressure on the database, causing slow queries, high disk usage, replication delays, locks, and even outages.

So how do large systems actually approach this problem?

Let's understand it from the ground up.

1. First: What Is a WhatsApp Status?

A Status is basically a temporary piece of content.

For example:

Alice posts a photo at 10:00 AM.
Bob posts a video at 2:00 PM.
Carol posts some text at 8:00 PM.

After roughly 24 hours, these Statuses are no longer supposed to be visible.

From a database perspective, you might store something like:

status_id	user_id	content	created_at	expires_at
101	Alice	photo.jpg	10:00	10:00 next day
102	Bob	video.mp4	14:00	14:00 next day
103	Carol	"Hello!"	20:00	20:00 next day

The database now has a simple job:

Find expired records and remove them.

But there's a catch.

At massive scale, there can be an enormous number of expired records.

2. Why Can't We Just Delete Everything at Once?

Suppose there are 1 billion expired records.

You might write:

DELETE FROM statuses
WHERE expires_at < NOW();

The database now has to find and delete a huge number of rows.

That can cause several problems.

Problem #1: Huge amount of work

Deleting a row isn't always as simple as removing a line from a file.

The database may need to:

Locate the row.
Modify indexes.
Write transaction information.
Update storage structures.
Replicate the changes.
Eventually reclaim the space.

Multiply that by billions.

That's a lot of work.

3. The Database Has Other Jobs Too

This is perhaps the most important idea for beginners.

Your database isn't sitting around waiting for the cleanup job.

While the cleanup system is deleting old Statuses, users are still:

uploading new Statuses,
viewing Statuses,
sending messages,
opening chats,
checking contacts.

The database needs to handle those requests too.

Think of a restaurant.

Imagine a restaurant has one kitchen.

During dinner, hundreds of customers are ordering food.

Now someone says:

“Before serving any more customers, let's completely clean the kitchen.”

The kitchen might become extremely busy cleaning instead of cooking.

A massive database deletion can create a similar problem.

4. The Basic Solution: Delete in Small Batches

Instead of deleting one billion rows in one operation, divide the work into small pieces.

For example:

DELETE FROM statuses
WHERE expires_at < NOW()
LIMIT 10,000;

Then repeat.

Conceptually:

Delete 10,000
       ↓
Delete 10,000
       ↓
Delete 10,000
       ↓
Delete 10,000
       ↓
...

Now the database gets many small jobs instead of one enormous job.

This is called batch deletion.

5. Why Batches Are Better

Suppose you need to remove 100 million records.

Instead of:

100,000,000 rows
       ↓
ONE MASSIVE DELETE
       ↓
Database suffers

you could do:

10,000 rows
10,000 rows
10,000 rows
10,000 rows
...

Each transaction is relatively small.

That means:

transactions finish faster,
locks are held for less time,
memory pressure is lower,
replication can keep up more easily,
other queries get opportunities to run.

The goal isn't merely to delete data.

The goal is to delete data without disturbing the rest of the system.

6. But There's Another Problem

You might now say:

“Fine. We'll delete 10,000 rows at a time.”

But how do we find those 10,000 expired rows?

Suppose the table looks like this:

statuses
--------------------------------
id
user_id
content
created_at
expires_at

If expires_at isn't indexed, the database may have to scan a huge portion of the table to discover which rows are expired.

That's expensive.

So we usually want an index.

For example:

CREATE INDEX idx_status_expiry
ON statuses(expires_at);

Now the database can efficiently find records whose expiration time has passed.

Think of an index like the index at the back of a textbook.

Without the index, you might have to read every page to find a topic.

With the index, you can jump closer to where the information lives.

7. Don't Delete Randomly — Delete in Order

There's another optimization.

Suppose expired records have IDs:

Instead of repeatedly asking:

“Give me any 10,000 expired rows.”

we can process them in a predictable order.

For example:

DELETE FROM statuses
WHERE expires_at < NOW()
ORDER BY expires_at
LIMIT 10,000;

Or, in some database designs, we can use an ID/cursor-based approach.

Conceptually:

Start at record 0
       ↓
Process 10,000
       ↓
Remember where we stopped
       ↓
Process the next 10,000
       ↓
Repeat

This is often called cursor-based processing or keyset pagination.

8. The Secret Weapon: Don't Wake Up Every Millisecond

Here's another beginner mistake.

You might create a worker that constantly asks:

"Anything expired?"
"Anything expired?"
"Anything expired?"
"Anything expired?"
...

That's unnecessary.

Instead, a cleanup system can work on a schedule.

For example:

12:00 → clean expired data
12:01 → clean expired data
12:02 → clean expired data
...

Or it can continuously process a queue at a controlled rate.

The important concept is backpressure.

9. What Is Backpressure?

Backpressure simply means:

Slow down when the database is under heavy load.

Imagine your cleanup worker can delete 100,000 records per second.

But the database is already extremely busy.

Instead of saying:

“I must delete 100,000 per second!”

the cleanup system can say:

“The database is busy. I'll reduce my deletion rate.”

For example:

Database healthy
→ delete faster

Database busy
→ delete slower

Database overloaded
→ pause cleanup temporarily

This is extremely useful in large distributed systems.

Cleanup is important.

But serving users is usually more important.

10. Even Better: Use a Queue

Instead of having one giant cleanup process constantly scanning the database, you can use a queue.

Imagine every Status gets an expiration event.

When Alice creates a Status:

Alice creates Status
        ↓
Status expires in 24 hours
        ↓
Create expiration task
        ↓
Queue

Later:

Queue
 ↓
Worker
 ↓
Delete Status

You can have many workers processing the queue.

For example:

                 ┌── Worker 1
Queue ───────────┼── Worker 2
                 ├── Worker 3
                 └── Worker 4

Now cleanup can scale horizontally.

Need more capacity?

Add more workers.

Need less capacity?

Remove workers.

11. But What If a Worker Crashes?

Distributed systems assume something will eventually fail.

A worker might crash halfway through its work.

That's why cleanup jobs should generally be idempotent.

Don't worry about the fancy word.

It basically means:

Running the same cleanup operation again should not cause a disaster.

For example:

Delete Status 123

If Status 123 is already gone, trying to delete it again shouldn't break the system.

This makes retries much safer.

12. A Very Important Idea: Soft Delete vs Hard Delete

There are actually two different meanings of "delete."

Soft delete

Instead of physically removing the row, mark it as deleted:

deleted = true

The application simply ignores deleted records.

Hard delete

Actually remove the database record.

For example:

DELETE FROM statuses
WHERE id = 123;

Large systems may sometimes use a combination of both approaches.

For example:

Status expires
      ↓
Immediately stop showing it
      ↓
Physical cleanup happens later

This is useful because the user-facing requirement is:

“Don't show expired content.”

It doesn't necessarily mean:

“The physical database bytes must disappear at exactly 24:00:00.”

Those are two different requirements.

13. This Difference Is Huge

Suppose a Status expires at:

10:00:00

The application can immediately treat it as unavailable:

expires_at <= current_time

So the user can't see it anymore.

The physical deletion might happen at:

depending on system load.

That's often perfectly acceptable.

This gives the cleanup system flexibility.

14. What About Photos and Videos?

There's another important detail.

The database might not actually contain the entire photo or video.

A database record might simply contain metadata:

status_id
user_id
storage_location
created_at
expires_at

The actual video could live in an object-storage system.

So deleting a Status may involve multiple steps:

Database record
      +
Media object
      +
Caches
      +
Indexes
      +
Metadata

You need to make sure all of these eventually get cleaned up.

15. Don't Delete Everything at the Exact Expiration Time

Here's a subtle but important design idea.

Imagine 100 million people uploaded Statuses between 10:00 AM and 10:01 AM.

Twenty-four hours later, a huge number of objects become eligible for deletion at roughly the same time.

If your system tries to delete all of them immediately, you get a thundering herd.

Instead, you can spread the cleanup work out.

For example:

10:00 → 100,000 deletions
10:01 → 100,000 deletions
10:02 → 100,000 deletions
...

The work is distributed over time.

This makes the system much smoother.

16. Partitioning Can Help Too

At very large scale, a single enormous table can become difficult to manage.

One technique is partitioning.

Imagine splitting Status data by time:

statuses_2026_08_20
statuses_2026_08_21
statuses_2026_08_22
statuses_2026_08_23

Now old data is grouped together.

Instead of deleting billions of individual rows one by one, a database may be able to remove or detach an entire old partition.

Conceptually:

Old partition
      ↓
No longer needed
      ↓
Drop partition
      ↓
Large amount of data removed efficiently

This can be dramatically cheaper than row-by-row deletion, depending on the database architecture.

However, partitioning isn't a magic solution. It has its own design and operational trade-offs.

17. A Realistic Architecture

A simplified large-scale design might look like this:

              User creates Status
                       │
                       ▼
                 Status Service
                       │
             ┌─────────┴─────────┐
             ▼                   ▼
        Database             Media Storage
             │
             ▼
      Expiration Scheduler
             │
             ▼
       Cleanup Queue
             │
       ┌─────┼─────┐
       ▼     ▼     ▼
    Worker Worker Worker
       │     │     │
       └─────┼─────┘
             ▼
        Batch Delete

The key idea is that expiration and physical deletion are separate concerns.

18. What Happens If the Database Is Overloaded?

A good cleanup system should be able to say:

“Not now.”

For example:

Cleanup worker
      ↓
Check database health
      ↓
Is database overloaded?
   /          \
 Yes           No
  ↓             ↓
Slow down    Continue
or pause     deleting

This is a crucial production principle:

Background work should be a good citizen.

User-facing traffic gets priority.

Cleanup can wait.

19. Monitoring Is Just as Important

You don't want to build the cleanup system and forget about it.

You need metrics.

For example:

Expired items waiting

50 million

Cleanup rate

200,000 items/sec

Database CPU

45%

Queue size

2 million jobs

Cleanup latency

Average: 3 minutes

Now you can see whether the system is keeping up.

20. What If Cleanup Falls Behind?

Suppose:

New expired Statuses:
1 billion/day

Cleanup capacity:
800 million/day

You're losing the race.

The queue will grow forever.

So the system needs to scale.

Possible solutions include:

increase worker count,
increase batch size carefully,
optimize indexes,
partition the data,
move cleanup to replicas or specialized stores where appropriate,
spread work over a longer window,
improve storage architecture.

The important thing is to measure the system instead of guessing.

21. The Beginner's Mental Model

You don't need to understand every database engine to understand the core idea.

Think of expired Statuses as garbage.

Imagine a city produces billions of pieces of garbage every day.

You wouldn't wait until the end of the month and tell one truck:

“Collect everything.”

You'd probably use:

many trucks,
scheduled pickups,
different neighborhoods,
manageable loads,
monitoring,
extra capacity during busy periods.

Database cleanup works in a similar way.

Don't create one giant cleanup operation. Build a controlled garbage-collection system.

22. The Big Lessons

If you remember only a few things, remember these:

1. Don't perform gigantic deletes

Break the work into batches.

10,000
10,000
10,000
...

2. Make finding expired data cheap

Indexes on expiration-related fields can be important.

3. Don't block user traffic

Cleanup should run as background work.

4. Use queues and workers when appropriate

They allow cleanup to scale horizontally.

5. Use backpressure

When the database is busy, slow down.

6. Consider partitioning

Time-based data can sometimes be efficiently managed through partitions.

7. Separate logical expiration from physical deletion

A Status can stop being visible immediately while physical cleanup happens later.

8. Make cleanup retry-safe

Failures are normal in distributed systems.

9. Monitor everything

Know how much data is waiting and how quickly you're processing it.

Final Picture

So, how can a service like WhatsApp deal with billions of temporary Statuses?

The answer isn't one magical SQL query.

It's an architecture.

Instead of:

Billions of expired records
          ↓
     ONE DELETE
          ↓
     💥 Database

you want something closer to:

              Expired Statuses
                     │
                     ▼
              Cleanup Queue
                     │
          ┌──────────┼──────────┐
          ▼          ▼          ▼
       Worker      Worker      Worker
          │          │          │
          └──────────┼──────────┘
                     ▼
               Small Batches
                     │
                     ▼
              Database / Storage

The trick is not to make the database delete billions of things instantly.

The trick is to make the system continuously and safely remove expired data at a controlled rate.

That's one of the fundamental lessons of large-scale backend engineering:

At massive scale, the question isn't just “Can we do this?” It's “Can we do this continuously without hurting everything else?”

Optimistic and Pessimistic Locking in .NET with SQL Server

Ravi Vishwakarma — Sat, 22 Aug 2026 14:31:54 +0000

When multiple users access the same application at the same time, they may also try to read or update the same database record.

For example:

User A opens a product and changes its price.
User B opens the same product at the same time and also changes its price.
Both users click Save.

What happens?

Without a strategy to handle concurrent updates, one user's changes may silently overwrite the other's. This is where concurrency control and database locking strategies become important.

Two common approaches are:

Optimistic locking
Pessimistic locking

In this article, we'll learn both approaches using .NET and SQL Server, with beginner-friendly examples and commented code.

What Problem Are We Trying to Solve?

Imagine we have a simple Products table.

CREATE TABLE Products
(
    Id INT PRIMARY KEY,
    Name NVARCHAR(100),
    Price DECIMAL(10, 2)
);

The table contains this record:

Id	Name	Price
1	Laptop	50000

Now imagine two users open this product at exactly the same time.

User A

Reads:

Laptop - ₹50,000

User A changes the price to:

₹55,000

User B

At the same time, User B also reads:

Laptop - ₹50,000

User B changes the price to:

₹48,000

If User A saves first and User B saves afterward, User B's update may overwrite User A's change.

This is often called a lost update problem.

We need a way to detect or prevent this conflict.

1. What Is Optimistic Locking?

Optimistic locking assumes that conflicts are rare.

The basic idea is:

"Let everyone read and work with the data. When someone tries to save, check whether the data has changed since they originally read it."

If the data has not changed, the update succeeds.

If the data has changed, the application detects a concurrency conflict.

How Does It Work?

A common approach is to add a rowversion column to the SQL Server table.

CREATE TABLE Products
(
    Id INT PRIMARY KEY,
    Name NVARCHAR(100),
    Price DECIMAL(10, 2),

    -- SQL Server automatically changes this value
    -- whenever the row is updated.
    RowVersion ROWVERSION NOT NULL
);

The RowVersion column acts like a version identifier for the row.

For example:

Product before update:

Id: 1
Price: 50000
RowVersion: 0x00000000000007D1

When the product is updated, SQL Server changes the RowVersion.

Product after update:

Id: 1
Price: 55000
RowVersion: 0x00000000000007D2

Now, when a user attempts to update the record, we can check whether the version they originally read is still the current version.

Optimistic Locking with ADO.NET

First, let's create a simple C# model.

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

    public string Name { get; set; } = string.Empty;

    public decimal Price { get; set; }

    // This stores the row version returned by SQL Server.
    // It helps us detect whether another user changed the row.
    public byte[] RowVersion { get; set; } = Array.Empty<byte>();
}

Step 1: Read the Product

using Microsoft.Data.SqlClient;

public async Task<Product?> GetProductAsync(int id)
{
    // Replace this with your actual connection string.
    var connectionString =
        "Server=.;Database=ShopDb;Trusted_Connection=True;TrustServerCertificate=True;";

    await using var connection =
        new SqlConnection(connectionString);

    await connection.OpenAsync();

    var sql = @"
        SELECT Id, Name, Price, RowVersion
        FROM Products
        WHERE Id = @Id";

    await using var command =
        new SqlCommand(sql, connection);

    // Use parameters instead of string concatenation.
    command.Parameters.AddWithValue("@Id", id);

    await using var reader =
        await command.ExecuteReaderAsync();

    if (!await reader.ReadAsync())
    {
        return null;
    }

    return new Product
    {
        Id = reader.GetInt32(0),
        Name = reader.GetString(1),
        Price = reader.GetDecimal(2),

        // Save the row version that existed when we read the record.
        RowVersion = (byte[])reader["RowVersion"]
    };
}

When the user loads the product, we also store its current RowVersion.

Later, when the user clicks Save, we use that version in the UPDATE statement.

Step 2: Update the Product Safely

public async Task<bool> UpdateProductAsync(Product product)
{
    var connectionString =
        "Server=.;Database=ShopDb;Trusted_Connection=True;TrustServerCertificate=True;";

    await using var connection =
        new SqlConnection(connectionString);

    await connection.OpenAsync();

    var sql = @"
        UPDATE Products
        SET
            Name = @Name,
            Price = @Price
        WHERE
            Id = @Id

            -- Only update if the row version is still the same
            -- as when the user originally read the record.
            AND RowVersion = @RowVersion";

    await using var command =
        new SqlCommand(sql, connection);

    command.Parameters.AddWithValue("@Id", product.Id);
    command.Parameters.AddWithValue("@Name", product.Name);
    command.Parameters.AddWithValue("@Price", product.Price);
    command.Parameters.Add("@RowVersion", System.Data.SqlDbType.Timestamp)
        .Value = product.RowVersion;

    // ExecuteNonQueryAsync returns the number of affected rows.
    var affectedRows = await command.ExecuteNonQueryAsync();

    // If 1 row was updated, the operation succeeded.
    // If 0 rows were updated, someone may have changed
    // the record before us.
    return affectedRows == 1;
}

Now imagine this sequence:

User A reads the product

Price: 50000
RowVersion: Version 1

User B reads the product

Price: 50000
RowVersion: Version 1

User A updates the product

The product becomes:

Price: 55000
RowVersion: Version 2

User B tries to update

But User B still has:

RowVersion: Version 1

The SQL query checks:

WHERE Id = @Id
AND RowVersion = @RowVersion

Since the database now contains Version 2, no row matches the condition.

Therefore:

affectedRows = 0

The application can now tell User B:

"This product was modified by another user. Please reload the latest data and try again."

That is optimistic locking.

Optimistic Locking with Entity Framework Core

Entity Framework Core makes optimistic concurrency easier.

First, create the model:

using System.ComponentModel.DataAnnotations;

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

    public string Name { get; set; } = string.Empty;

    public decimal Price { get; set; }

    // [Timestamp] tells EF Core that this property
    // should be used for optimistic concurrency checking.
    [Timestamp]
    public byte[] RowVersion { get; set; } = Array.Empty<byte>();
}

You can also configure it using Fluent API:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Product>()
        .Property(p => p.RowVersion)
        .IsRowVersion();
}

When EF Core detects that another user changed the row before SaveChangesAsync(), it can throw a concurrency exception.

try
{
    // Get the product.
    var product = await _context.Products.FindAsync(1);

    if (product == null)
    {
        return;
    }

    // Change the price.
    product.Price = 55000;

    // EF Core generates an UPDATE statement that checks
    // the original concurrency value.
    await _context.SaveChangesAsync();

    Console.WriteLine("Product updated successfully.");
}
catch (DbUpdateConcurrencyException)
{
    // This happens when another user changed or deleted
    // the record before our update was completed.
    Console.WriteLine(
        "The product was modified by another user. " +
        "Reload the latest data and try again.");
}

This is one reason rowversion is commonly used with EF Core applications.

Advantages of Optimistic Locking

Optimistic locking works well when conflicts are relatively uncommon.

Benefits

Users are not blocked while reading data.
Long-running locks are avoided.
It generally scales well for many read operations.
It is useful for web applications where users may keep a page open for several minutes.

Disadvantages

The application must handle concurrency conflicts.
A user may spend time editing data and then discover that another user changed it.
Users may need to reload and merge changes.

2. What Is Pessimistic Locking?

Pessimistic locking takes the opposite approach.

It assumes:

"A conflict might happen, so lock the data while it is being used."

In simple terms:

User A accesses a row.
The application places a lock on that row.
User B tries to access or modify the same row.
User B may have to wait until User A finishes and releases the lock.

The lock usually exists within a database transaction.

Pessimistic Locking Example with SQL Server

Suppose we want to reserve a product row for update.

We can use locking hints such as:

UPDLOCK

and:

ROWLOCK

For example:

SELECT *
FROM Products WITH (UPDLOCK, ROWLOCK)
WHERE Id = 1;

Let's understand these hints.

`UPDLOCK`

This requests an update lock while reading the row.

The intention is:

"I am reading this row because I plan to update it."

`ROWLOCK`

This asks SQL Server to prefer row-level locking rather than locking a larger resource.

However, it is important to understand that SQL Server manages locking internally, and locking hints are requests rather than a guarantee of a particular physical locking behavior in every situation.

Pessimistic Locking with ADO.NET

Here is a simple example.

using Microsoft.Data.SqlClient;

public async Task UpdateProductWithLockAsync(
    int productId,
    decimal newPrice)
{
    var connectionString =
        "Server=.;Database=ShopDb;Trusted_Connection=True;TrustServerCertificate=True;";

    await using var connection =
        new SqlConnection(connectionString);

    await connection.OpenAsync();

    // Start a database transaction.
    await using var transaction =
        (SqlTransaction)await connection.BeginTransactionAsync();

    try
    {
        var selectSql = @"
            SELECT Id, Name, Price
            FROM Products WITH (UPDLOCK, ROWLOCK)
            WHERE Id = @Id";

        await using var selectCommand =
            new SqlCommand(selectSql, connection, transaction);

        selectCommand.Parameters.AddWithValue("@Id", productId);

        await using var reader =
            await selectCommand.ExecuteReaderAsync();

        if (!await reader.ReadAsync())
        {
            throw new Exception("Product not found.");
        }

        // Read the current values while the transaction
        // is still holding the requested lock.
        var productName = reader.GetString(1);
        var currentPrice = reader.GetDecimal(2);

        Console.WriteLine(
            $"Current price of {productName}: {currentPrice}");

        // Close the reader before executing another command.
        await reader.CloseAsync();

        var updateSql = @"
            UPDATE Products
            SET Price = @Price
            WHERE Id = @Id";

        await using var updateCommand =
            new SqlCommand(updateSql, connection, transaction);

        updateCommand.Parameters.AddWithValue("@Id", productId);
        updateCommand.Parameters.AddWithValue("@Price", newPrice);

        await updateCommand.ExecuteNonQueryAsync();

        // Commit releases the transaction's locks.
        await transaction.CommitAsync();

        Console.WriteLine("Product updated successfully.");
    }
    catch
    {
        // If something goes wrong, undo the transaction.
        await transaction.RollbackAsync();

        throw;
    }
}

The important part is:

SELECT *
FROM Products WITH (UPDLOCK, ROWLOCK)
WHERE Id = @Id;

combined with a transaction:

await using var transaction =
    (SqlTransaction)await connection.BeginTransactionAsync();

The lock remains relevant for the transaction according to SQL Server's locking and transaction behavior, helping protect the read-then-update operation from competing modifications.

A Simple Pessimistic Locking Scenario

Imagine User A starts this transaction:

BEGIN TRANSACTION

Read Product 1 with an update lock

Update Product 1

COMMIT

While User A's transaction is still active, User B tries to perform a conflicting operation on the same data.

Depending on the operation, isolation level, and locks involved, User B may wait until User A commits or rolls back.

After User A executes:

COMMIT

the transaction completes and its locks are released.

Then User B can continue.

The Danger of Long Transactions

Pessimistic locking can cause problems if transactions stay open for too long.

For example, this is usually a bad idea:

1. Start transaction
2. Lock product
3. Wait for user to fill out a form
4. User goes for lunch
5. Commit transaction

That could cause other users to wait unnecessarily.

Instead, transactions should generally be as short as possible.

A better pattern is:

1. User fills out the form
2. Start transaction
3. Read and validate the current data
4. Update the data
5. Commit immediately

Pessimistic Locking and Deadlocks

Pessimistic locking can increase the possibility of blocking and, in some situations, deadlocks.

A deadlock can look like this:

Transaction A

Locks Product 1
Waits for Product 2

Transaction B

Locks Product 2
Waits for Product 1

Now both transactions are waiting for each other.

SQL Server detects the deadlock and chooses one transaction as the deadlock victim, rolling it back.

One useful strategy for reducing deadlocks is to access resources in a consistent order.

For example, if you always update products in ID order:

Product 1
Product 2
Product 3

rather than sometimes doing:

Product 3
Product 1

you can reduce certain deadlock scenarios.

Optimistic vs Pessimistic Locking

Feature	Optimistic Locking	Pessimistic Locking
Assumption	Conflicts are rare	Conflicts are likely or costly
Locks held while user edits	No	Usually no user-edit-duration lock; locks are held during the transaction
Conflict handling	Detect conflict during update	Block or serialize conflicting access
Scalability	Often better for read-heavy apps	Can suffer from blocking
Complexity	Requires conflict resolution	Requires careful transaction management
Best for	Web apps, normal CRUD systems	Short critical sections with high contention

Which One Should You Use?

There is no universal answer.

Use Optimistic Locking When

Choose optimistic locking when:

Many users mostly read data.
Simultaneous updates are relatively rare.
Your application can ask users to reload or resolve conflicts.
You are building a typical web application or business application.

For many CRUD applications, optimistic concurrency using SQL Server rowversion is a practical starting point.

Use Pessimistic Locking When

Consider pessimistic locking when:

Multiple processes frequently modify the same data.
Conflicting updates would be especially problematic.
You need to protect a short, critical read-modify-write operation.
Waiting is preferable to allowing concurrent conflicting work.

Examples might include certain inventory, reservation, or financial workflows—but the exact design should depend on the business rules and transaction requirements.

A Real-World Example: Booking the Last Seat

Suppose there is only one seat left.

Two users try to book it at the same time.

Optimistic Approach

Both users may initially see:

Available seats: 1

The first user successfully updates the record.

The second user's update detects that the data changed.

The second user receives a message:

"Sorry, this seat is no longer available."

Pessimistic Approach

The first transaction locks the relevant data, checks availability, and creates the booking.

A competing transaction attempting a conflicting operation may wait.

Once the first transaction completes, the next transaction checks the latest availability.

If no seat remains, it does not create a booking.

The important point is that the entire operation should be designed as a short atomic transaction.

A Safer Inventory Pattern

For inventory-like scenarios, you can often avoid a separate read followed by an update.

Instead, perform the business rule directly in the UPDATE statement.

UPDATE Products
SET Stock = Stock - 1
WHERE Id = @Id
  AND Stock > 0;

Then check how many rows were affected.

In C#:

public async Task<bool> TryBuyProductAsync(int productId)
{
    var connectionString =
        "Server=.;Database=ShopDb;Trusted_Connection=True;TrustServerCertificate=True;";

    await using var connection =
        new SqlConnection(connectionString);

    await connection.OpenAsync();

    var sql = @"
        UPDATE Products
        SET Stock = Stock - 1
        WHERE Id = @Id
          AND Stock > 0";

    await using var command =
        new SqlCommand(sql, connection);

    command.Parameters.AddWithValue("@Id", productId);

    // If affectedRows is 1, stock was available.
    // If affectedRows is 0, either the product does not exist
    // or there was no stock remaining.
    var affectedRows =
        await command.ExecuteNonQueryAsync();

    return affectedRows == 1;
}

This pattern is often simpler and safer than manually locking a row and then performing application-side logic.

A Simple Way to Remember the Difference

Think of a shared document.

Optimistic Locking

Two people can open and edit the document.

When someone saves, the system checks:

"Has somebody else changed this since you opened it?"

If yes, there is a conflict.

Pessimistic Locking

The first person effectively reserves the document for the critical operation.

Other conflicting operations may need to wait until the first person is finished.

Final Thoughts

Concurrency can initially sound complicated, but the core idea is simple:

What should happen when two users try to change the same data at the same time?

Optimistic locking says:

"Let them work independently. Detect the conflict when saving."

Pessimistic locking says:

"Protect the critical section so conflicting operations are coordinated."

For many .NET applications using SQL Server, a good starting point is optimistic concurrency with a rowversion column. It avoids holding long-running locks and works naturally with Entity Framework Core.

For operations where contention is high or correctness requires carefully coordinated access, a short transaction with appropriate locking or an atomic SQL operation may be more suitable.

The key is not simply choosing "optimistic" or "pessimistic." The best solution depends on your application's business rules, how frequently conflicts occur, and what should happen when two users attempt the same operation at the same time.

Key Takeaways

Concurrency means multiple users or processes accessing data at the same time.
Optimistic locking detects conflicts when data is updated.
SQL Server's rowversion is commonly used for optimistic concurrency.
Pessimistic locking coordinates conflicting access during a transaction.
Keep database transactions as short as possible.
Long-running locks can cause blocking and increase the risk of deadlocks.
For some scenarios, an atomic SQL statement is better than manually implementing a lock.
Always design concurrency around the actual business rule you need to protect.

Why HTTP Needed the QUERY Method

Ravi Vishwakarma — Sat, 11 Jul 2026 09:17:42 +0000

HTTP Finally Gets a New Request Method: Meet `QUERY`

For years, HTTP developers have worked with a familiar set of request methods—GET, POST, PUT, PATCH, and DELETE. These methods have served the web remarkably well, but one common problem has always been awkward to solve:

How do you send a complex query to the server without pretending it's a state-changing operation?

The answer was usually one of two compromises:

Stuff everything into a long GET URL.
Use POST even though you're only reading data.

Now, HTTP has a better answer.

With RFC 10008, the HTTP ecosystem introduces a new standardized request method: QUERY.

The Problem with GET

GET is the natural choice for retrieving data because it is:

Safe (doesn't modify server state)
Idempotent
Cache-friendly

However, GET requests carry parameters in the URL.

Imagine searching an e-commerce website with dozens of filters:

GET /products?category=laptops&brand=Dell&brand=Lenovo&priceMin=500&priceMax=1500&sort=-rating&page=3

As filters become more complex, URLs become:

Difficult to read
Hard to maintain
Limited by URL length restrictions in some environments

Even worse, expressing deeply nested filters in a query string can become nearly impossible.

Why Developers Used POST

To avoid enormous URLs, many APIs switched to:

POST /products/search
Content-Type: application/json

{
  "category": "laptops",
  "brands": ["Dell", "Lenovo"],
  "price": {
    "min": 500,
    "max": 1500
  },
  "sort": "-rating"
}

This works technically.

But semantically, it's misleading.

POST is intended for operations that may change server state, while a search is simply retrieving information.

This mismatch affects caching, retries, API documentation, and HTTP semantics.

Enter `QUERY`

The new QUERY method is designed specifically for read-only operations that require a request body.

Example:

QUERY /products
Content-Type: application/json

{
  "category": "laptops",
  "brands": ["Dell", "Lenovo"],
  "price": {
    "min": 500,
    "max": 1500
  },
  "sort": "-rating"
}

Now the intent is clear:

The client is retrieving data.
The request can include a rich JSON body.
The server promises not to modify server state.

Key Characteristics

QUERY is:

Safe
Idempotent
Designed to support a request body
Intended for complex retrieval operations

In many situations, it becomes the ideal middle ground between GET and POST.

GET vs POST vs QUERY

Feature	GET	POST	QUERY
Read data	Yes	Yes	Yes
Request body	No (not generally used)	Yes	Yes
Safe	Yes	No	Yes
Idempotent	Yes	No	Yes
Complex filters	Limited	Yes	Yes
Correct HTTP semantics	Yes	No (for reads)	Yes

Real-World Use Cases

QUERY is especially useful for:

Advanced product searches
Analytics dashboards
Business intelligence queries
Graph-style filtering
GIS and map searches
Large reporting APIs
Log search platforms
AI and vector database queries

Anywhere a client needs to send a structured query without changing data, QUERY is a natural fit.

Will It Replace POST?

Not immediately.

The web ecosystem is vast. Browsers, HTTP libraries, proxies, API gateways, CDNs, and frameworks all need to support the new method. Existing APIs that already use POST /search will likely continue to do so until support for QUERY becomes widespread.

Over time, however, new APIs may adopt QUERY to better express read-only operations.

What This Means for API Designers

For years, developers had to choose between:

Correct semantics (GET) with awkward URLs
Convenient request bodies (POST) with incorrect semantics

QUERY removes that trade-off.

When an endpoint retrieves data but requires a structured request body, developers no longer have to misuse POST.

Final Thoughts

New HTTP methods are introduced very rarely.

The introduction of PATCH was a significant milestone, and now QUERY represents another meaningful evolution of the HTTP protocol.

It is a small addition with a significant impact, making HTTP more expressive while preserving the principles that have made it successful for decades.

As support spreads across frameworks, servers, proxies, and client libraries, QUERY has the potential to become the standard choice for complex, read-only operations.

HTTP doesn't evolve often, but when it does, it's worth paying attention.

Building a Live Data Dashboard with Angular and ASP.NET Core: A Complete Step-by-Step Guide (Beginner to Advanced)

Ravi Vishwakarma — Tue, 30 Jun 2026 06:39:12 +0000

Learn how to build a real-time, live-updating data dashboard using Angular on the frontend and ASP.NET Core with SignalR on the backend. This guide walks through every step — from project setup to production deployment — with full code examples, best practices, and SEO-friendly structure for your own blog or documentation.

Introduction
What You Will Build
Prerequisites
Understanding the Architecture
Part 1 (Beginner): Setting Up the ASP.NET Core Backend
Part 2 (Beginner): Adding SignalR for Real-Time Communication
Part 3 (Beginner): Setting Up the Angular Frontend
Part 4 (Intermediate): Connecting Angular to SignalR
Part 5 (Intermediate): Building the Dashboard UI with Live Charts
Part 6 (Intermediate): Styling the Dashboard
Part 7 (Advanced): Handling Reconnection and Error States
Part 8 (Advanced): Adding Authentication with JWT
Part 9 (Advanced): Scaling SignalR with Redis Backplane
Part 10 (Advanced): Performance Optimization
Part 11 (Advanced): Testing the Application
Part 12 (Advanced): Deploying to Production
Common Errors and Troubleshooting
Best Practices Checklist
Frequently Asked Questions (FAQ)
Conclusion

1. Introduction

Real-time dashboards have become a core requirement in modern web applications — whether you're tracking stock prices, monitoring IoT sensor data, displaying server health metrics, or showing live sales numbers. Instead of forcing users to refresh a page to see updated data, a live data dashboard pushes new information to the browser the moment it becomes available.

In this guide, you will learn how to build a complete live data dashboard using two of the most popular technologies in the enterprise web development world: Angular for the frontend and ASP.NET Core for the backend, connected through SignalR, Microsoft's real-time communication library.

This tutorial is structured to take you from absolute beginner concepts all the way to advanced, production-ready practices including authentication, scaling, and deployment. Whether you are a student building your first real-time app or a professional developer architecting a production dashboard, this guide has something for you.

2. What You Will Build

By the end of this tutorial, you will have a fully functional application consisting of:

An ASP.NET Core Web API backend that generates and broadcasts live data (for example, simulated stock prices, server metrics, or sensor readings).
A SignalR Hub that pushes updates to connected clients instantly, without polling.
An Angular application that connects to the SignalR hub and updates its UI in real time.
Live charts built with a charting library (Chart.js or ngx-charts) that animate as new data arrives.
JWT authentication to secure the dashboard so only logged-in users can view live data.
A production deployment setup using Docker and IIS/Azure.

3. Prerequisites

Before starting, make sure you have the following installed and a basic understanding of these technologies.

Software Requirements

Node.js (LTS version) and npm
Angular CLI (npm install -g @angular/cli)
.NET SDK (latest LTS version of .NET)
Visual Studio Code or Visual Studio 2022
Git for version control
(Optional, for advanced sections) Docker Desktop and a Redis instance

Knowledge Requirements

Basic understanding of TypeScript and Angular components/services
Basic understanding of C# and ASP.NET Core controllers
Familiarity with REST APIs (helpful but not mandatory)

If you are completely new to Angular or ASP.NET Core, don't worry — each step includes explanations of why we are doing something, not just how.

4. Understanding the Architecture

Before writing any code, it's important to understand how the pieces fit together.

 ┌─────────────────────┐         WebSocket / SignalR        ┌──────────────────────┐
 │                      │ <---------------------------------> │                      │
 │   Angular Frontend   │                                     │  ASP.NET Core Backend│
 │  (Dashboard UI +     │         REST API (initial data)     │  (Web API + SignalR  │
 │   SignalR Client)    │ <---------------------------------- │   Hub + Data Service)│
 │                      │                                     │                      │
 └─────────────────────┘                                     └──────────────────────┘
                                                                         │
                                                                         ▼
                                                              ┌──────────────────────┐
                                                              │  Data Source (DB,    │
                                                              │  IoT feed, simulated │
                                                              │  data generator, etc)│
                                                              └──────────────────────┘

Key concept: Instead of the Angular app repeatedly calling an API (polling) every few seconds to check for new data, the ASP.NET Core backend uses SignalR to push data directly to connected clients over a persistent WebSocket connection. This is far more efficient and provides true real-time updates.

We will use a REST API call for the initial page load (to get historical/starting data) and SignalR for all subsequent live updates.

5. Part 1 (Beginner): Setting Up the ASP.NET Core Backend

Step 1.1: Create the Web API Project

Open your terminal and run:

dotnet new webapi -n LiveDashboard.Api
cd LiveDashboard.Api

This creates a new ASP.NET Core Web API project. If you're prompted to choose between minimal APIs and controllers, this guide uses controllers for clarity, but the concepts apply equally to minimal API style.

Step 1.2: Project Structure

Organize your project with the following folders for clarity as the app grows:

LiveDashboard.Api/
 ├── Controllers/
 ├── Hubs/
 ├── Models/
 ├── Services/
 ├── Program.cs
 └── appsettings.json

Create these folders inside your project directory.

Step 1.3: Define the Data Model

Create Models/MetricData.cs:

namespace LiveDashboard.Api.Models
{
    public class MetricData
    {
        public string MetricName { get; set; } = string.Empty;
        public double Value { get; set; }
        public DateTime Timestamp { get; set; }
    }
}

This simple model represents a single data point — for example, a CPU usage percentage, a stock price, or a temperature reading.

Step 1.4: Create a Simulated Data Service

In a real application, this data might come from a database, a message queue, or an external API. For this tutorial, we'll simulate live data so you can see the dashboard working immediately.

Create Services/DataGeneratorService.cs:

using LiveDashboard.Api.Models;

namespace LiveDashboard.Api.Services
{
    public class DataGeneratorService
    {
        private readonly Random _random = new();

        public MetricData GenerateMetric(string metricName, double baseValue, double variance)
        {
            var change = (_random.NextDouble() * 2 - 1) * variance;
            return new MetricData
            {
                MetricName = metricName,
                Value = Math.Round(baseValue + change, 2),
                Timestamp = DateTime.UtcNow
            };
        }
    }
}

builder.Services.AddSingleton<DataGeneratorService>();

Step 1.5: Create a Basic REST Endpoint

Create Controllers/MetricsController.cs to allow the Angular app to fetch the initial set of data when it first loads:

using Microsoft.AspNetCore.Mvc;
using LiveDashboard.Api.Services;

namespace LiveDashboard.Api.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class MetricsController : ControllerBase
    {
        private readonly DataGeneratorService _generator;

        public MetricsController(DataGeneratorService generator)
        {
            _generator = generator;
        }

        [HttpGet("snapshot")]
        public IActionResult GetSnapshot()
        {
            var data = new[]
            {
                _generator.GenerateMetric("CPU", 45, 10),
                _generator.GenerateMetric("Memory", 60, 8),
                _generator.GenerateMetric("RequestsPerSecond", 120, 30)
            };

            return Ok(data);
        }
    }
}

Step 1.6: Enable CORS

Since Angular (running on port 4200 in development) and ASP.NET Core (running on a different port) are different origins, you need to enable CORS. Add this to Program.cs:

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAngularDev", policy =>
    {
        policy.WithOrigins("http://localhost:4200")
              .AllowAnyHeader()
              .AllowAnyMethod()
              .AllowCredentials();
    });
});

And later, in the middleware pipeline:

app.UseCors("AllowAngularDev");

Tip: AllowCredentials() is required for SignalR connections to work correctly with CORS.

Step 1.7: Run and Verify

Run the backend with:

dotnet run

Visit https://localhost:<port>/api/metrics/snapshot in your browser or via a tool like Postman to confirm you receive a JSON array of metric data.

At this point, you have a working REST API. Next, we'll add real-time capability using SignalR.

6. Part 2 (Beginner): Adding SignalR for Real-Time Communication

Step 2.1: What Is SignalR?

SignalR is a library built into ASP.NET Core that simplifies adding real-time web functionality. It abstracts away the complexity of WebSockets, automatically falling back to other transport methods (like Server-Sent Events or long polling) when WebSockets aren't available, and handles connection management for you.

Step 2.2: Create the Hub

A "Hub" in SignalR is the core component that handles communication between server and clients. Create Hubs/DashboardHub.cs:

using Microsoft.AspNetCore.SignalR;

namespace LiveDashboard.Api.Hubs
{
    public class DashboardHub : Hub
    {
        public override async Task OnConnectedAsync()
        {
            await Clients.Caller.SendAsync("ReceiveMessage", "Connected to live dashboard hub.");
            await base.OnConnectedAsync();
        }
    }
}

This hub doesn't need many methods yet — most of the data pushing will happen from a background service, not from client-invoked methods. The hub mainly serves as the "pipe" through which data flows.

Step 2.3: Register SignalR in Program.cs

Update Program.cs:

using LiveDashboard.Api.Hubs;
using LiveDashboard.Api.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddSignalR();
builder.Services.AddSingleton<DataGeneratorService>();

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAngularDev", policy =>
    {
        policy.WithOrigins("http://localhost:4200")
              .AllowAnyHeader()
              .AllowAnyMethod()
              .AllowCredentials();
    });
});

var app = builder.Build();

app.UseCors("AllowAngularDev");
app.UseRouting();

app.MapControllers();
app.MapHub<DashboardHub>("/hubs/dashboard");

app.Run();

The key line here is app.MapHub<DashboardHub>("/hubs/dashboard"), which exposes the hub at a specific URL that the Angular client will connect to.

Step 2.4: Create a Background Service to Push Live Data

This is where the "live" part of the dashboard comes to life. We'll create a hosted background service that runs continuously, generates new data every few seconds, and broadcasts it to all connected clients via the hub.

Create Services/MetricBroadcastService.cs:

using Microsoft.AspNetCore.SignalR;
using LiveDashboard.Api.Hubs;

namespace LiveDashboard.Api.Services
{
    public class MetricBroadcastService : BackgroundService
    {
        private readonly IHubContext<DashboardHub> _hubContext;
        private readonly DataGeneratorService _generator;

        public MetricBroadcastService(IHubContext<DashboardHub> hubContext, DataGeneratorService generator)
        {
            _hubContext = hubContext;
            _generator = generator;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                var cpu = _generator.GenerateMetric("CPU", 45, 10);
                var memory = _generator.GenerateMetric("Memory", 60, 8);
                var rps = _generator.GenerateMetric("RequestsPerSecond", 120, 30);

                await _hubContext.Clients.All.SendAsync("ReceiveMetric", cpu, stoppingToken);
                await _hubContext.Clients.All.SendAsync("ReceiveMetric", memory, stoppingToken);
                await _hubContext.Clients.All.SendAsync("ReceiveMetric", rps, stoppingToken);

                await Task.Delay(2000, stoppingToken); // push every 2 seconds
            }
        }
    }
}

builder.Services.AddHostedService<MetricBroadcastService>();

How this works: IHubContext<DashboardHub> lets you send messages to clients from anywhere in your application (not just from within the hub itself) — perfect for a background service that has no direct connection to a specific client, but needs to broadcast to all of them. Clients.All.SendAsync("ReceiveMetric", ...) sends a message named "ReceiveMetric" with the metric data as a payload to every connected client.

Step 2.5: Verify with a Test Client (Optional)

Before building the Angular frontend, you can test the SignalR hub using a tool like the SignalR test client in Postman or a simple HTML page with the SignalR JavaScript client. This isn't required, but it can help isolate backend issues from frontend issues if something doesn't work later.

At this point, your backend is complete for the beginner phase: it has a REST endpoint for the initial snapshot and a SignalR hub broadcasting new data every two seconds.

7. Part 3 (Beginner): Setting Up the Angular Frontend

Step 3.1: Create the Angular Project

In a separate folder (sibling to your backend project), run:

ng new live-dashboard-client --routing --style=scss
cd live-dashboard-client

Choose the default options when prompted, or customize as you prefer.

Step 3.2: Install the SignalR Client Library

Angular communicates with the SignalR hub using Microsoft's official JavaScript/TypeScript client:

npm install @microsoft/signalr

Step 3.3: Install a Charting Library

For this tutorial we'll use Chart.js with the ng2-charts Angular wrapper, since it's lightweight and beginner-friendly. (Advanced alternative: ngx-charts, covered briefly later.)

npm install chart.js ng2-charts

Step 3.4: Project Structure

Generate the core building blocks:

ng generate service services/signalr
ng generate service services/metrics
ng generate component components/dashboard
ng generate component components/metric-card

This gives you a clean separation: a service to manage the SignalR connection, a service to manage metric state, and components for the visual layer.

Step 3.5: Define the Metric Model

Create src/app/models/metric-data.model.ts:

export interface MetricData {
  metricName: string;
  value: number;
  timestamp: string;
}

This mirrors the C# MetricData class on the backend, ensuring type safety across the stack.

At this point, your Angular project is scaffolded and ready to be wired up to the live backend. In the next section, we'll connect it to SignalR.

8. Part 4 (Intermediate): Connecting Angular to SignalR

Step 4.1: Build the SignalR Service

This service will manage the connection lifecycle (connect, disconnect, reconnect) and expose an Observable stream of incoming metric data that any component can subscribe to.

Edit src/app/services/signalr.service.ts:

import { Injectable } from '@angular/core';
import * as signalR from '@microsoft/signalr';
import { Subject } from 'rxjs';
import { MetricData } from '../models/metric-data.model';
import { environment } from '../../environments/environment';

@Injectable({
  providedIn: 'root'
})
export class SignalrService {
  private hubConnection!: signalR.HubConnection;
  private metricSubject = new Subject<MetricData>();

  public metric$ = this.metricSubject.asObservable();

  public startConnection(): void {
    this.hubConnection = new signalR.HubConnectionBuilder()
      .withUrl(`${environment.apiBaseUrl}/hubs/dashboard`)
      .withAutomaticReconnect()
      .configureLogging(signalR.LogLevel.Information)
      .build();

    this.hubConnection
      .start()
      .then(() => console.log('SignalR connection started'))
      .catch(err => console.error('Error starting SignalR connection:', err));

    this.registerHandlers();
  }

  private registerHandlers(): void {
    this.hubConnection.on('ReceiveMetric', (data: MetricData) => {
      this.metricSubject.next(data);
    });

    this.hubConnection.on('ReceiveMessage', (message: string) => {
      console.log('Server message:', message);
    });
  }

  public stopConnection(): void {
    this.hubConnection?.stop();
  }
}

Key concepts explained:

HubConnectionBuilder().withUrl(...) configures the connection to point at the hub endpoint we exposed on the backend (/hubs/dashboard).
.withAutomaticReconnect() tells SignalR to automatically attempt reconnection if the connection drops — essential for a reliable live dashboard.
this.hubConnection.on('ReceiveMetric', ...) registers a handler for the exact same message name ("ReceiveMetric") that the backend uses in SendAsync("ReceiveMetric", ...). These names must match exactly.
We use an RxJS Subject to convert SignalR's callback-based API into an Observable stream, which fits naturally into Angular's reactive patterns.

Step 4.2: Create the Environment Configuration

Update src/environments/environment.ts:

export const environment = {
  production: false,
  apiBaseUrl: 'https://localhost:7000' // match your backend's actual port
};

And src/environments/environment.prod.ts for production builds:

export const environment = {
  production: true,
  apiBaseUrl: 'https://your-production-api.com'
};

Step 4.3: Build the Metrics Service

This service will fetch the initial snapshot via REST and maintain the current state of each metric as live updates arrive.

Edit src/app/services/metrics.service.ts:

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { BehaviorSubject } from 'rxjs';
import { MetricData } from '../models/metric-data.model';
import { environment } from '../../environments/environment';
import { SignalrService } from './signalr.service';

@Injectable({
  providedIn: 'root'
})
export class MetricsService {
  private metricsMap = new Map<string, MetricData>();
  private metricsSubject = new BehaviorSubject<MetricData[]>([]);

  public metrics$ = this.metricsSubject.asObservable();

  constructor(private http: HttpClient, private signalr: SignalrService) {
    this.signalr.metric$.subscribe(metric => this.upsertMetric(metric));
  }

  public loadInitialSnapshot(): void {
    this.http
      .get<MetricData[]>(`${environment.apiBaseUrl}/api/metrics/snapshot`)
      .subscribe(initialData => {
        initialData.forEach(m => this.metricsMap.set(m.metricName, m));
        this.emitMetrics();
      });
  }

  private upsertMetric(metric: MetricData): void {
    this.metricsMap.set(metric.metricName, metric);
    this.emitMetrics();
  }

  private emitMetrics(): void {
    this.metricsSubject.next(Array.from(this.metricsMap.values()));
  }
}

Why a Map keyed by metric name? Each new live update replaces the latest value for that specific metric (e.g., CPU), rather than appending to an ever-growing list. This keeps the current-state view of the dashboard accurate and memory-efficient. (We'll handle historical trend data separately for charts in the next section.)

Step 4.4: Enable HttpClient

Make sure HttpClient is available. In a standalone Angular app (app.config.ts):

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient()
  ]
};

If you're using an NgModule-based app instead, import HttpClientModule into your AppModule.

Step 4.5: Initialize the Connection in the Dashboard Component

Edit src/app/components/dashboard/dashboard.component.ts:

import { Component, OnInit, OnDestroy } from '@angular/core';
import { CommonModule } from '@angular/common';
import { MetricsService } from '../../services/metrics.service';
import { SignalrService } from '../../services/signalr.service';
import { MetricData } from '../../models/metric-data.model';

@Component({
  selector: 'app-dashboard',
  standalone: true,
  imports: [CommonModule],
  templateUrl: './dashboard.component.html',
  styleUrls: ['./dashboard.component.scss']
})
export class DashboardComponent implements OnInit, OnDestroy {
  metrics: MetricData[] = [];

  constructor(
    private metricsService: MetricsService,
    private signalrService: SignalrService
  ) {}

  ngOnInit(): void {
    this.signalrService.startConnection();
    this.metricsService.loadInitialSnapshot();

    this.metricsService.metrics$.subscribe(data => {
      this.metrics = data;
    });
  }

  ngOnDestroy(): void {
    this.signalrService.stopConnection();
  }
}

At this stage, your Angular app connects to the backend, fetches an initial snapshot, and listens for live updates. Next, we'll render this data visually.

9. Part 5 (Intermediate): Building the Dashboard UI with Live Charts

Step 5.1: Basic Metric Cards (Numbers View)

Update dashboard.component.html:

<div class="dashboard">
  <h1>Live Data Dashboard</h1>

  <div class="metric-grid">
    <app-metric-card
      *ngFor="let metric of metrics"
      [name]="metric.metricName"
      [value]="metric.value"
      [timestamp]="metric.timestamp">
    </app-metric-card>
  </div>
</div>

Edit metric-card.component.ts:

import { Component, Input } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-metric-card',
  standalone: true,
  imports: [CommonModule],
  templateUrl: './metric-card.component.html',
  styleUrls: ['./metric-card.component.scss']
})
export class MetricCardComponent {
  @Input() name = '';
  @Input() value = 0;
  @Input() timestamp = '';
}

metric-card.component.html:

<div class="metric-card">
  <h3>{{ name }}</h3>
  <p class="value">{{ value }}</p>
  <small>Updated: {{ timestamp | date:'mediumTime' }}</small>
</div>

This gives you a simple, working live-updating numeric dashboard. Now let's add line charts to visualize trends over time.

Step 5.2: Setting Up ng2-charts

In your standalone component or module, import the chart provider. With standalone components, register it in app.config.ts:

import { provideCharts, withDefaultRegisterables } from 'ng2-charts';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient(),
    provideCharts(withDefaultRegisterables())
  ]
};

Step 5.3: Create a Live Chart Component

Generate a new component:

ng generate component components/live-chart

This component needs to maintain a rolling history of values for a given metric (e.g., the last 30 data points) so the chart shows a trend rather than just the latest number.

Edit live-chart.component.ts:

import { Component, Input, OnChanges, SimpleChanges } from '@angular/core';
import { CommonModule } from '@angular/common';
import { BaseChartDirective } from 'ng2-charts';
import { ChartConfiguration, ChartData } from 'chart.js';

@Component({
  selector: 'app-live-chart',
  standalone: true,
  imports: [CommonModule, BaseChartDirective],
  templateUrl: './live-chart.component.html',
  styleUrls: ['./live-chart.component.scss']
})
export class LiveChartComponent implements OnChanges {
  @Input() label = '';
  @Input() value = 0;
  @Input() timestamp = '';

  private readonly maxPoints = 30;

  public lineChartData: ChartData<'line'> = {
    labels: [],
    datasets: [
      {
        data: [],
        label: this.label,
        borderColor: '#3f8cff',
        backgroundColor: 'rgba(63, 140, 255, 0.15)',
        fill: true,
        tension: 0.35,
        pointRadius: 0
      }
    ]
  };

  public lineChartOptions: ChartConfiguration['options'] = {
    responsive: true,
    animation: { duration: 300 },
    scales: {
      x: { display: false },
      y: { beginAtZero: false }
    },
    plugins: {
      legend: { display: false }
    }
  };

  ngOnChanges(changes: SimpleChanges): void {
    if (changes['value'] && !changes['value'].firstChange) {
      this.addDataPoint();
    } else if (changes['value'] && changes['value'].firstChange) {
      this.addDataPoint();
    }
  }

  private addDataPoint(): void {
    const labels = this.lineChartData.labels as string[];
    const dataset = this.lineChartData.datasets[0].data as number[];

    labels.push(new Date(this.timestamp).toLocaleTimeString());
    dataset.push(this.value);

    if (labels.length > this.maxPoints) {
      labels.shift();
      dataset.shift();
    }

    // Reassign to trigger change detection in ng2-charts
    this.lineChartData = {
      ...this.lineChartData,
      labels: [...labels],
      datasets: [{ ...this.lineChartData.datasets[0], data: [...dataset] }]
    };
  }
}

live-chart.component.html:

<div class="chart-wrapper">
  <h4>{{ label }} Trend</h4>
  <canvas
    baseChart
    [data]="lineChartData"
    [options]="lineChartOptions"
    type="line">
  </canvas>
</div>

Step 5.4: Wire the Chart into the Dashboard

Update dashboard.component.html to include the chart alongside the cards:

<div class="dashboard">
  <h1>Live Data Dashboard</h1>

  <div class="metric-grid">
    <app-metric-card
      *ngFor="let metric of metrics"
      [name]="metric.metricName"
      [value]="metric.value"
      [timestamp]="metric.timestamp">
    </app-metric-card>
  </div>

  <div class="chart-grid">
    <app-live-chart
      *ngFor="let metric of metrics"
      [label]="metric.metricName"
      [value]="metric.value"
      [timestamp]="metric.timestamp">
    </app-live-chart>
  </div>
</div>

Don't forget to add LiveChartComponent to the imports array of DashboardComponent since both are standalone.

At this point, your dashboard displays both live numeric values and animated trend lines that update in real time as the backend pushes new data every two seconds.

Step 5.5: Alternative — Using ngx-charts (Advanced Option)

If you prefer a more "Angular-native" charting library with declarative templates instead of imperative chart configuration objects, consider @swimlane/ngx-charts. It integrates well with Angular's change detection and offers built-in chart types (line, bar, gauge, pie) ideal for dashboards. The setup process is similar: install the package, import the chart module, and bind data arrays to chart components via [results] inputs. Many production dashboards mix both libraries depending on the visualization needed — for example, ngx-charts for gauges and Chart.js for dense time-series lines.

10. Part 6 (Intermediate): Styling the Dashboard

A functional dashboard is only half the job — visual clarity matters, especially for monitoring tools that may be displayed on a large screen for extended periods (e.g., a NOC wall display).

Step 6.1: Grid Layout

In dashboard.component.scss:

.dashboard {
  padding: 2rem;
  background: #0f172a;
  min-height: 100vh;
  color: #e2e8f0;
  font-family: 'Inter', sans-serif;

  h1 {
    font-weight: 600;
    margin-bottom: 1.5rem;
  }
}

.metric-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 1rem;
  margin-bottom: 2rem;
}

.chart-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
  gap: 1.5rem;
}

Step 6.2: Card Styling

In metric-card.component.scss:

.metric-card {
  background: #1e293b;
  border-radius: 12px;
  padding: 1.25rem;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
  transition: transform 0.2s ease;

  &:hover {
    transform: translateY(-2px);
  }

  h3 {
    font-size: 0.85rem;
    text-transform: uppercase;
    letter-spacing: 0.05em;
    color: #94a3b8;
    margin-bottom: 0.5rem;
  }

  .value {
    font-size: 2rem;
    font-weight: 700;
    color: #3f8cff;
    margin: 0;
  }

  small {
    color: #64748b;
  }
}

Step 6.3: Visual Feedback on Update

A nice UX touch for live dashboards is briefly highlighting a value when it changes, so users can visually notice an update without staring at numbers. You can achieve this with a CSS animation triggered by an Angular class binding tied to a "just updated" flag, toggled with a short setTimeout whenever new data arrives. This kind of micro-interaction significantly improves the perceived "liveness" of the dashboard.

11. Part 7 (Advanced): Handling Reconnection and Error States

Production dashboards must gracefully handle network interruptions. SignalR's .withAutomaticReconnect() handles basic reconnection, but you should also surface connection status to users and handle edge cases.

Step 7.1: Expose Connection State

Update signalr.service.ts to track and expose connection status:

import { BehaviorSubject } from 'rxjs';

public connectionState$ = new BehaviorSubject<'connected' | 'reconnecting' | 'disconnected'>('disconnected');

public startConnection(): void {
  this.hubConnection = new signalR.HubConnectionBuilder()
    .withUrl(`${environment.apiBaseUrl}/hubs/dashboard`)
    .withAutomaticReconnect([0, 2000, 5000, 10000, 30000])
    .build();

  this.hubConnection.onreconnecting(() => this.connectionState$.next('reconnecting'));
  this.hubConnection.onreconnected(() => this.connectionState$.next('connected'));
  this.hubConnection.onclose(() => this.connectionState$.next('disconnected'));

  this.hubConnection
    .start()
    .then(() => this.connectionState$.next('connected'))
    .catch(() => this.connectionState$.next('disconnected'));

  this.registerHandlers();
}

The array [0, 2000, 5000, 10000, 30000] passed to withAutomaticReconnect defines custom retry delays (in milliseconds): retry immediately, then after 2s, 5s, 10s, and 30s, after which SignalR stops retrying automatically (you can add logic to manually retry beyond this).

Step 7.2: Display a Connection Banner

In dashboard.component.html, add a status banner:

<div class="connection-banner" *ngIf="connectionState !== 'connected'" [ngClass]="connectionState">
  <span *ngIf="connectionState === 'reconnecting'">Reconnecting to live data...</span>
  <span *ngIf="connectionState === 'disconnected'">Disconnected. Attempting to reconnect...</span>
</div>

Subscribe to connectionState$ in the component class just like you did for metrics. This small addition dramatically improves trust in the dashboard — users immediately know if the data they're looking at might be stale.

Step 7.3: Handle Manual Reconnection

If automatic reconnection exhausts its retries, implement a manual fallback, for instance using setInterval to attempt hubConnection.start() again every 30 seconds while in the disconnected state, with exponential backoff capped at a reasonable maximum to avoid hammering the server.

Step 7.4: Graceful Degradation

Consider what happens if SignalR/WebSockets are entirely blocked (e.g., by a restrictive corporate proxy). SignalR automatically falls back to Server-Sent Events or long polling, but if you want a guaranteed fallback, you could implement a periodic REST polling mechanism as a last resort, triggered only when the connectionState$ remains disconnected for an extended period.

12. Part 8 (Advanced): Adding Authentication with JWT

Most production dashboards display sensitive business data and need to be secured. Here's how to add JWT-based authentication to both the backend and the SignalR connection.

Step 8.1: Backend — Add JWT Authentication

Install the JWT package:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Configure it in Program.cs:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

var jwtKey = builder.Configuration["Jwt:Key"]!;

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtKey))
        };

        // Required so SignalR can read the access token from the query string,
        // since WebSocket connections cannot set custom Authorization headers.
        options.Events = new JwtBearerEvents
        {
            OnMessageReceived = context =>
            {
                var accessToken = context.Request.Query["access_token"];
                var path = context.HttpContext.Request.Path;

                if (!string.IsNullOrEmpty(accessToken) && path.StartsWithSegments("/hubs"))
                {
                    context.Token = accessToken;
                }

                return Task.CompletedTask;
            }
        };
    });

builder.Services.AddAuthorization();

Add the middleware:

app.UseAuthentication();
app.UseAuthorization();

Secure the hub and controller:

[Authorize]
public class DashboardHub : Hub { ... }

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class MetricsController : ControllerBase { ... }

Important detail: Browsers cannot attach custom Authorization headers to native WebSocket connections, so SignalR's JavaScript client sends the token as a query string parameter (access_token) instead. The OnMessageReceived event above reads that token specifically for requests to the /hubs path.

Step 8.2: Create a Simple Login Endpoint (for demo purposes)

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly IConfiguration _config;
    public AuthController(IConfiguration config) => _config = config;

    [HttpPost("login")]
    public IActionResult Login([FromBody] LoginRequest request)
    {
        // Replace with real user validation against your identity store
        if (request.Username != "demo" || request.Password != "password")
            return Unauthorized();

        var claims = new[] { new Claim(ClaimTypes.Name, request.Username) };
        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_config["Jwt:Key"]!));
        var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

        var token = new JwtSecurityToken(
            issuer: _config["Jwt:Issuer"],
            audience: _config["Jwt:Audience"],
            claims: claims,
            expires: DateTime.UtcNow.AddHours(2),
            signingCredentials: creds);

        return Ok(new { token = new JwtSecurityTokenHandler().WriteToken(token) });
    }
}

public record LoginRequest(string Username, string Password);

Add the corresponding Jwt:Key, Jwt:Issuer, and Jwt:Audience values to appsettings.json.

Step 8.3: Angular — Send the Token with SignalR

Update signalr.service.ts to pass the access token when building the connection:

this.hubConnection = new signalR.HubConnectionBuilder()
  .withUrl(`${environment.apiBaseUrl}/hubs/dashboard`, {
    accessTokenFactory: () => localStorage.getItem('authToken') || ''
  })
  .withAutomaticReconnect()
  .build();

Step 8.4: Add an Angular HTTP Interceptor for REST Calls

To attach the token to your regular REST API calls (like /api/metrics/snapshot), add an HttpInterceptorFn:

import { HttpInterceptorFn } from '@angular/common/http';

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const token = localStorage.getItem('authToken');
  const cloned = token
    ? req.clone({ setHeaders: { Authorization: `Bearer ${token}` } })
    : req;
  return next(cloned);
};

provideHttpClient(withInterceptors([authInterceptor]))

Step 8.5: Build a Minimal Login Component

Create a simple login form that calls /api/auth/login, stores the returned token in localStorage (or, for better security, a memory-based store with refresh tokens in an HttpOnly cookie for production-grade apps), and redirects to the dashboard route. Use an Angular route guard (CanActivateFn) to prevent unauthenticated access to the dashboard route.

Security note: Storing JWTs in localStorage is convenient but vulnerable to XSS attacks. For production systems handling sensitive data, consider using HttpOnly, Secure cookies combined with short-lived access tokens and a refresh token rotation strategy.

13. Part 9 (Advanced): Scaling SignalR with Redis Backplane

If you deploy your ASP.NET Core backend across multiple server instances (for load balancing or high availability), SignalR connections will be distributed across those instances. By default, a message broadcast from one server instance won't reach clients connected to a different instance. This is solved using a backplane.

Step 9.1: Install the Redis Backplane Package

dotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis

Step 9.2: Configure It in Program.cs

builder.Services.AddSignalR()
    .AddStackExchangeRedis(builder.Configuration["Redis:ConnectionString"]!, options =>
    {
        options.Configuration.ChannelPrefix = StackExchange.Redis.RedisChannel.Literal("LiveDashboard");
    });

With this in place, when MetricBroadcastService calls Clients.All.SendAsync(...) on one server instance, Redis ensures the message is relayed to all other instances, which then forward it to their own connected clients. This makes your dashboard horizontally scalable.

Step 9.3: When Do You Need This?

For a single-instance deployment (most small to mid-size applications), you do not need a backplane. Only add this complexity once you're running multiple instances behind a load balancer — typically in higher-traffic production environments.

14. Part 10 (Advanced): Performance Optimization

Step 10.1: Throttle High-Frequency Updates

If your real data source produces updates faster than the UI needs to render them (e.g., hundreds of updates per second), avoid pushing every single update to clients. Instead, batch or throttle on the backend — for example, aggregate updates and broadcast at a fixed interval (every 500ms–1s) using a buffer, rather than sending on every change.

On the Angular side, you can also throttle using RxJS:

import { throttleTime } from 'rxjs/operators';

this.signalrService.metric$
  .pipe(throttleTime(300))
  .subscribe(metric => this.upsertMetric(metric));

Step 10.2: Use OnPush Change Detection

For dashboard components receiving frequent updates, switch to ChangeDetectionStrategy.OnPush to avoid unnecessary re-renders across the entire component tree:

@Component({
  selector: 'app-metric-card',
  changeDetection: ChangeDetectionStrategy.OnPush,
  ...
})

Combined with immutable data patterns (creating new objects/arrays rather than mutating existing ones, as we did in the chart component), OnPush significantly reduces CPU usage on busy dashboards.

Step 10.3: Limit Chart History

Capping chart data to a fixed window (we used maxPoints = 30 earlier) prevents memory growth and keeps rendering fast, especially important if the dashboard runs unattended for hours or days (e.g., on an office wall display).

Step 10.4: Use trackBy for *ngFor

When rendering lists of metric cards or charts, always use trackBy to prevent Angular from destroying and recreating DOM elements unnecessarily on every update:

<app-metric-card *ngFor="let metric of metrics; trackBy: trackByName" ... ></app-metric-card>

trackByName(index: number, metric: MetricData): string {
  return metric.metricName;
}

Step 10.5: Compress SignalR Messages (Advanced)

For very data-heavy dashboards, consider using MessagePack instead of the default JSON protocol for SignalR, which reduces payload size and improves throughput:

dotnet add package Microsoft.AspNetCore.SignalR.Protocols.MessagePack
npm install @microsoft/signalr-protocol-msgpack

Configure it on both server (AddSignalR().AddMessagePackProtocol()) and client (.withHubProtocol(new MessagePackHubProtocol())).

15. Part 11 (Advanced): Testing the Application

Step 11.1: Backend Unit Tests

Use xUnit to test your services in isolation. For example, test that DataGeneratorService.GenerateMetric returns values within the expected variance range:

[Fact]
public void GenerateMetric_ReturnsValueWithinVarianceRange()
{
    var service = new DataGeneratorService();
    var result = service.GenerateMetric("CPU", 50, 10);

    Assert.InRange(result.Value, 40, 60);
    Assert.Equal("CPU", result.MetricName);
}

Step 11.2: Integration Testing the Hub

ASP.NET Core supports integration testing using WebApplicationFactory combined with a real SignalR client connecting to an in-memory test server, allowing you to verify that messages broadcast from the hub are actually received by a connected client.

Step 11.3: Angular Unit Tests

Use Jasmine/Karma (or Jest, if configured) to test that MetricsService correctly upserts metrics:

it('should update existing metric value on new data', () => {
  service['upsertMetric']({ metricName: 'CPU', value: 55, timestamp: '2026-01-01T00:00:00Z' });
  service['upsertMetric']({ metricName: 'CPU', value: 70, timestamp: '2026-01-01T00:00:05Z' });

  service.metrics$.subscribe(metrics => {
    const cpu = metrics.find(m => m.metricName === 'CPU');
    expect(cpu?.value).toBe(70);
  });
});

Step 11.4: End-to-End Testing

Use Playwright or Cypress to verify the full flow: load the dashboard, confirm the initial snapshot renders, wait for a live update, and assert that displayed values change without a page reload.

16. Part 12 (Advanced): Deploying to Production

Step 16.1: Build the Angular App for Production

ng build --configuration production

This outputs static files to dist/live-dashboard-client, which can be served by any static file host or reverse proxy.

Step 16.2: Publish the ASP.NET Core Backend

dotnet publish -c Release -o ./publish

Step 16.3: Dockerize Both Applications

Backend Dockerfile:

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app/publish .
EXPOSE 80
ENTRYPOINT ["dotnet", "LiveDashboard.Api.dll"]

Frontend Dockerfile (served via Nginx):

FROM node:20 AS build
WORKDIR /app
COPY . .
RUN npm install && npm run build -- --configuration production

FROM nginx:alpine
COPY --from=build /app/dist/live-dashboard-client /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

A minimal nginx.conf should include a WebSocket-friendly proxy configuration if Nginx also handles routing to the backend, ensuring Upgrade and Connection headers are forwarded correctly for SignalR's WebSocket transport.

Step 16.4: docker-compose for Local Orchestration

version: '3.8'
services:
  api:
    build: ./LiveDashboard.Api
    ports:
      - "5000:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Production

  client:
    build: ./live-dashboard-client
    ports:
      - "4200:80"
    depends_on:
      - api

Step 16.5: Deploying to Azure

For Azure App Service deployments, deploy the ASP.NET Core backend to an App Service (with WebSockets enabled in the Configuration settings — this is required for SignalR to function correctly) and the Angular frontend to Azure Static Web Apps or a separate App Service serving static files. If you expect multiple backend instances, enable Azure SignalR Service instead of self-hosting SignalR, which handles scaling and connection management for you and removes the need for a Redis backplane.

Step 16.6: Deploying to IIS

If deploying to IIS, ensure the WebSocket Protocol feature is enabled in Windows Server roles/features, and that the ASP.NET Core Module v2 is installed. Without WebSocket support enabled at the IIS/server level, SignalR will silently fall back to long polling, which still works but is less efficient.

Step 16.7: HTTPS and Security Headers

In production, always serve both frontend and backend over HTTPS — mixed content (HTTPS frontend calling an HTTP backend) will be blocked by browsers, and WebSocket connections (wss://) require a secure context when the page itself is loaded over HTTPS.

17. Common Errors and Troubleshooting

Error: "Failed to complete negotiation with the server"
Usually caused by CORS misconfiguration or the backend not running. Confirm AllowCredentials() is set and that the origin matches exactly (including protocol and port).

Error: SignalR connects but no data arrives
Double-check that the event name in hubConnection.on('ReceiveMetric', ...) exactly matches the string used in SendAsync("ReceiveMetric", ...) on the backend — these are case-sensitive string matches, not type-checked.

Error: Connection works locally but fails after deployment
Almost always a missing WebSocket configuration at the hosting/proxy layer (IIS, Nginx, or a load balancer not configured for WebSocket passthrough).

Charts not updating despite new data arriving
Verify you are creating new array/object references when updating chart data (as shown in Step 5.3) rather than mutating existing objects in place — Angular and Chart.js both rely on reference changes to detect updates efficiently.

401 Unauthorized when connecting to the hub after adding JWT auth
Confirm the accessTokenFactory is correctly returning a valid, non-expired token, and that the OnMessageReceived handler on the backend is scoped to the /hubs path.

18. Best Practices Checklist

Use SignalR for live updates; use REST only for the initial data snapshot.
Always implement .withAutomaticReconnect() and surface connection status in the UI.
Cap historical data arrays to avoid unbounded memory growth in long-running dashboard sessions.
Use OnPush change detection and trackBy for performance on data-heavy dashboards.
Secure both the REST API and the SignalR hub with [Authorize] once authentication is added.
Enable WebSockets explicitly on your hosting environment (IIS, Azure App Service, Nginx).
Use a Redis backplane or Azure SignalR Service only once you scale beyond a single backend instance.
Throttle extremely high-frequency data sources before broadcasting to clients.
Always test reconnection behavior by manually killing and restarting the backend during development.

19. Frequently Asked Questions (FAQ)

Q: Do I need SignalR, or can I just poll the API every few seconds?
Polling works for simple cases but is less efficient and introduces latency. SignalR provides true push-based real-time updates with lower overhead once a connection is established, making it the better choice for dashboards needing sub-second responsiveness.

Q: Can I use this approach with React or Vue instead of Angular?
Yes. The backend (ASP.NET Core + SignalR) is frontend-agnostic. Microsoft provides the same @microsoft/signalr JavaScript client that works with any frontend framework, not just Angular.

Q: What's the difference between SignalR and raw WebSockets?
SignalR is a higher-level abstraction built on top of WebSockets (with automatic fallback to other transports). It handles connection management, reconnection, and message serialization for you, whereas raw WebSockets require you to build all of that yourself.

Q: How do I handle dashboards with many different data types (not just numeric metrics)?
Use a more generic message envelope (e.g., a DashboardEvent with a type field and a polymorphic payload) instead of a single MetricData model, and route messages to different handlers/components based on type on the client side.

Q: Is SignalR suitable for very high-frequency data (thousands of updates per second)?
For extremely high-frequency data, consider batching updates on the server before broadcasting (as discussed in the performance section) rather than sending every single data point individually.

20. Conclusion

You've now built a complete, real-time live data dashboard from the ground up — starting with a simple ASP.NET Core Web API, layering in SignalR for true real-time push updates, building a reactive Angular frontend with live-updating charts, and progressing through advanced topics like authentication, scaling, performance optimization, and production deployment.

This architecture pattern — REST for initial state, SignalR for live updates, RxJS for reactive state management on the client — is a robust foundation you can extend to almost any real-time use case: IoT monitoring, financial dashboards, server health monitors, live order tracking, or collaborative applications.

From here, consider exploring related topics such as integrating a real database with Entity Framework Core instead of simulated data, adding role-based dashboards where different users see different metrics, or building alerting rules that trigger notifications when metric thresholds are crossed.

Source Code

The complete source code for this project is available on GitHub.

GitHub Repository:
Live Data Dashboard – GitHub

The repository contains both the ASP.NET Core backend and Angular frontend, including the SignalR implementation used for real-time metric updates.

You can clone the repository and follow the setup instructions in the README to run the project locally.

git clone https://github.com/ravi-vishwakarma-hash/Live_Data_Dashboard.git

If you found this guide helpful, consider bookmarking it as a reference architecture for your next real-time Angular + ASP.NET Core project.

The Complete Guide to Types of Testing in Software Engineering

Ravi Vishwakarma — Sun, 07 Jun 2026 13:49:25 +0000

Software testing is primarily divided into two main categories:

Functional Testing, which verifies what the system does against business requirements
Non-Functional Testing, which evaluates how the system performs regarding usability, speed, and security.

These categories are executed across different stages, methods, and levels to ensure the final product is stable and reliable.

1. Functional Testing (The "What")

Functional testing focuses on the business requirements of an application, validating that every feature operates according to specified expectations.

Unit Testing: Checks individual blocks, methods, or functions of code in strict isolation.
Integration Testing: Verifies that different modules or units work together seamlessly when combined.
System Testing: Evaluates the complete, fully integrated software system as a whole to check overall business compliance.
Acceptance Testing (UAT): Conducted by clients or end-users to confirm if the application is ready for real-world deployment.
Regression Testing: Re-tests existing features after updates or code modifications to ensure no new bugs were introduced.
Smoke Testing: Runs rapid, high-level checks on core functionalities to verify if a build is stable enough for deeper testing.

2. Non-Functional Testing (The "How")

Non-functional testing evaluates the quality, technical behaviors, and operational readiness of the software rather than specific features.

Performance Testing: Measures system responsiveness, speed, and resource usage under normal and peak conditions.
Load Testing: Evaluates how the application behaves under a specific, expected volume of simultaneous users.
Stress Testing: Pushes the system past its normal performance capacity to find its breaking point.
Security Testing: Scans the application for internal or external vulnerabilities and cyber threats.
Usability Testing: Assesses user experience, interface layout, and overall user-friendliness.
Compatibility Testing: Verifies the software functions correctly across various operating systems, browsers, and devices.

3. Testing Approaches (The "Knowledge")

Software tests are also classified by how much visibility the tester has into the underlying programming code:

Black-Box Testing: Testing is done completely from the outside, with no knowledge of the internal code or logic structure.
White-Box Testing: Testing is executed with deep knowledge of the code, loops, data flows, and internal architectures.
Grey-Box Testing: A hybrid approach where the tester has limited or partial knowledge of the internal system backend.

4. Methods of Execution

Depending on the engineering team's goals and resources, the testing types above can be carried out through two primary execution methods:

Manual Testing: Human QA specialists manually interact with the user interface and tools to log unexpected defects.
Automated Testing: Writing scripts and utilizing testing frameworks to execute repetitive test suites with speed and precision.

Keep coding.

How to Implement SSE for Notifications in .NET in a Production-Ready Way?

Ravi Vishwakarma — Thu, 16 Apr 2026 02:43:20 +0000

This is not a demo – this is the same pattern used in real chat/notification systems (WhatsApp-like browser notifications, dashboards, etc.).

1. When to Use SSE (Production Decision)

Use SSE when:

One-way server → browser notifications
Chat message alerts (not full chat transport)
Live counters, alerts, status updates
Browser-based apps (no mobile socket requirement)

Do NOT use SSE for:

Binary streaming
High-frequency bidirectional chat typing events
Mobile background connections (WebSocket better)

2. Architecture (Production)

Browser (EventSource)
        ↓
SSE Controller (long-lived HTTP)
        ↓
ConcurrentDictionary<UserId, SseClient>
        ↓
Notification Publisher (Chat / Job / API)

Key rules:

One SSE connection per user
No DB polling
No blocking threads
Heartbeat required
Auto-reconnect handled by browser

3. Core SSE Infrastructure (IMPORTANT)

3.1 SSE Client Model

public class SseClient
{
    public int UserId { get; set; }
    public HttpResponse Response { get; set; }
    public DateTime ConnectedAt { get; set; }
}

3.2 SSE Connection Manager (Thread-Safe)

public static class SseConnectionManager
{
    private static readonly ConcurrentDictionary<int, SseClient> _clients
        = new ConcurrentDictionary<int, SseClient>();

    public static bool AddClient(int userId, HttpResponse response)
    {
        RemoveClient(userId); // ensure single tab policy (optional)
        return _clients.TryAdd(userId, new SseClient
        {
            UserId = userId,
            Response = response,
            ConnectedAt = DateTime.UtcNow
        });
    }

    public static void RemoveClient(int userId)
    {
        _clients.TryRemove(userId, out _);
    }

    public static bool SendToUser(int userId, string eventName, string data)
    {
        if (!_clients.TryGetValue(userId, out var client))
            return false;

        try
        {
            client.Response.Write($"event: {eventName}\n");
            client.Response.Write($"data: {data}\n\n");
            client.Response.Flush();
            return true;
        }
        catch
        {
            RemoveClient(userId);
            return false;
        }
    }

    public static void Broadcast(string eventName, string data)
    {
        foreach (var userId in _clients.Keys)
        {
            SendToUser(userId, eventName, data);
        }
    }
}

Thread-safe
Memory-safe
Handles broken connections

4. SSE Controller (Production-Safe)

public class SseController : Controller
{
    [HttpGet]
    public void Subscribe()
    {
        int userId = GetLoggedInUserId();

        Response.ContentType = "text/event-stream";
        Response.CacheControl = "no-cache";
        Response.BufferOutput = false;

        SseConnectionManager.AddClient(userId, Response);

        try
        {
            while (Response.IsClientConnected)
            {
                // Heartbeat every 15 sec
                Response.Write("event: ping\n");
                Response.Write("data: {}\n\n");
                Response.Flush();

                Thread.Sleep(15000);
            }
        }
        finally
        {
            SseConnectionManager.RemoveClient(userId);
        }
    }

    private int GetLoggedInUserId()
    {
        return int.Parse(User.Identity.Name);
    }
}

Why heartbeat?

Prevents proxy/load-balancer timeout
Detects dead connections

5. Sending Notifications (Chat / API / Jobs)

Example: Chat Message Notification

public class NotificationService
{
    public static void NotifyUser(int userId, object payload)
    {
        string json = Newtonsoft.Json.JsonConvert.SerializeObject(payload);
        SseConnectionManager.SendToUser(userId, "message", json);
    }
}

Usage:

NotificationService.NotifyUser(671496, new
{
    fromUserId = 655093,
    text = "Hello 👋",
    createdAt = DateTime.UtcNow
});

6. Browser Client (Production JS)

<script>
let source = new EventSource("/sse/subscribe");

source.addEventListener("message", function (e) {
    let data = JSON.parse(e.data);
    console.log("Message:", data);
});

source.addEventListener("ping", function () {
    console.log("heartbeat");
});

source.onerror = function () {
    console.log("SSE disconnected. Reconnecting...");
};
</script>

Auto-reconnect handled by browser
No polling
Low memory footprint

7. Multi-Tab Handling (WhatsApp-Like Behavior)

If same user opens multiple tabs, enforce single active tab:

public static bool AddClient(int userId, HttpResponse response)
{
    RemoveClient(userId); // kicks old tab
    return _clients.TryAdd(userId, new SseClient
    {
        UserId = userId,
        Response = response,
        ConnectedAt = DateTime.UtcNow
    });
}

Other tabs will automatically disconnect and can show popup:

“This account is active in another tab”

8. Production Hardening Checklist

IIS / Hosting

Disable response buffering
Increase request timeout
Enable keep-alive

Security

Auth-based user binding
No userId in query string
Rate-limit notification sends

Scalability

In-memory only → single server
Multi-server → use Redis Pub/Sub

9. Multi-Server (Redis) Architecture

Server A  ─┐
Server B  ─┼── Redis Pub/Sub ──► SSE Clients
Server C  ─┘

Each server:

Subscribes to Redis channel
Pushes events to connected users

10. Why Big Companies Use SSE

GitHub notifications
Slack web notifications
Trading dashboards
Monitoring systems

Lower cost than WebSockets

Works perfectly behind proxies

Auto-reconnect built-in

11. SSE vs WebSocket (Quick Decision)

Feature	SSE	WebSocket
Direction	Server → Client	Two-way
Complexity	Low	High
Scaling	Easy	Harder
Browser support	Excellent	Excellent
Chat notifications	Best	Overkill

Final Recommendation (For Your Chat App)

Use:

SSE → notifications, unread count, alerts
API → send message
Optional WebSocket → typing indicators only