The key to DevUI’s usefulness is its ability to shorten the agent development loop by giving developers immediate visibility into workflow execution and agent interactions. However, as agentic applications move from prototype to production, a new observability gap begins to appear. Developers need to understand not only what happened during a local debugging session, but how agents behave across users, sessions, models, tools, latency, cost, quality, and failures.

In this article, you'll use DevUI to develop, visualize, and debug workflows locally before expanding into observability to support multi-session debugging and production-ready diagnostics. By extending the agent development loop beyond local testing, observability helps bridge the gap between development-time insight and the operational visibility required for production systems.

Installing the Microsoft Agent Framework Templates

To get started with DevUI and Microsoft Agent Framework, install the project templates from NuGet. The templates provide a starter project for building and debugging agent-based applications in .NET.

Install the templates using the .NET CLI:

dotnet new install Microsoft.Agents.AI.ProjectTemplates::1.3.0-preview.1.26251.3

Once installed, the templates become available through Visual Studio under File > New Project. Search for Agent to locate the available Microsoft Agent Framework project templates, shown in Figure 1.

Figure 1: The project template shown in Visual Studio.

You can also create a new project directly from the command line:

dotnet new aiagent-webapi

The generated project includes a starter implementation configured for Microsoft Agent Framework and DevUI, making it easy to begin experimenting with agents, orchestration, and workflow debugging locally.

Exploring the Template

The aiagent-webapi template includes a complete sample application that demonstrates how agents and workflows operate within Microsoft Agent Framework.

The sample application contains two hosted agents and a workflow:

1. Writer Agent
   Generates short stories based on a provided topic while keeping responses under 300 words.

2. Editor Agent
   Reviews and refines the generated story by improving grammar, readability, and style while maintaining the word limit.

3. Publisher Workflow Agent
   Coordinates the workflow between the writer and editor agents using a sequential process that passes content through each stage of execution.

The agents are exposed through OpenAI-compatible API endpoints, making the sample easy to test with DevUI and simple to integrate with external tools and applications. By keeping the architecture approachable, the template creates a practical environment for understanding how agent orchestration works in a real .NET application.

Understanding AddAgent and IHostedAgentBuilder

Microsoft Agent Framework registers agents using the AddAgent extension method during application startup. This approach integrates agents directly into the standard ASP.NET Core dependency injection system, making the programming model feel familiar to .NET developers.

builder.AddAIAgent("writer", 
    "You write short stories (300 words or less) about the specified topic.");

The AddAgent method returns an IHostedAgentBuilder, which provides additional configuration options for the agent and its hosting behavior. The template uses this pattern to register the Writer, Editor, and Publisher workflow agents so they can be discovered and executed through DevUI and the framework’s OpenAI-compatible endpoints.

Running the Application

With the project created, the next step is running the application and launching DevUI. Start the application using the .NET CLI:

dotnet run

The application exposes OpenAI-compatible API endpoints that can be accessed from compatible clients and tools. During development, the application also maps a /devui/ route that launches the Agent Framework development UI.

When running the project from Visual Studio or another IDE, the browser automatically opens to the DevUI endpoint. DevUI provides a web-based interface for interacting with agents and workflows while using the framework’s Responses and Conversations endpoints behind the scenes. This creates a fast feedback loop for testing prompts, tracing interactions, and validating workflow execution during development.

Understanding the Agent Development Loop

DevUI improves the agent development loop by making it easier to build, run, inspect, and refine workflows during development. Instead of treating agents as black-box processes, developers can interact with workflows in real time and observe how messages move between agents during execution.

Both agents and workflows can be independently selected from the interface, shown in Figure 2.

Figure 2: The browser running DevUI with the agent selection showing the available agents and workflows. 1) The editor and writer agents can be selected and executed independently. 2) The publisher workflow can be executed.

This visibility becomes increasingly important as workflows grow more complex. Multi-agent systems introduce challenges that traditional request-response applications typically avoid, including non-deterministic behavior, chained execution steps, and state shared across conversations.

To run a selected workflow in DevUI, open a prompt by clicking Configure and Run. Then enter a prompt in the dialog box, shown in Figure 3. The prompt text is passed into the workflow and the entire workflow will execute when Run Workflow is clicked.

Figure 3: The Configure Workflow Input dialog box.

DevUI creates an approachable debugging experience, its current model focuses on short-lived, single-session workflows. The final output is clearly displayed on screen, shown in Figure 4.

Figure 4: The output shown in the workflow execution timeline.

This works well for experimentation and local testing. However, debugging becomes more difficult once multiple sessions are running concurrently or workflows require historical visibility for troubleshooting.

For example, the execution information is shown for this run in the Events panel in Figure 5. While the status and token information is visible from DevUI, it does not persist once the application stops.

Figure 5: The Events panel displays a completed status along with usage statistics for token consumption.

As developers move beyond isolated testing scenarios, the agent development loop begins to require more than interactive debugging alone. Understanding how workflows behave across sessions, tracing execution over time, and diagnosing failures in larger systems naturally leads to the next step: observability.

Note: Currently Telemetry is not supported within DevUI when using .NET.

Introducing AI Observability Across Tracing, Debugging, Cost, and Evaluation

As workflows grow beyond simple development scenarios, observability becomes a critical part of the agent development loop. This is where the observability gap begins to appear. DevUI helps developers understand what happened during a local debugging session, but production systems require persistent visibility into how agents behave across users, sessions, models, tools, latency, cost, quality, and failures. While DevUI provides interactive debugging for local workflows, observability extends visibility across sessions, tool calls, evaluations, and distributed execution paths using OpenTelemetry and .NET’s built-in Activity pipeline.

The .NET SDK instruments agents built with either IChatClient from Microsoft.Extensions.AI or IAgent from Microsoft Agent Framework. This allows developers to trace LLM requests, streaming responses, workflow execution, and tool calls while integrating naturally with existing .NET telemetry infrastructure.

To enable observability, we'll use Progress AI Observability Platform. The Progress AI Observability Platform is a cloud-based platform for tracing, debugging, cost analysis, and evaluation of AI applications. It provides visibility into how AI agents behave across models, tools, and sessions, helping teams identify issues as they happen, understand their impact, and continuously improve workflow quality over time.

Start by installing the .NET SDK for Progress AI Observability Platform.

dotnet add package Progress.Observability.Instrumentation

Next, configure the desired options. Tags can be included for easier filtering within the observability reporting screen. In this example, the Environment name will capture: Development, Staging, and Production tags. Once the options are declared, the tracer is initialized.

// Configure the observiablity options, tags, and keys
var observabilityOptions = new ObservabilityOptions()
{
    AppName = builder.Environment.ApplicationName,
    ApiKey = builder.Configuration["Progress:ObservabilityKey"]!,
    AdditionalTags = new List<string> { builder.Environment.EnvironmentName }
};

// Initialize the observability tracer
ObservabilityTracer.Initialize(observabilityOptions);

Start capturing traces at the top level of applications using IChatClient, observability is added directly to the client:

var chatClient = new ChatClient(
        "gpt-4o-mini",
        new ApiKeyCredential(builder.Configuration["AzureOpenAI:Key"] ?? throw new InvalidOperationException("Missing configuration: AzureOpenAI:Key")),
        new OpenAIClientOptions { Endpoint = azureOpenAIEndpoint })
    .AsIChatClient()
    .AddObservability(o => o = observabilityOptions);

Applications using Microsoft Agent Framework can initialize observability through AddObservability() during agent construction:

var chatClient = new ChatClient(
        "gpt-4o-mini",
        new ApiKeyCredential(builder.Configuration["AzureOpenAI:Key"] ?? throw new InvalidOperationException("Missing configuration: AzureOpenAI:Key")),
        new OpenAIClientOptions { Endpoint = azureOpenAIEndpoint })
    .AsIChatClient()
    .AddObservability(o => o = observabilityOptions);

With observability enabled, you'll run the application using DevUI. Exercise the agents and workflows as before, but this time each session is collected for a deeper analysis through the AI Observability Platform. From the dashboard, you can perform cost analysis, run evaluations, and drill into traces across multiple sessions.

From the main Observations tab, all sessions are shown for a given period. Through the tagging feature the data is easily categorized, seen in Figure 6.

Figure 6: The observability platform with the Observations tab selected. 1) The date range and filter selection is chosen. 2) All sessions within the filter criteria.

Clicking on an individual item displays a complete breakdown of the trace log, see Figure 7. Including status, latency, cost and more. A tree interface allows deeper debugging, showing individual agent calls within the workflow, along with their corresponding inputs and outputs.

Figure 7: A trace is selected. 1) The status section shows top level telemetry data including status, latency and costs. 2) A tree interface expands into nested trace activity. 3) The inputs and outputs of the selected agent are displayed.

This approach creates a more complete agent development loop, allowing local experimentation in DevUI to evolve into production-ready diagnostics and monitoring. In this article, tracing serves as the primary example, however production AI observability extends much further. Teams also need debugging, cost analysis, evaluation, governance, and operational insight to successfully operate AI systems at scale.

Progress AI Observability Platform supports that broader production view, helping teams connect trace-level detail with the trust, scale, and operational control required for enterprise AI applications.

Next Steps

DevUI provides a strong starting point for building and debugging agents locally, but production AI systems require deeper visibility across tracing, debugging, evaluation, and operational monitoring.

Explore the Progress AI Observability Platform to see how observability extends the agent development loop from local experimentation to production-ready diagnostics.

Have questions or want to share what you're building? Join the conversation with the team on Discord.

In ASP.NET Core applications, developers often underestimate the importance of validating objects and classes. An if statement in the controller, a FluentValidation in the request or some DataAnnotations in the model, and that’s it. The problem is that, if care isn’t taken when implementing domain validations, responsibility ends up leaking, which can compromise the entire system’s evolution.

In this article, we will analyze common examples of domain validation that are highly prone to errors and how these validations should be correctly modeled according to the principles of Domain-Driven Design (DDD).

Poorly Structured Validations

1. Validation in the Controller

Although it speeds up development, implementing validations in API controllers is discouraged, as it makes the controller highly coupled to business rules. Furthermore, the rules created there are impossible to reuse. Finally, validations in controllers allow other parts of the code to execute the same actions, bypassing the rules.

Consider the following example:

[Route("api/[controller]")]
[ApiController]
public class OrderController : ControllerBase
{
    private readonly OrderRepository _orderRepository;

    public OrderController(OrderRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }

    [HttpPost]
    public IActionResult Create(CreateOrderDto dto)
    {
        if (dto.Total <= 0)
            return BadRequest("Total must be greater than zero");

        if (dto.Items == null || !dto.Items.Any())
            return BadRequest("Order must have at least one item");

        var order = new Order()
        {
            Total = dto.Total,
            Items = dto.Items
        };

        _orderRepository.Add(order);

        return Ok();
    }
}

The code above is a common example of validations in the Controller, and it’s a bad example because it has all the flaws mentioned earlier. Note that the _orderRepository.Add(order); method is called at the end, meaning there are loopholes here.

Imagine that the parameter CreateOrderDto dto has a total greater than zero, and the Items list has one item, but the rest of the properties are null. Even so, the Add method will be called and will create problematic entities or generate a bug.

2. Validation in the Service Class

Although common, the use of validations in the Service class should also be avoided because they place business rules in the wrong place. Considering the previous example, they only changed location but still remain a problem.

When a business rule is coupled to a Service, the domain model becomes passive, and entities can be created or modified in invalid states because there is nothing to prevent them from doing so. The result is a fragile system, as object validation ceases to be a priority and becomes solely dependent on the execution flow.

Another problem is rule duplication. In large systems, the same rule is often needed in more than one use case. When it is in the Service, it ends up being copied to other services, handlers or jobs, which increases the risk of inconsistency and hinders business evolution.

Finally, the Service Layer is responsible for orchestrating use cases, coordinating repositories, transactions and external calls. When it validates domain rules, it mixes responsibilities and becomes a central point of complexity, bloated with if statements and exceptions that don’t belong to it.

The example below shows what a Service class looks like with business rules defined in it:

public class OrderService
{
    private readonly OrderRepository _orderRepository;

    public OrderService(OrderRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }

    public void Create(CreateOrderDto dto)
    {
        if (dto.Total <= 0)
            throw new Exception("Total must be greater than zero");

        if (!dto.Items.Any())
            throw new Exception("Order must have at least one item");

        var order = new Order(dto.Total, dto.Items);
        _orderRepository.Add(order);
    }
}

Note that the logic of if and else statements remains the same, it has only changed location, allowing objects to change state and create corrupted states.

3. Using Data Annotations

Another common form of validation is through the Data Annotations Model Binder, which is implemented using attributes placed above the properties of an entity class.

The problem is that, as they make the domain dependent on a framework, the validation only works in binding (MVC), and they may not work in non-web scenarios such as workers, messaging and tests.

 public class Order
  {
      [Required]
      [Range(1, double.MaxValue)]
      public decimal Total { get; set; }
      public List<OrderItem> Items { get; set; }
  }

Note that we are requiring the Total property to have a minimum value of 1. But even so, it is not yet a secure validation because it is still possible to create an entity with an invalid state.

Domain Validation with DDD

Domain-Driven Design emphasizes the importance of keeping validations within the domain. The main reason is that this way, the domain becomes self-protecting.

Entities and aggregates cease to be passive structures (as seen in previous examples) and ensure that their rules are always respected, regardless of where or how they are used.

Another positive aspect of this approach is the model’s coherence. When business rules are in the domain, they are closer to the concept they represent, making the code more expressive and easier to understand. Reading an entity or a behavioral method reveals the rules governing that concept. In other words, you understand the intention behind that behavior.

Finally, implementing validations in the domain makes system evolution safer. New use cases can be added without fear of breaking existing rules because the domain itself acts as a safety barrier. This reduces maintenance costs and makes the system more resilient to business growth and changes.

Next, we’ll look at an example of a domain guided by DDD principles and analyze each point. You can access the source code in this GitHub repository: Domain Validations code.

Order class with Domain Validations:

public class Order
{
    private readonly List<OrderItem> _items = new();

    public Guid Id { get; private set; }
    public DateTime CreatedAt { get; private set; }
    public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();
    public decimal Total { get; private set; }

    public Order(IEnumerable<OrderItem> items)
    {
        if (items == null || !items.Any())
            throw new DomainException("Order must have at least one item.");

        Id = Guid.NewGuid();
        CreatedAt = DateTime.UtcNow;

        foreach (var item in items)
            AddItem(item);

        ValidateItemsQuantity();
    }

    public void AddItem(OrderItem item)
    {
        if (item == null)
            throw new DomainException("Order item cannot be null.");

        _items.Add(item);
        RecalculateTotal();
    }

    private void RecalculateTotal()
    {
        Total = _items.Sum(i => i.Subtotal);

        if (Total <= 0)
            throw new DomainException("Order total must be greater than zero.");
    }

    private void ValidateItemsQuantity()
    {
        if (!_items.Any())
            throw new DomainException("Order cannot exist without items.");
    }
}

Item class with Domain Validations:

public class OrderItem
{
    public Guid ProductId { get; private set; }
    public decimal Price { get; private set; }
    public int Quantity { get; private set; }

    public decimal Subtotal => Price * Quantity;

    protected OrderItem() { } // EF

    public OrderItem(Guid productId, decimal price, int quantity)
    {
        if (productId == Guid.Empty)
            throw new DomainException("ProductId is required.");

        if (price <= 0)
            throw new DomainException("Price must be greater than zero.");

        if (quantity <= 0)
            throw new DomainException("Quantity must be greater than zero.");

        ProductId = productId;
        Price = price;
        Quantity = quantity;
    }
}

Private Setters and ReadOnly Properties

The first aspect we can notice in this new version of the Order class is that the Items property is private, which means it is inaccessible outside the class: private readonly List<OrderItem> _items = new();.

We also have a public list of items: public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();, but note that it is defined as read-only. This means that it can be accessed by external sources, but only for reading the data and never for modification.

Another factor protecting the class properties is that, despite being public, they have private setters: public Guid Id { get; private set; }, preventing external sources from modifying their states.

Protected Constructor

Protecting the constructor method means allowing only valid states of an entity to be created. In our example, we are defining rules within the constructor:

public Order(IEnumerable<OrderItem> items)
{
    if (items == null || !items.Any())
        throw new DomainException("Order must have at least one item.");

    Id = Guid.NewGuid();
    CreatedAt = DateTime.UtcNow;

    foreach (var item in items)
        AddItem(item);

    ValidateItemsQuantity();
}

public void AddItem(OrderItem item)
{
    if (item == null)
        throw new DomainException("Order item cannot be null.");

    _items.Add(item);
    RecalculateTotal();
}

private void RecalculateTotal()
{
    Total = _items.Sum(i => i.Subtotal);

    if (Total <= 0)
        throw new DomainException("Order total must be greater than zero.");
}

private void ValidateItemsQuantity()
{
    if (!_items.Any())
        throw new DomainException("Order cannot exist without items.");
}

Note that the item quantity validation is performed within the constructor. That is, when creating a new object state, values are also set for the Id and CreatedAt properties. Finally, the ValidateItemsQuantity method verifies if the private property _items has actually been loaded with items, adding an extra layer of validation. In this way, the database will only receive valid states, a corrupted or incomplete entity will never be inserted, enabling data consistency.

Domain Exceptions

Domain exceptions are errors thrown when a business rule (invariant) is violated. Unlike technical failures such as database outages or timeouts, domain exceptions represent violations of the system’s business rules, such as an order without items, for example.

Domain exceptions are important because they help prevent an entity or aggregate from existing in an invalid state. If a rule is broken, the domain needs to react immediately, and the exception is a suitable mechanism to keep inconsistent data from reaching the database or being manipulated in any way.

In the previous example, we validated whether the value was less than zero and whether the list of items was empty. If either condition is met, a DomainException will be thrown, which is a custom exception. The code below shows how the exception is implemented:

namespace DomainValidation;

[Serializable]
internal class DomainException : Exception
{
    public DomainException()
    {
    }

    public DomainException(string? message) : base(message)
    {
    }

    public DomainException(string? message, Exception? innerException) : base(message, innerException)
    {
    }
}

Is FluentValidation Still Useful?

FluentValidation is a widely used .NET library for validations, and even in scenarios where we use the domain validation approach, it certainly remains useful.

The main functionality of FluentValidation is to validate input data, not business rules. Therefore, by using it in the application, we can obtain an extra layer of validation, preventing corrupted data from reaching the domain.

The code below demonstrates how FluentValidation can be used to validate input data:

using FluentValidation;

public class CreateOrderRequest
{
    public List<CreateOrderItemRequest> Items { get; set; }
}

public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderRequestValidator()
    {
        RuleFor(x => x.Items)
            .NotNull()
            .WithMessage("Items cannot be null.")
            .Must(x => x.Any())
            .WithMessage("Order must contain at least one item.");

        RuleForEach(x => x.Items)
            .SetValidator(new CreateOrderItemRequestValidator());
    }
}

public class CreateOrderItemRequest
{
    public Guid ProductId { get; set; }
    public decimal Price { get; set; }
    public int Quantity { get; set; }
}

public class CreateOrderItemRequestValidator : AbstractValidator<CreateOrderItemRequest>
{
    public CreateOrderItemRequestValidator()
    {
        RuleFor(x => x.ProductId)
            .NotEmpty()
            .WithMessage("ProductId is required.");

        RuleFor(x => x.Price)
            .GreaterThan(0)
            .WithMessage("Price must be greater than zero.");

        RuleFor(x => x.Quantity)
            .GreaterThan(0)
            .WithMessage("Quantity must be greater than zero.");
    }
}

When Out-of-Domain Validations Make Sense

Validations in the Controller and Service classes make sense when they are not business rules, but rather validations such as security, flow or format.

It is common to perform authentication/authorization validations in the Controller, because this is the responsibility of the edge (API), and if a user or system is not properly authenticated/authorized, it should not have access to the domain or the rest of the system; it should be blocked at the entrance.

The Service class, on the other hand, can have validations used to manage operational flows, for example, checking if the customer exists before creating an order, checking if the product exists, checking if there is already an open order for the customer.

In this way, we do not validate the internal state of the entity. Instead, we validate the interactions between aggregates or external systems.

Conclusion

Implementing domain validations in an application means explicitly stating the reason for that domain’s existence and the rules that determine its behavior. Furthermore, domain validations keep an invalid object from reaching the database, preventing future bugs and the resulting damage.

Throughout this post, we’ve seen examples of incorrectly implemented validations, scattered across controllers or services, resulting in fragile and difficult-to-maintain code. In contrast, we implemented validations directly on the entities, applying DDD principles.

I hope this post has helped you see the domain as the heart of the application and the importance of keeping it consistent, protected and expressive.

More on DDD: Getting Started with Domain-Driven Design in ASP.NET Core

In the world of web development, there are scenarios where you need to receive real-time information, such as notifications about an event, server metrics or live logs. One possible solution to achieve this is the use of Server-Sent Events (SSE). With the arrival of .NET 10, implementing this type of solution has become much easier, so let’s see how to integrate this web standard into your projects.

What Are Server-Sent Events?

The Server-Sent Events (SSE) are not a new technology. Their origins date back to around 2006, and they are a web standard that allows data to be sent to clients continuously using a persistent HTTP connection.

If you wonder the difference compared to other similar technologies, we can make a comparison:

• SSE vs. Polling: In the case of polling, the direction goes from the client to the server, using the HTTP protocol. We can see it as a client asking the server if there are updates at certain intervals. It involves low implementation complexity.

• SSE vs. WebSockets: With WebSockets there is bidirectional communication. It involves high complexity and is ideal for scenarios like video games, chats, etc. It works over the WS protocol.

• SSE vs. SignalR: SignalR also establishes bidirectional communication, with medium implementation complexity. It allows the use of binary protocols, which makes it a very good option for scalable enterprise apps. It uses variable protocols.

Analyzing the above, we can conclude that SSE is ideal when the data flow is unidirectional, you need it to work over the HTTP protocol and it must be easy to implement.

How Does the SSE Protocol Work?

The workings behind the scenes of the SSE protocol, in broad terms, are as follows: a server SSE endpoint needs to send an HTTP response of the type Content-Type: text/event-stream. The response looks similar to the following:

event: app-event
data: {"id":1,"time":"10:30:45","level":"Info","source":"OrderService","message":"Order #1234 placed successfully"}

In the code above, there are some fields we should pay attention to:

• event: Specifies the name of the event
• data: Is the content of the message
• id: Identifier used to perform a reconnection if needed

What’s New in .NET 10 for SSE

The most important update in .NET 10 for working with SSE is that the ability to return a ServerSentEvents using the API TypedResults.ServerSentEvents has been implemented. This means that the method TypedResults.ServerSentEvents<T>() allows converting any IAsyncEnumerable<T> into a formatted SSE stream without needing to do anything else. Tasks like JSON serialization, HTTP headers, connection closing, etc. are handled automatically.

To better understand how it works, let’s create a project using the SSE standard with ASP.NET 10.

Building an SSE Project Using ASP.NET 10

To practice the theoretical concepts covered so far, we’ll create a page that shows a simulation of receiving events from backend services in real time. Using a Progress Telerik UI for Blazor Grid, we’ll perform tasks like filtering, grouping and analysis quickly.

Creating and Configuring the Project

The first thing we’ll do is create a project using the Blazor Web App template, selecting an Interactive render mode of Server and Interactivity location of Global. Next, we’ll follow the official installation guide for Telerik UI for Blazor to configure the project and be able to use the Telerik components.

Creating an EventBroadcaster

For our project, we’ll create an event broadcaster, which in simple terms will be a bus that SSE clients can connect to to consume events, while backend services will use it to publish events. First, we’ll create a record that represents a system event:

namespace SSEDemo.Services
{
    public record AppEvent(int Id, string Time, string Level, string Source, string Message);
}

Next, we will create the class EventBroadcaster which will have the following definition:

public class EventBroadcaster
{
    //1.
    private readonly Channel<AppEvent> _channel = Channel.CreateBounded<AppEvent>(
    new BoundedChannelOptions(100) { FullMode = BoundedChannelFullMode.DropOldest });

    private int _nextId;

    // 2.
    public void Publish(string level, string source, string message)
    {
        var id = Interlocked.Increment(ref _nextId);
        var evt = new AppEvent(id, DateTime.Now.ToString("HH:mm:ss"), level, source, message);
        _channel.Writer.TryWrite(evt);
    }

    // 3.
    public async IAsyncEnumerable<AppEvent> Subscribe(
        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            bool hasData;
            try
            {
                hasData = await _channel.Reader.WaitToReadAsync(ct);
            }
            catch (OperationCanceledException)
            {
                yield break;
            }

            if (!hasData) yield break;

            while (_channel.Reader.TryRead(out var evt))
            {
                yield return evt;
            }
        }
    }
}

In the code above, we have the following sections:

1. Sets up the channel where events will be passed, with a queue limit of 100 messages. FullMode = BoundedChannelFullMode.DropOldest allows that if the queue fills up and a new message arrives, the oldest one is removed to make room for the new message.

2. The method Publish is the one that will be used to emit events. Interlocked.Increment allows generating sequential IDs in a safe manner, while AppEvent packages the received data together with the obtained id. Finally the method TryWrite() attempts to write the event to the channel asynchronously.

3. On the other hand, the method Subscribe returns a continuous stream of asynchronous data through the use of IAsyncEnumerable<AppEvent>. Inside its implementation an infinite loop is created that waits for data to be available in the channel. Once an event enters the channel, it is emitted to the consumer. This will happen until the CancellationToken called ct is canceled.

Generating Test Events

To test the bus defined above, we’ll create a service that simulates the activity of multiple services:

public class DemoEventGenerator(EventBroadcaster broadcaster) : BackgroundService
{
    private static readonly string[] Levels = ["Info", "Warning", "Error", "Success"];
    private static readonly string[] Sources =
        ["OrderService", "PaymentService", "InventoryService", "AuthService", "ShippingService"];
    private static readonly string[][] Messages =
    [
        ["Order #{0} placed successfully", "New customer registered", "Product viewed: SKU-{0}"],
        ["High latency detected: {0}ms", "Retry attempt #{0}", "Queue depth above threshold"],
        ["Payment failed for order #{0}", "Database timeout after {0}ms", "Service unreachable"],
        ["Deployment completed v2.{0}", "Health check passed", "Cache refreshed ({0} items)"]
    ];

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var rng = new Random();

        while (!stoppingToken.IsCancellationRequested)
        {            
            await Task.Delay(rng.Next(1500, 4000), stoppingToken);

            var levelIdx = rng.Next(Levels.Length);
            var level = Levels[levelIdx];
            var source = Sources[rng.Next(Sources.Length)];
            var templates = Messages[levelIdx];
            var message = string.Format(templates[rng.Next(templates.Length)], rng.Next(1000, 9999));

            broadcaster.Publish(level, source, message);
        }
    }
}

The previous class is a random event generator, taking a random value from the arrays Levels, Sources and Messages. In addition, through the parameter broadcaster, the new event is published to the bus.

Creating the SSE Endpoint

Now it’s time to create the SSE endpoint, which will consume the shared EventBroadcaster, with the purpose of creating the Event Feed so clients can connect to receive events:

public static class SseEndpoints
{
    public static void MapSseEndpoints(this WebApplication app)
    {        
        app.MapGet("/sse/events", (EventBroadcaster broadcaster, CancellationToken ct) =>
            TypedResults.ServerSentEvents(broadcaster.Subscribe(ct), eventType: "app-event"));
    }
}

In the code above you can notice how EventBroadcaster is injected as a parameter of MapGet. Likewise, TypedResults.ServerSentEvent is executed, which serializes the information and sends the correct SSE format to clients.

Registering Services in Program.cs

For everything to work as expected, we must register in Program.cs the different instances that will interact in the Blazor application. This means creating a singleton instance of EventBroadcaster, so that all systems have access to the same bus. Similarly, we will register DemoEventGenerator as a background service, through the method AddHostedService. This will allow simulated events to be generated in the background continuously:

var builder = WebApplication.CreateBuilder(args);
...
builder.Services.AddSingleton<EventBroadcaster>();
builder.Services.AddHostedService<DemoEventGenerator>();

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

app.MapSseEndpoints();

app.Run();

In the previous code, in addition to registering the services, MapSseEndpoints is invoked to enable SSE communication in the project.

Creating the Blazor Application

Once we have the application infrastructure ready, it’s time to move on to the UI part. At this point, let’s start by creating a JavaScript client, because the standard requires using the browser’s EventSource API. Since the project is configured as InteractiveServer, we cannot add inline script tags. To work around this, I will add a new file inside the wwwroot/js folder called sse-demos.js:

//1.
let eventFeedSource = null;

2.
export function start(dotNetRef) {
    // 3.
    if (eventFeedSource) eventFeedSource.close();

//4.
    const src = new EventSource('/sse/events');

    // 5.
    src.addEventListener('app-event', function (e) {
        dotNetRef.invokeMethodAsync('OnEventReceived', JSON.parse(e.data));
    });

    // 6.
    src.onopen = function () { dotNetRef.invokeMethodAsync('OnConnectionChanged', true); };
    src.onerror = function () { dotNetRef.invokeMethodAsync('OnConnectionChanged', false); };

    eventFeedSource = src;
}

//7.
export function stop() {
    if (eventFeedSource) {
        eventFeedSource.close();
        eventFeedSource = null;
    }
}

The previous code does the following:

1. A variable eventFeedSource is created to keep information about whether there is an active connection with the server.
2. A function named start should be called from C# code when you want to start receiving information…
3. It checks whether there is an open connection, in which case it is closed.
4. It tells the browser to connect to /sse/events and to listen for all events that the server sends.
5. It filters events named app-event.
6. We subscribe to the events onopen and onerror. Each will notify the method OnConnectionChanged about a change in the connection, which will allow showing a different state in the Blazor UI.
7. The function stop should be invoked to clean up memory when we want to close the connection.

With the JS functions ready, the next step is to create the Blazor component. In this new component we will use a Blazor Data Grid type component, because it is a highly configurable component that has built-in options to filter, group, etc., ideal for quickly obtaining information about events in the different systems.

To do the above, we will create a component called EventFeed.razor, which looks as follows:

@page "/events"
@rendermode InteractiveServer
@inject IJSRuntime JS
@implements IAsyncDisposable

<PageTitle>Live Event Feed</PageTitle>

<h1 class="mb-4">Live Event Feed</h1>

<div class="card shadow-sm">
    <div class="card-header d-flex align-items-center justify-content-between py-2">
        <div class="d-flex align-items-center gap-3">
            @if (isStreaming)
            {
                <span class="badge rounded-pill @(isConnected ? "bg-success" : "bg-secondary") fs-6">
                    <span class="me-1">⬤</span>@(isConnected ? "Connected" : "Disconnected")
                </span>
            }
            else
            {
                <span class="badge rounded-pill bg-warning text-dark fs-6">
                    <span class="me-1">⏸</span>Paused
                </span>
            }
            <span class="text-muted">
                Events received: <strong class="text-dark">@totalEventsReceived</strong>
            </span>
        </div>
        <div class="d-flex gap-2">
            <TelerikButton OnClick="ToggleStreaming"
                           ThemeColor="@(isStreaming ? ThemeConstants.Button.ThemeColor.Primary : ThemeConstants.Button.ThemeColor.Success)">
                @(isStreaming ? "⏸ Pause" : "▶ Resume")
            </TelerikButton>
            <TelerikButton OnClick="ClearGrid" ThemeColor="@ThemeConstants.Button.ThemeColor.Light"> Clear</TelerikButton>
        </div>
    </div>
    <div class="card-body p-0">
        <TelerikGrid Data="@events"
                     Height="560px"
                     Sortable="true"
                     Resizable="true"
                     Reorderable="true"
                     Groupable="true"                     
                     ShowColumnMenu="true">
            <GridColumns>
                <GridColumn Field="@nameof(AppEvent.Time)" Title="Time" Width="110px" />
                <GridColumn Field="@nameof(AppEvent.Level)" Title="Level" Width="120px">
                    <Template>
                        @{
                            var item = (AppEvent)context;
                        }
                        <span class="badge rounded-pill @GetBadgeClass(item.Level) px-3 py-2">@item.Level</span>
                    </Template>
                </GridColumn>
                <GridColumn Field="@nameof(AppEvent.Source)" Title="Source" Width="140px" />
                <GridColumn Field="@nameof(AppEvent.Message)" Title="Message" />
            </GridColumns>
        </TelerikGrid>
    </div>
</div>

@code {
    private List<AppEvent> events = new();
    private bool isConnected;
    private bool isStreaming = true;
    private int totalEventsReceived;
    private DotNetObjectReference<EventFeed>? dotNetRef;
    private IJSObjectReference? jsModule;
    private bool _jsInitialized;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            dotNetRef = DotNetObjectReference.Create(this);
                       
            jsModule = await JS.InvokeAsync<IJSObjectReference>("import", "./js/sse-demos.js");
                        
            await jsModule.InvokeVoidAsync("start", dotNetRef);
            
            _jsInitialized = true;
        }
    }

    [JSInvokable]
    public void OnEventReceived(AppEvent appEvent)
    {
        totalEventsReceived++;
        var updated = new List<AppEvent>(events);
        updated.Insert(0, appEvent);
        if (updated.Count > 50)
            updated.RemoveRange(50, updated.Count - 50);
        events = updated;
        InvokeAsync(StateHasChanged);
    }

    [JSInvokable]
    public void OnConnectionChanged(bool connected)
    {
        isConnected = connected;
        InvokeAsync(StateHasChanged);
    }

    private async Task ToggleStreaming()
    {
        isStreaming = !isStreaming;
        
        if (jsModule is not null)
        {
            if (isStreaming)
                await jsModule.InvokeVoidAsync("start", dotNetRef);
            else
                await jsModule.InvokeVoidAsync("stop");
        }
    }

    private void ClearGrid()
    {
        events = new List<AppEvent>();
        StateHasChanged();
    }

    private string GetBadgeClass(string level) => level switch
    {
        "Info" => "bg-info text-dark",
        "Warning" => "bg-warning text-dark",
        "Error" => "bg-danger",
        "Success" => "bg-success",
        _ => "bg-secondary"
    };

    public async ValueTask DisposeAsync()
    {
        if (_jsInitialized && jsModule is not null)
        {
            try
            {                
                await jsModule.InvokeVoidAsync("stop");
                                
                await jsModule.DisposeAsync();
            }
            catch
            {                
            }
        }
        dotNetRef?.Dispose();
    }

    public class AppEvent
    {
        public int Id { get; set; }
        public string Time { get; set; } = string.Empty;
        public string Level { get; set; } = string.Empty;
        public string Source { get; set; } = string.Empty;
        public string Message { get; set; } = string.Empty;
    }
}

In the previous code, there are some points to highlight:

• jsModule dynamically loads the JS module.
• The variable dotNetRef wraps the instance of the Blazor component that we will use inside the JS code.
• The method InvokeVoidAsync is used both to start and to stop the event streaming.
• The method OnEventReceived is invoked from the JS code each time an event is received. This allows updating the list events to show the new information in TelerikGrid.
• The OnConnectionChanged method receives a connection status from the JS code to update the UI according to any change in the connection.

With the new component ready, we can test the application, which looks like the following:

With this, we verify that everything works correctly. Also, thanks to the Blazor DataGrid capabilities, we can perform operations such as monitoring only those high-severity events:

With this we have a nice event viewer that monitors the status of multiple fictitious systems.

Conclusion

Throughout this article you have learned about the SSE standard. You have also seen how changes introduced in .NET 10 help simplify the creation of SSE endpoints, enabling the creation of applications that send real-time events to clients. Now it’s your turn to explore when you might use this web standard in your own projects. See you in the next article!

Try all this yourself with a free 30-day trial of Telerik UI for Blazor.

Try Now

Testing a web API involves much more than simply checking whether methods return or send data correctly. It requires validating real-world behaviors like pagination, unique keys, data persistence and other database rules. Anticipating and reproducing these scenarios can be challenging, especially when they depend on specific query behaviors or stored data.

To address this, the .NET ecosystem provides powerful tools for unit testing. In this post, we explore how in-memory SQLite serves as an effective solution for testing ASP.NET Core APIs, enabling developers to simulate common scenarios without deploying a real database. Additionally, we demonstrate how tools like Progress Telerik JustMock can streamline test implementation and help validate business rules efficiently.

The Importance of Testing in Real-World Environments

A common example of functionality in web APIs is paginated search, which at first glance is quite simple. We receive parameters such as page and pageSize, apply a Skip and a Take, return the data and move on. In a controlled scenario, with few records, it’s difficult for something to go wrong.

The problem begins when this code reaches production or even test environments, without having been validated with a real database. Consider a common scenario: in a paginated search, sorting is essential for it to function correctly. Without an explicit OrderBy, the database does not guarantee the order of the returned records.

In in-memory lists, the result usually appears stable, which completely masks the problem. Without tests running this query on a relational database, the error goes unnoticed, resulting in inconsistent pagination with duplicate records between pages, items “disappearing” when navigating between pages or different results for the same request. This type of bug is especially difficult to reproduce locally when not using a real database or even a simulation of one.

This is where the in-memory database plays a very important role. It allows the query to be executed exactly as it will be executed in production, revealing flaws that only appear when pagination, sorting and the database work together.

Understanding In-Memory SQLite

In-memory SQLite is a way to use the SQLite database entirely in memory. Instead of saving data to a .db file, SQLite creates the database only while the application or connection is active. When the connection is closed, all data is discarded.

In-memory SQLite is widely used in automated testing, especially in ASP.NET Core applications in conjunction with Entity Framework Core, as it has advanced features such as simulating a real database and executing real SQL (constraints, indexes, unique keys, FK and others).

Testing with SQLite in Memory

Next, we’ll look at some examples of unit tests in common web API scenarios where in-memory SQLite excels. But first, let’s create the basic application and then add the tests.

You can access all the code discussed in this post in this GitHub repository: Memo Order source code.

To create the application you can use the command below:

dotnet new web -o MemoOrder

To add the NuGet packages you can use the following commands:

dotnet add package Microsoft.EntityFrameworkCore --version 10.0.1
dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 10.0.1

Then, open the application and create the following classes:

namespace MemoOrder;

public class Order
{
    public int Id { get; set; }
    public string Number { get; set; } = string.Empty;
    public decimal TotalAmount { get; set; }
    public DateTime CreatedAt { get; set; }
    public bool IsDeleted { get; set; }
}

namespace MemoOrder;

public class OrderSummaryDto
{
    public string Number { get; set; }
    public decimal Total { get; set; }
}

using Microsoft.EntityFrameworkCore;

namespace MemoOrder;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options) { }

    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>(entity =>
        {
            entity.HasKey(o => o.Id);
            entity.Property(o => o.Number).IsRequired();
            entity.HasIndex(o => o.Number).IsUnique();
entity.HasQueryFilter(o => !o.IsDeleted);
        });
    }
}

using Microsoft.EntityFrameworkCore;

namespace MemoOrder;

public class OrderRepository
{
    private readonly AppDbContext _context;

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

    public async Task AddAsync(Order order)
    {
        _context.Orders.Add(order);
        await _context.SaveChangesAsync();
    }

    public async Task<List<Order>> Pagination(AppDbContext context, int skip, int take)
    {
        return await context.Orders
                    .OrderBy(o => o.Id)
                    .Skip(skip)
                    .Take(take)
                    .ToListAsync();
    }
}

Now let’s create a special factory class that will be used in the tests to create the in-memory database and keep the connection open while the tests are running. Create the following class in the application:

namespace MemoOrder;

using Microsoft.Data.Sqlite;
using Microsoft.EntityFrameworkCore;

public static class SqliteInMemoryFactory
{
    public static AppDbContext Create()
    {
        var connection = new SqliteConnection("DataSource=:memory:");
        connection.Open();

        var options = new DbContextOptionsBuilder<AppDbContext>()
            .UseSqlite(connection)
            .Options;

        var context = new AppDbContext(options);
        context.Database.EnsureCreated();

        return context;
    }
}

Note that to tell SQLite to use an in-memory database, we use DataSource=:memory: in the connection string.

Creating the Test Project

All the code needed to implement the unit tests is ready, so let’s create the test project and download the NuGet packages for it. To do this, you can use the following commands, simply run them in a terminal in the application’s root directory:

dotnet new xunit -n MemoOrder.Tests
cd MemoOrder.Tests
dotnet add package Microsoft.NET.Test.Sdk --version 18.0.1
dotnet add package xunit --version 2.9.3
dotnet add package xunit.runner.visualstudio --version 3.1.5
dotnet add package coverlet.collector --version 6.0.4
dotnet add reference ../MemoOrder/MemoOrder.csproj

Next, inside the project MemoOrder.Tests, create a new class called OrderRepositoryTests and let’s add tests to it.

Testing Persistence

The first test will be used to validate persistence—that is, to insert data into the database (which in this case will be the in-memory database). To do this, simply add the following test method to the OrderRepositoryTests class:

[Fact]
public async Task AddAsync_ShouldPersistOrder()
{
    // Arrange
    using var context = SqliteInMemoryFactory.Create();
    var repository = new OrderRepository(context);

    var order = new Order
    {
        Number = "ORD-2026-0001",
        TotalAmount = 200m,
        CreatedAt = DateTime.UtcNow
    };

    // Act
    await repository.AddAsync(order);

    // Assert
    var savedOrder = await context.Orders.FirstAsync();

    Assert.Equal("ORD-2026-0001", savedOrder.Number);
    Assert.Equal(200m, savedOrder.TotalAmount);
}

Note that we use var context = SqliteInMemoryFactory.Create(); to create and represent the database in memory. It works exactly like the EF Core context that maps database tables to class entities.

Testing Constraint UNIQUE

Another common mistake is allowing duplicate records to reach the production environment, which in many cases can have catastrophic impacts. With in-memory testing, we can anticipate problems like this. Simply create a test that verifies inserting a duplicate record will generate an exception. In this case, we could do the following:

[Fact]
public async Task Should_Throw_When_Duplicated_Order_Number()
{
    using var context = SqliteInMemoryFactory.Create();

    context.Orders.Add(new Order
    {
        Number = "ORD-001",
        TotalAmount = 100,
        CreatedAt = DateTime.UtcNow
    });

    await context.SaveChangesAsync();

    context.Orders.Add(new Order
    {
        Number = "ORD-001",
        TotalAmount = 200,
        CreatedAt = DateTime.UtcNow
    });

    await Assert.ThrowsAsync<DbUpdateException>(() => context.SaveChangesAsync());
}

In this test, we created an instance of the database in memory, added an item to the table and saved it.

Then, we tried to add the same item, which generates an exception because, in the dbContext configuration, we declared the Number property of the Order entity as Unique: entity.HasIndex(o => o.Number).IsUnique();.

Thus, we have a real-world scenario, demonstrating that duplicate records will not reach the production environment, as the unit test is able to reproduce exactly the same result.

Testing Pagination

To test pagination using an in-memory database, we could do the following:

[Fact]
public async Task Should_Return_Paginated_Orders()
{
    using var context = SqliteInMemoryFactory.Create();
    var repository = new OrderRepository(context);

    for (int i = 1; i <= 10; i++)
    {
        context.Orders.Add(new Order
        {
            Number = $"ORD-{i}",
            TotalAmount = i * 10,
            CreatedAt = DateTime.UtcNow
        });
    }

    await context.SaveChangesAsync();

    List<Order> page = await repository.Pagination(context, 5, 5);

    Assert.Equal(5, page.Count);
    Assert.Equal("ORD-6", page.First().Number);
}

Note that here we create 10 items and insert them into the in-memory database. Then, we use the Pagination(context, 5, 5) method to perform the pagination and finally verify if the expected quantity and item are correct.

An in-memory database wouldn’t be mandatory to test pagination. This could be done using only regular in-memory lists. However, in this way, we can reproduce the same production scenario.

Testing Soft Delete

Soft-delete is a technique where data is not physically removed from the database, but rather marked as inactive through a flag, such as an isDeleted or deleted_at column. This allows you to keep the entire transaction history in the database.

The problem is that in some cases soft delete can leak unwanted data into reports, new endpoints or even refactored queries. To prevent this from happening, we can use the in-memory database and simulate a search with and without soft-delete:

[Fact]
 public async Task SoftDeleted_Orders_Should_Not_Appear_In_Default_Queries()
 {
     using var context = SqliteInMemoryFactory.Create();

     context.Orders.AddRange(
         new Order
         {
             Number = "ORD-001",
             TotalAmount = 100,
             CreatedAt = DateTime.UtcNow,
             IsDeleted = false
         },
         new Order
         {
             Number = "ORD-002",
             TotalAmount = 200,
             CreatedAt = DateTime.UtcNow,
             IsDeleted = true
         }
     );

     await context.SaveChangesAsync();

     var orders = await context.Orders.ToListAsync();

     Assert.Single(orders);
     Assert.Equal("ORD-001", orders.First().Number);
 }

In this test, the list returns only one item because the second one is marked as deleted. This happens because we declared the query filter entity.HasQueryFilter(o => !o.IsDeleted); when the database is created. By using an in-memory database, we can verify this mechanism works.

It’s also possible to ignore the query filter and still verify it works:

[Fact]
public async Task Admin_Query_Should_See_SoftDeleted_Orders()
{
    using var context = SqliteInMemoryFactory.Create();

    context.Orders.AddRange(
        new Order
        {
            Number = "ORD-001",
            TotalAmount = 100,
            CreatedAt = DateTime.UtcNow,
            IsDeleted = false
        },
        new Order
        {
            Number = "ORD-002",
            TotalAmount = 200,
            CreatedAt = DateTime.UtcNow,
            IsDeleted = true
        }
    );

    await context.SaveChangesAsync();

    var orders = await context.Orders.IgnoreQueryFilters().ToListAsync();

    Assert.Equal(2, orders.Count);
}

Testing Rollback

When performing multiple operations, we run the risk of something failing during the process and the data becoming inconsistent. To keep this from happening, we can use the in-memory database to test if the rollback operation solves this problem.

[Fact]
public async Task Transaction_Should_Rollback_When_Error_Occurs()
{
    using var context = SqliteInMemoryFactory.Create();

    using var transaction = await context.Database.BeginTransactionAsync();

    context.Orders.Add(new Order
    {
        Number = "ORD-NMBR-1",
        TotalAmount = 100,
        CreatedAt = DateTime.UtcNow
    });

    await context.SaveChangesAsync();

    await transaction.RollbackAsync();

    var count = await context.Orders.CountAsync();

    Assert.Equal(0, count);
}

In this test, we added an item to the order list, saved it and then performed a rollback. Finally, we verified that the list was empty, checking that the operation was undone.

Testing Query Refactoring

Refactoring queries is often necessary, whether to improve performance or simply to make the code cleaner. The problem is that this can break queries that previously worked.

To see that both the old and new queries have the same result, we can use an in-memory database as demonstrated in the example below:

   [Fact]
    public async Task Refactored_Query_Should_Return_Same_Result()
    {
        using var context = SqliteInMemoryFactory.Create();

        var oldResult = await context.Orders
            .Where(o => o.TotalAmount > 100)
            .Select(o => o.Id)
            .ToListAsync();

        var newResult = await context.Orders
            .Select(o => new { o.Id, o.TotalAmount })
            .Where(o => o.TotalAmount > 100)
            .Select(o => o.Id)
            .ToListAsync();

        Assert.Equal(oldResult, newResult);
    }

In this example, we verify that both queries have the same result, so even after refactoring, the old logic will continue to work.

Query Test with Projection to DTO

When using Data Transfer Objects (DTOs) for data transport, we are subject to errors that can silently break our queries. Again, with an in-memory database, we can simulate a query using a DTO.

   [Fact]
    public async Task Projection_To_Dto_Should_Work()
    {
        using var context = SqliteInMemoryFactory.Create();

        var result = await context.Orders
            .Select(o => new OrderSummaryDto
            {
                Number = o.Number,
                Total = o.TotalAmount
            })
            .ToListAsync();

        Assert.NotNull(result);
    }

Note that through this test, we can be sure that our DTOs will function correctly.

Not All Tests Need a Database

Until now, we’ve used in-memory SQLite to validate constraints (UNIQUE), global filters (Soft Delete), real pagination, GroupBy, Sum, transactions and rollback.

Tests like these depend on database behavior, but it’s common to encounter scenarios where the database isn’t present, and only business rules are involved. In this case, to facilitate our work and validate our tests, we can use tools like JustMock and simulate a production-facing environment.

Next, we’ll look at some examples of business rule tests where we can use JustMock to easily create mocks for our tests.

Verifying the Repository Will Be Called

[Fact]
public async Task CreateAsync_Should_Call_Repository_AddAsync()
{
    // Arrange
    var repository = Mock.Create<IOrderRepository>();

    var order = new Order
    {
        Id = 1,
        Number = "ORD-001"
    };

    Mock.Arrange(() => repository.AddAsync(order))
        .Returns(Task.CompletedTask)
        .MustBeCalled();

    var service = new OrderService(repository);

    // Act
    await service.CreateAsync(order);

    // Assert
    Mock.Assert(repository);
}

Verifying the GetHighValueOrders Method Returns Only Orders Above the Minimum Value

[Fact]
public void GetHighValueOrders_Should_Return_Only_Orders_Above_MinValue()
{
    // Arrange
    var repository = Mock.Create<IOrderRepository>();

    var orders = FakeOrders()
        .Where(o => o.TotalAmount >= 150 && !o.IsDeleted)
        .ToList();

    Mock.Arrange(() => repository.GetHighValueOrders(150))
        .Returns(orders);

    var service = new OrderService(repository);

    // Act
    var result = service.GetHighValueOrders(150);

    // Assert
    Assert.AreEqual(1, result.Count);
    Assert.IsTrue(result.First().TotalAmount >= 150);
}

Verifying the Service Forwards Exactly the Filter Received

       [Fact]
        public void GetHighValueOrders_Should_Call_Repository_With_Same_MinValue()
        {
            // Arrange
            var repository = Mock.Create<IOrderRepository>();

            Mock.Arrange(() => repository.GetHighValueOrders(500))
                .Returns(new List<Order>())
                .MustBeCalled();

            var service = new OrderService(repository);

            // Act
            service.GetHighValueOrders(500);

            // Assert
            Mock.Assert(repository);
        }

If you run all the tests, you can verify that they all passed:

Conclusion

Testing web applications is common in software development, but these tests don’t always guarantee that errors won’t occur in the production environment. Using in-memory databases, such as in-memory SQLite, allows you to reproduce scenarios closer to reality.

In this post, we saw how this approach helps identify common errors, such as persistence, pagination and projection issues. Furthermore, we explored how JustMock can help save time when validating business rules. I hope the content covered here helps you further improve your applications, making them more reliable through even more realistic testing.

Try JustMock free for 30 days, or try out the whole Telerik DevCraft suite for access to the ASP.NET Core component library and lots more (also a free 30-day trial).

Progress Telerik Document Processing Libraries, in addition to letting you work with a variety of document formats (PDF, DOCX, RTF, HTML, XLSX and more), are an example of the reason you buy into a suite of tools: All the tools bear a “family resemblance.”

The ideal scenario, of course, would be for a single tool that made all these document formats look the same. Given the differences in format and functionality between, for example, a PDF, a Microsoft Word (or RTF or HTML) document and an Excel spreadsheet, that’s not reasonable (though Progress Telerik has achieved that with DOCX, RTF and HTML documents).

The good news here is that, with Telerik Document Processing Libraries (DPL), the family resemblance is strong enough that, for all of the document types the library supports, I can show you how to load documents, start the editing process, convert between various document types and save a document in this one post.

Configuring Your Project

The sample code in this post was all written using the DPL for Windows libraries (even though I was working in ASP.NET Core—the more technical name for the version I used is “.NET(Target OS: Windows).” The suite is also available for the .NET Framework.

To create an ASP.NET Core project that would work with “all the documents,” I added these NuGet packages to my project:

• To work with PDF files: Telerik.Windows.Documents.Fixed
• To work with DOCX, HTML and RTF files: Telerik.Windows.Documents.Flow
• To work with Excel spreadsheets: Telerik.Windows.Documents.Spreadsheet

For the Excel spreadsheets, I’m only going to work with XLSX files, so I added the Telerik.Windows.Documents.Spreadsheet.FormatProviders.OpenXml package to my project. (If I was going to work with, for example, XLS spreadsheet, then I would have added the Telerik.Documents.Spreadsheet.FormatProviders.Xls package.)

Loading Your Document

The code to load a document from a file into any of these libraries is very similar:

1. Create the appropriate provider.
2. Use the .NETFile object’s OpenRead to create a Stream that points to the file.
3. Use the provider’s Import method to load the stream into the document object.

Here, for example, is the code to load a PDF file into a RadFixedDocument object (I used this code in an ASP.NET Core application with documents in my project’s wwwroot folder):

RadFixedDocument doc;
PdfFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.pdf"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

And here’s the code to load a DOCX file into a RadFlowDocument:

RadFlowDocument doc;
DocxFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.docx"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

As you can see, the code is identical except for the provider (PdfFormatProvider vs. DocxFormatProvider) and document objects (RadFlowDocument vs. RadFixedDocument).

Because both RTF and HTML documents load into the same RadFlowDocument object as a DOCX document, only the provider object changes (HtmlFormatProvider or RtfFormatProdiver instead of DocxFormatProvider) when working with those file formats. Here’s the code to load an RTF document:

RadFlowDocument doc;
RtfFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.rtf"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

And here’s the almost identical code to load an HTML file:

RadFlowDocument doc;
HtmlFormatProvider prov = new();

using (Stream str = File.OpenRead(@"wwwroot/documents/Priorities.html"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

The code to load an Excel workbook is also similar to what you’ve seen before, just swapping in a new document object (Workbook) and provider (XlsxFormatProvider):

Workbook doc;
XlsxFormatProvider prov = new();
using (Stream str = File.OpenRead(@"wwwroot/documents/priority.xlsx"))
{
    doc = prov.Import(str, TimeSpan.FromSeconds(10));
}

A note: The Workbook object assumes that you’re going to load the whole Excel workbook into memory. For very large workbooks, that may not make sense. For that scenario, you should look at the SpreadStreamProcessing Library.

Modifying the Documents

Once you’ve loaded the documents, you can start working with them. You can often simplify your code by using the RadFixedDocumentEditor with PDF documents or the RadFlowDocumentEditorwith Word/RTF/HTML documents. Not surprisingly, the code for creating an editor is almost identical for these two document types: create an editor object and pass the document you want loaded into the editor.

The code to create an editor for a PDF document looks like this:

RadFixedDocumentEditor editor = new RadFixedDocumentEditor(doc);

The code for Word/RTF/HTML documents looks like this:

RadFlowDocumentEditor editor = new RadFlowDocumentEditor(doc);

That’s not to say that, as you start working with those documents, there aren’t going to be differences. These are, after all, very different kinds of documents. Having said that, some functionality does work in a similar way across all the document types.

If, for example, I want to search a PDF document for the text “ASP.NET,” I create a TextSearch instance from my document object. I then use the TextSearch object’s FindAll method to search for text in my PDF document, passing two things: my search text and a TextSearchOptions object that specifies how I want my search conducted. That FindAll object returns a collection of SearchResult objects that I can loop through.

Typical code, then, looks like this:

TextSearch search = new TextSearch(doc);
TextSearchOptions opts = new() {
CaseSensitive = false,
WholeWordsOnly = true,
UseRegularExpression = true
                                                              };

IEnumerable<SearchResult> items = search.FindAll("ASP.NET", opts);

Debug.Print($"Found {items.Count()} items.");
foreach (SearchResult item in items)
{
    Debug.Print($"Found at {item.Range.StartPosition} ");
    Debug.Print($"Found: {item.Result}");
}

The process is almost identical for the RadFlowDocument object, except:

• You call the FindAllmethod directly from the RadFlowDocumentEditor.
• There isn’t a separate options object (though all the search options from the TextSearch object are still available).
• The FindAll method on the editor returns FindResult objects instead of SearchResult objects.

As a result, the equivalent search code for a DOCX, RTF or HTML document looks like this:

RadFlowDocumentEditor editor = new RadFlowDocumentEditor(doc);

IEnumerable<FindResult> items = editor.FindAll("ASP.NET");

Debug.Print($"Found {items.Count()} items.");
foreach (FindResult item in items)
{
    Debug.Print($"Found at {item.RelativeStartIndex} ");
    Debug.Print($"Found: {item.FullMatchText}");
}

Searching a spreadsheet works similarly. The differences:

• The FindAll method is built right into the Workbook object.
• You have more search options available with the spreadsheet object.
• You pass your search string as part of the options object.

My find code with a workbook would look like this:

FindOptions opts = new() {
FindWhat = "ASP.NET",
MatchCase = false,
MatchEntireCellContents = true,
                                                };

IEnumerable<FindResult> items = doc.FindAll(opts);

Debug.Print($"Found {items.Count()} items.");
foreach(FindResult item in items)
{
    Debug.Print($"Found at {item.FoundCell.CellIndex} ");
    Debug.Print($"Found: {item.ResultValue}");
}

One note: It is certainly convenient when objects from the different libraries share the same name (like the FindResult object that’s defined in both the RadFlowDocument and Workbook libraries). However, if you try to use both FindResult objects in the same code file, the compiler will get confused because the two objects are in different namespaces. In the unlikely case that you’re working with both Excel and Word documents in the same code file, you’ll have to fully qualify the object names—something I haven’t done in this post.

Saving Your Documents

To save your modified documents back to disk, you just need to use the provider’s Export method. The code for all the document types is identical:

using (Stream str = File.Create(@"wwwroot/documents/Prioritiesnew.<filetype>"))
{
    prov.Export(doc,str, TimeSpan.FromSeconds(10));
}

Converting Documents

You can convert from one type in the suite to other types and, not surprisingly, the conversion processes look very much alike. As you’ve seen before, it often comes down to using the right provider.

If, for example, you want plain text version of your PDF file, you use the TextFormatProvider object’s Export method:

TextFormatProvider prov = new();
string text = prov.Export(doc, TimeSpan.FromSeconds(10));

For Word/HTML/RTF document types, the code is almost identical except it uses the TxtFormatProvider object:

TxtFormatProvider txProv = new();
string text = prov.Export(doc, TimeSpan.FromSeconds(10));            

One note: There is a downside to having the classes that do similar things to different document types have the same name. If you are mixing document types and, as a result, using the Fixed, Flow and spreadsheet libraries in the same application, the compiler can get confused about which class from which library you’re using. If so, you’ll have to fully qualify your class names by including their namespaces in the class names. That makes for hard-to-read code, so I haven’t done that here.

But, as an example of how different documents require different functionality, you probably wouldn’t ever want to convert an Excel workbook to a string … but you might want to save your workbook as a CSV file. As you might expect by now, the code to save your imported workbook into a CSV file just means using the Export method on the appropriate provider—the CsvFormatProvider object in this case.

Typical code would look like this:

CsvFormatProvider prov = new();

using (Stream str = File.Create("Priority.csv"))
{
    prov.Export(doc, str, TimeSpan.FromSeconds(10));
}

Converting any of these document types (Excel, Word, HTML, etc.) to PDF is equally straightforward. Because all the libraries look very much alike, it’s really just a matter of adding the library with the provider you need.

But you can also convert your Workbook object into a RadFixedDocument if you wanted to manipulate your spreadsheet as a PDF object. That conversion is handled by the PdfFormatProvider from the Telerik.Windows.Documents.Spreadsheet.Formatproviders.Pdf package and using its ExportToFixedDocumentmethod:

PdfFormatProvider prov = new();

RadFixedDocument fixedDoc = 
        prov.ExportToFixedDocument(doc, TimeSpan.FromSeconds(10));

The code is identical if you want to convert a Word/RTF/HTML document to a RadFixedDocument to work with it as a PDF file. That conversion also uses a PdfFormatProvider object but, this time, from the Telerik.Windows.Documents.Flow.FormatProviders.Pdf namespace.

But, because the providers from the two libraries have the same name, if you’re using both libraries in the same code file, you will need to fully qualify your provider names to make sure you’re getting the appropriate PdfFormatProvider.

Of course, once you start using these tools to create or modify the documents you’ve loaded, you’ll find more differences—the functionality in a spreadsheet is very different from the functionality in an HTML document. But, while the family resemblances among this suite won’t eliminate those differences, it does cut those differences down to what matters: how those documents differ in their functionality. Which is, after all, what you want.

Explore Telerik Document Processing Libraries, plus component libraries, reporting and more with a free trial of the Telerik DevCraft bundle:

Try DevCraft

In contrast to traditional Controller classes, minimal APIs offer a more compact way to create web APIs. The downside of this approach is that the Program class can quickly become bloated. To overcome this problem, we can use some approaches and libraries that help organize the mess and bring order to things.

In this post, we’ll create a Minimal API with a disorganized Program class and then refactor it into a clean and elegant version. We’ll also explore a very versatile approach using the Carter library.

One Class to Rule Them All

.NET 6 introduced a new format for creating web APIs, eliminating the need for the Startup class and even the Controller classes, responsible for HTTP input and output methods.

In the Minimal APIs model, the Program class, previously responsible only for bootstrapping the application, now also concentrates everything that was previously in Startup and Controller: service configuration, middleware definition and endpoint mapping.

This unification considerably reduced the number of classes in the project, but also opened the door to a common problem: the tendency to transform Program.cs into an inflated, confusing and difficult-to-maintain file.

Without a structured approach to organizing these responsibilities, what should be minimalist can quickly become something far from it. Therefore, adopting strategies and tools that help modularize routes, configurations and business rules is not only a good practice but also essential for maintaining the scalability and clarity of the project.

Organization Is the Key ️

When working with Minimal APIs, the tendency is to put everything in the Program class, but the truth is that this class wasn’t designed to be a repository, but rather to orchestrate the application. Keeping this class clean, small and focused on composition is the secret to preserving readability and facilitating code evolution.

And this is only possible when we use consistent organization: separating modules, extracting configurations, delegating routes and preventing implementation details from leaking to the highest level of the application.

In this section, we’ll first create a messy example and then transform Program.cs into a truly minimalist entry point, taking in only what it should take in, while moving the rest to the most appropriate places.

Creating the Project

The complete application code is available in this GitHub repository: Customer Admin source code.

To create the base application, you can use the command below:

dotnet new web -n CustomerAdmin

Then, open the application and add the following dependencies to the .csproj file:

 <ItemGroup>
    <PackageReference Include="Microsoft. EntityFrameworkCore" Version="10.0.1" />
    <PackageReference Include="Microsoft. EntityFrameworkCore .SqlServer" Version="10.0.1" />
    <PackageReference Include="Microsoft. EntityFrameworkCore .Design" Version="10.0.1">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

Now let’s move on to the grand finale, the monstrous Program.cs class. Replace the code in the Program class with the code below:

using Microsoft.EntityFrameworkCore;
using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddLogging(logging =>
{
    logging.ClearProviders();
    logging.AddConsole();
});

builder.Services.AddHttpClient();
builder.Services.AddEndpointsApiExplorer();

builder.Services.AddCors(options =>
{
    options.AddPolicy("Default", policy =>
    {
        policy.AllowAnyOrigin().AllowAnyHeader().AllowAnyMethod();
    });
});

builder.Services.AddSingleton<IEmailSender, SmtpEmailSender>();

var app = builder.Build();

app.UseCors("Default");

app.Use(async (context, next) =>
{
    var logger = context.RequestServices.GetRequiredService<ILoggerFactory>().CreateLogger("RequestLogger");
    logger.LogInformation("Request: {method} {url}", context.Request.Method, context.Request.Path);
    await next();
});

app.MapPost("/customers", async (CustomerDto dto, AppDbContext db, IEmailSender email) =>
{
    if (string.IsNullOrWhiteSpace(dto.Name))
        return Results.BadRequest("Name is required");

    if (!new EmailAddressAttribute().IsValid(dto.Email))
        return Results.BadRequest("Invalid email");

    var entity = new Customer
    {
        Name = dto.Name,
        Email = dto.Email,
        CreatedAt = DateTime.UtcNow
    };

    db.Customers.Add(entity);
    await db.SaveChangesAsync();

    await email.SendAsync(dto.Email, "Welcome!", "Thanks for registering!");

    return Results.Created($"/customers/{entity.Id}", entity);
});

app.MapGet("/customers", async (AppDbContext db) =>
{
    var items = await db.Customers.ToListAsync();
    return Results.Ok(items);
});

app.MapGet("/customers/{id:int}", async (int id, AppDbContext db) =>
{
    var customer = await db.Customers.FindAsync(id);
    return customer is null ? Results.NotFound() : Results.Ok(customer);
});

app.MapPost("/customers/{id:int}/activate", async (int id, AppDbContext db) =>
{
    var customer = await db.Customers.FindAsync(id);
    if (customer is null)
        return Results.NotFound();

    if (customer.IsActive)
        return Results.BadRequest("Customer already active");

    customer.IsActive = true;
    await db.SaveChangesAsync();

    return Results.Ok(customer);
});

app.Run();

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
    public bool IsActive { get; set; }
    public DateTime CreatedAt { get; set; }
}

public class CustomerDto
{
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
}

public interface IEmailSender
{
    Task SendAsync(string to, string subject, string body);
}

public class SmtpEmailSender : IEmailSender
{
    public Task SendAsync(string to, string subject, string body)
    {
        Console.WriteLine($"Sending email to {to}: {subject}");
        return Task.CompletedTask;
    }
}

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<Customer> Customers => Set<Customer>();
}

The code above demonstrates the type of architecture that starts simple but quickly becomes a serious problem as the application grows. The Program class should only be the compose root of the application, where services are registered, middlewares are configured and high-level endpoints are mapped. Instead, the code above:

• Validates data
• Accesses the database
• Implements business rules
• Sends emails
• Defines DTOs, entities, services and DbContext
• Registers all services manually
• Writes middleware logic directly in it
• Maps detailed and complex endpoints

The result is a single file that performs the work of about 10 different files, resulting in something that grows uncontrollably and prevents the healthy evolution of the application. Each new feature exacerbates the problem, leaving the class disorganized and prone to errors. Furthermore, it hinders teamwork, generates merge conflicts and makes the integration of new developers much slower.

Putting Things in Order

Now that we’ve seen a bad example of a bloated and messy Program class, let’s put things in order, separating each part into its proper place.

The image below shows what the complete application structure will look like at the end of the post:

So, let’s start with the entities, for which we can create separate classes. In this case, create a new folder called “Model” and inside it create the classes below:

namespace CustomerAdmin.Models;

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
    public bool IsActive { get; set; }
    public DateTime CreatedAt { get; set; }
}

namespace CustomerAdmin.Models;

public class CustomerDto
{
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
}

Now let’s create all the other things related to the Infrastructure layer, which refers to everything that communicates with external services such as databases and web APIs. Create a new folder called “Infrastructure” and inside it create a new folder called “Data” and add the following class to it:

using CustomerAdmin.Models;
using Microsoft.EntityFrameworkCore;

namespace CustomerAdmin.Infrastructure.Data;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options) { }

    public DbSet<Customer> Customers => Set<Customer>();
}

All subsequent folders should be created inside the Infrastructure folder. So, add another folder called “Email” and, inside it, add the following interface and class:

namespace CustomerAdmin.Infrastructure.Email;

public interface IEmailSender
{
    Task SendAsync(string to, string subject, string body);
}

namespace CustomerAdmin.Infrastructure.Email;

public class SmtpEmailSender : IEmailSender
{
    public Task SendAsync(string to, string subject, string body)
    {
        Console.WriteLine($"Sending email to {to}: {subject}");
        return Task.CompletedTask;
    }
}

Here we create an interface and a class for sending emails, which is used only for demonstration purposes and is therefore very simple, but in real applications it can become large, so separating it from the Program class is essential.

The next step is to create the extension methods for the controllers, endpoints and policies. Create a new folder called “Extensions” and, inside it, create the classes below:

using System.ComponentModel.DataAnnotations;
using CustomerAdmin.Infrastructure.Data;
using CustomerAdmin.Infrastructure.Email;
using CustomerAdmin.Models;
using Microsoft.EntityFrameworkCore;

namespace CustomerAdmin.Infrastructure.Extensions;

public static class CustomerEndpoints
{
    public static async Task<IResult> CreateCustomer(
        CustomerDto dto,
        AppDbContext db,
        IEmailSender email
    )
    {
        if (string.IsNullOrWhiteSpace(dto.Name))
            return Results.BadRequest("Name is required");

        if (!new EmailAddressAttribute().IsValid(dto.Email))
            return Results.BadRequest("Invalid email");

        var entity = new Customer
        {
            Name = dto.Name,
            Email = dto.Email,
            CreatedAt = DateTime.UtcNow,
        };

        db.Customers.Add(entity);
        await db.SaveChangesAsync();

        await email.SendAsync(dto.Email, "Welcome!", "Thanks for registering!");

        return Results.Created($"/customers/{entity.Id}", entity);
    }

    public static async Task<IResult> GetAll(AppDbContext db)
    {
        return Results.Ok(await db.Customers.ToListAsync());
    }

    public static async Task<IResult> GetById(int id, AppDbContext db)
    {
        var customer = await db.Customers.FindAsync(id);
        return customer is null ? Results.NotFound() : Results.Ok(customer);
    }

    public static async Task<IResult> Activate(int id, AppDbContext db)
    {
        var customer = await db.Customers.FindAsync(id);

        if (customer is null)
            return Results.NotFound();
        if (customer.IsActive)
            return Results.BadRequest("Customer already active");

        customer.IsActive = true;
        await db.SaveChangesAsync();

        return Results.Ok(customer);
    }
}

Here we add all the endpoints for the new customer registration API. Note that the methods are static so they can be used by the endpoint mapper that we will create next.

So now create a new class called CustomersModule and add the following code to it:

namespace CustomerAdmin.Infrastructure.Extensions;

public static class CustomersModule
{
    public static IEndpointRouteBuilder MapCustomerEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/customers");

        group.MapPost("/", CustomerEndpoints.CreateCustomer);
        group.MapGet("/", CustomerEndpoints.GetAll);
        group.MapGet("/{id:int}", CustomerEndpoints.GetById);
        group.MapPost("/{id:int}/activate", CustomerEndpoints.Activate);

        return app;
    }
}

In the code above, we define an endpoint module where we use an extension method to encapsulate the mapping of routes related to customers. All routes are grouped with the prefix /customers, which allows for scalable application growth and facilitates API organization.

Now let’s create another extension class to define the registration of application services in the ASP.NET Core dependency injection container. This class will centralize the configuration of application dependencies such as infrastructure, HTTP communication, API documentation and CORS policies. So, still in the “Extensions” folder, add the class below:

using CustomerAdmin.Infrastructure.Data;
using CustomerAdmin.Infrastructure.Email;
using Microsoft.EntityFrameworkCore;

namespace CustomerAdmin.Infrastructure.Extensions;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddApplicationServices(this IServiceCollection services)
    {
        services.AddScoped<IEmailSender, SmtpEmailSender>();
        return services;
    }

    public static IServiceCollection AddInfrastructure(
        this IServiceCollection services,
        IConfiguration config
    )
    {
        services.AddDbContext<AppDbContext>(options =>
            options.UseSqlServer(config.GetConnectionString("DefaultConnection"))
        );

        services.AddHttpClient();
        return services;
    }

    public static IServiceCollection AddApiDocumentation(this IServiceCollection services)
    {
        services.AddEndpointsApiExplorer();
        return services;
    }

    public static IServiceCollection AddCorsPolicies(this IServiceCollection services)
    {
        services.AddCors(options =>
        {
            options.AddPolicy(
                "Default",
                policy => policy.AllowAnyOrigin().AllowAnyHeader().AllowAnyMethod()
            );
        });
        return services;
    }
}

Note that here we have several configurations grouped into a separate file, leaving the Program class free for what it is actually responsible for.

Now let’s create the class responsible for implementing the configurations that belong to the WebApplication class. So, create a new class called WebApplicationExtensions and add the code below to it:

using CustomerAdmin.Infrastructure.Middlewares;

namespace CustomerAdmin.Infrastructure.Extensions;

public static class WebApplicationExtensions
{
    public static IApplicationBuilder UseApiDocumentation(this WebApplication app)
    {
        return app;
    }

    public static IApplicationBuilder UseCorsPolicies(this WebApplication app)
    {
        app.UseCors("Default");
        return app;
    }

    public static WebApplication UseRequestLogging(this WebApplication app)
    {
        app.UseMiddleware<RequestLoggingMiddleware>();
        return app;
    }
}

The last configuration class will be used to implement logging middleware. So, create a new class called RequestLoggingMiddleware and add the code below to it:

namespace CustomerAdmin.Infrastructure.Middlewares;

public class RequestLoggingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<RequestLoggingMiddleware> _logger;

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

    public async Task InvokeAsync(HttpContext context)
    {
        _logger.LogInformation("Request: {method} {url}", context.Request.Method, context.Request.Path);
        await _next(context);
    }
}

With all the implementations organized, we can finally implement the method calls in the Program class. So, replace the existing code there with the code below:

using CustomerAdmin.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder
    .Services.AddApplicationServices()
    .AddInfrastructure(builder.Configuration)
    .AddApiDocumentation()
    .AddCorsPolicies();

var app = builder.Build();

app.UseRequestLogging();
app.UseApiDocumentation();
app.UseCorsPolicies();

app.MapCustomerEndpoints();

app.Run();

See how the Program class looks now. Instead of spreading configurations across multiple files, it centralizes the entire application initialization process in a fluid way.

Starting with the creation of the WebApplicationBuilder, responsible for preparing the environment, the configuration of services is done in a chained manner, which has greatly improved readability compared to the first version.

Each extension method represents a well-defined block of responsibility, such as registering application services, configuring the infrastructure (database, external integrations, etc.), API documentation and CORS policies.

Finally, the HTTP request pipeline, middleware and endpoint mapping are initiated. Thus, this refactored approach makes the Program class leaner and more expressive, serving as a high-level view of how the application is composed and initialized.

Taking a Shortcut with Carter

Carter is an open-source NuGet package for defining HTTP routes and request handlers using a simple and declarative syntax.

Below, we’ll use Carter in the refactored version and see how it can be a great option for organizing minimal APIs.

To download Carter to the project, simply run the command below:

dotnet add package Carter --version 10.0.0

Next, create a new folder in the project called “Modules,” inside it another folder called “Customers” and, inside that folder, create the class below:

namespace CustomerAdmin.Modules.Customers;

using System.ComponentModel.DataAnnotations;

public class CustomersModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/customers");

        group.MapPost("/", Create);
        group.MapGet("/", GetAll);
        group.MapGet("/{id:int}", GetById);
        group.MapPost("/{id:int}/activate", Activate);
    }

    private static async Task<IResult> Create(CustomerDto dto, AppDbContext db, IEmailSender email)
    {
        if (string.IsNullOrWhiteSpace(dto.Name))
            return Results.BadRequest("Name is required");

        if (!new EmailAddressAttribute().IsValid(dto.Email))
            return Results.BadRequest("Invalid email");

        var customer = new Customer
        {
            Name = dto.Name,
            Email = dto.Email,
            CreatedAt = DateTime.UtcNow,
        };

        db.Customers.Add(customer);
        await db.SaveChangesAsync();

        await email.SendAsync(dto.Email, "Welcome!", "Thanks for registering!");

        return Results.Created($"/customers/{customer.Id}", customer);
    }

    private static async Task<IResult> GetAll(AppDbContext db)
    {
        return Results.Ok(await db.Customers.ToListAsync());
    }

    private static async Task<IResult> GetById(int id, AppDbContext db)
    {
        var customer = await db.Customers.FindAsync(id);
        return customer is null ? Results.NotFound() : Results.Ok(customer);
    }

    private static async Task<IResult> Activate(int id, AppDbContext db)
    {
        var customer = await db.Customers.FindAsync(id);
        if (customer is null)
            return Results.NotFound();
        if (customer.IsActive)
            return Results.BadRequest("Customer already active");

        customer.IsActive = true;
        await db.SaveChangesAsync();

        return Results.Ok(customer);
    }
}

Note that the class we created inherits from the Carter interface: ICarterModule, which allows grouping related endpoints without coupling them to Program.cs. This isolates route definitions, validations and integrations into separate modules, making the code scalable and aligned with the true purpose of Minimal APIs: simplicity with organization.

To configure the Program class with Carter, replace the existing code with the code below:

using Carter;
using CustomerAdmin.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder
    .Services.AddApplicationServices()
    .AddInfrastructure(builder.Configuration)
    .AddApiDocumentation()
    .AddCorsPolicies();

builder.Services.AddCarter();

var app = builder.Build();

app.UseRequestLogging();
app.UseApiDocumentation();
app.UseCorsPolicies();

app.MapCarter();

app.Run();

Note that the Program class remains simple and clean using Carter. Another important point to highlight is that we have no coupling to the Program class. Instead, we pass all responsibility for the modules to Carter through dependency injection (DI), implemented by the app.MapCarter(); method.

Conclusion

Minimal APIs streamline development by offering a simple approach to creating compact endpoints. However, as the application grows, it’s common for the Program class to become extensive and disorganized if project structure isn’t carefully considered.

To minimize the chances of having an inflated Program class, we can adopt some organizational strategies. In this post, we saw an approach that clearly separates the responsibilities of each class and, to shorten the process, we used the Carter library, leaving the Program class responsible only for the configurations that truly belong to it.

I hope this post helps you create more organized APIs that are ready to evolve!

The use of artificial intelligence has become increasingly common in web applications, so it’s important to consider how to optimize the use of AI via large language models (LLMs) for efficiency and cost reduction.

In this article, we’ll explore how to use the Retrieval-Augmented Generation (RAG) concept in ASP,NET Core projects to create an automated return policy system. We’ll understand how RAG combines information retrieval and text generation to enable LLMs to respond based on real, up-to-date data, reducing the need for retraining.

Understanding the RAG Concept

Retrieval Augmented Generation, or RAG, is a technique (sometimes referred to as an architecture) used to optimize the performance of an AI model. It consists of connecting a model to an internal knowledge base, which can be a text file or even a database, to provide more relevant answers without the need for additional training.

In simple terms, instead of relying only on its training data, RAG allows the model to retrieve up-to-date or domain-specific information to generate a more accurate answer.

How Does RAG Work?

The operation of RAG basically involves combining information retrieval models with generative AI models, and then returning a more accurate result. RAG systems typically follow a five-stage process:

1. User Input (User Prompt)
   The user asks a question or sends a command, for example, “What are the company’s security policies?”

2. Information Retrieval (Retrieval)
   A retrieval model, such as a vector search engine, is triggered to search for relevant data in an external knowledge base, such as corporate documents or databases. This step transforms the prompt into embeddings and searches for the semantically closest documents.

3. Integration (Integration / Context Assembly)
   The most relevant information found is returned and combined with the original prompt. In this stage, the system assembles an augmented prompt that contains both the user’s question and the relevant snippets retrieved from the internal knowledge base.

4. Generation (Augmented Generation)
   The language model receives this augmented prompt and generates a contextualized response, taking into account the retrieved data.

5. Output to the User (Response Delivery)
   The final result is then delivered to the user, usually accompanied by references to the sources or links that support the answer.

These five steps constitute the complete RAG workflow, which goes beyond a simple question-and-answer approach. It combines querying, filtering, context assembly and contextualized generation, enabling more accurate and up-to-date responses. The image below summarizes this workflow:

Creating a RAG in ASP,NET Core

To practice using RAG, we will develop an API in ASP,NET Core that will answer questions about a product return policy. The API will retrieve the information from a knowledge base, a text file containing the return policy. This data will be converted into embeddings and stored in an SQLite database.

Then, the API will send the relevant content to the OpenAI API, which will generate a contextualized response and return it in the request response.

You can check the complete source code in this GitHub repository: Return Policy source code.

Prerequisites

To practice the example in this tutorial, you will need to have the following:

1. API Key. If you don’t already have an API key, you can use this tutorial to create it: Get Started Integrating AI in Your ASP.NET Core Applications.

2. A project created on the OpenAI website

3. The following models configured in your API key:

You can use other models of your choice, but other libraries and additional configurations may be necessary.

So, to create the sample application and download the packages you can use the following commands on the terminal:

dotnet new web -o ReturnPolicy

dotnet add package Microsoft.Data.Sqlite --version 9.0.10
dotnet add package OpenAI --version 2.5.0

Next, let’s create the single model class used in the application, it will be used to request the data. So, create a new folder called “Models” and, inside it, add the following record:

namespace ReturnPolicy.Models;

public record QuestionRequest(string Question);

Creating the Return Policy File

Now let’s create a text file that will serve as the knowledge base to be sent to the model to formulate the response. It will contain a common example of a return policy. Create a new folder called “Data” and, inside it, create a file called return_policy.txt and add to it the following text:

Return Policy - Updated July 2025

Our customers may return most new, unopened items within 30 days of delivery for a full refund.
Products that are defective or damaged can be returned or exchanged at any time.

To be eligible for a return:

- The product must be in the same condition as received.
- Proof of purchase is required.
- Returns after 30 days are subject to manager approval.

Please contact our support team before sending any returns.

Creating the Logic for Generating the Response

Now, let’s create the logic to generate, register and retrieve the embeddings, as well as formulate the response generated by the model.

Create a new folder called “Service” and, inside it, add the class below.

Note that we will first create the class and throughout the post we will add methods to it until it is complete. This is intended to explain each method separately for better understanding.

using Microsoft.Data.Sqlite;
using OpenAI;
using OpenAI.Chat;
using OpenAI.Embeddings;

namespace ReturnPolicy.Services
{
    public class PolicyService
    {
        private readonly ChatClient _chatClient;
        private readonly EmbeddingClient _embeddingClient;
        private readonly string _policyPath;
        private readonly string _dbPath;

        public PolicyService(IConfiguration config)
        {
            var apiKey = config["OpenAI:ApiKey"];

            if (string.IsNullOrWhiteSpace(apiKey))
                throw new InvalidOperationException("Missing OpenAI:ApiKey in configuration.");

            var client = new OpenAIClient(apiKey);

            _chatClient = client.GetChatClient("gpt-4o-mini");
            _embeddingClient = client.GetEmbeddingClient("text-embedding-3-small");

            _policyPath = Path.Combine(Directory.GetCurrentDirectory(), "Data", "return_policy.txt");
            _dbPath = Path.Combine(Directory.GetCurrentDirectory(), "Data", "embeddings.db");

            InitializeDatabase();
            LoadPolicyIntoDatabaseAsync().Wait();
        }
    }
}

Here we are using the PolicyService class to integrate the application with the OpenAI API and prepare the necessary data to work with RAG.

At the beginning, four private fields are declared: _chatClient and _embeddingClient are responsible for communicating with the OpenAI API. The first handles the chat model (in this case, gpt-4o-mini), while the second works with the embeddings model.

Meanwhile, _policyPath stores the path to the text file containing the return policy we created earlier, and _dbPath indicates the location where the SQLite database will be created.

The class constructor starts by reading the OpenAI API key from the application’s configuration file. If the key is not present, an exception is thrown indicating that it is required. Then, an OpenAIClient object is created, which serves as an access point to the different OpenAI services.

With this client, two components are initialized: the _chatClient, which will be used to generate intelligent responses, and the _embeddingClient, which will handle the creation of the text embeddings for the policy. After that, we define the paths of the data files, so that both the original text and the embeddings database are stored within the project’s Data folder.

Finally, two important actions are performed: InitializeDatabase() to prepare the SQLite database, creating the necessary tables if they do not already exist, and LoadPolicyIntoDatabaseAsync().Wait(), which reads the content of the return policy file, generates the embeddings and saves them to the database for later use.

Now, let’s create the methods to insert and retrieve the embeddings from the database. In the PolicyService class, add the methods below:

private void InitializeDatabase()
{
    using var conn = new SqliteConnection($"Data Source={_dbPath}");
    conn.Open();

    var cmd = conn.CreateCommand();
    cmd.CommandText = @"CREATE TABLE IF NOT EXISTS PolicyChunks (
                        Id INTEGER PRIMARY KEY AUTOINCREMENT,
                        Text TEXT NOT NULL,
                        Embedding BLOB NOT NULL
                        );";
    cmd.ExecuteNonQuery();
}

private async Task LoadPolicyIntoDatabaseAsync()
{
    var policyText = await File.ReadAllTextAsync(_policyPath);
    var chunks = SplitIntoChunks(policyText, 500);

    using var conn = new SqliteConnection($"Data Source={_dbPath}");
    conn.Open();

    foreach (var chunk in chunks)
    {
        var checkCmd = conn.CreateCommand();

        checkCmd.CommandText = "SELECT COUNT(*) FROM PolicyChunks WHERE Text = $text";

        checkCmd.Parameters.AddWithValue("$text", chunk);

        bool exists = Convert.ToInt32(checkCmd.ExecuteScalar()) > 0;

        if (exists) continue;

        try
        {
            var embeddingResult = await _embeddingClient.GenerateEmbeddingAsync(chunk);
            
            float[] vector = embeddingResult.Value.ToFloats().ToArray();

            var insertComand = conn.CreateCommand();

            insertComand.CommandText = "INSERT INTO PolicyChunks (Text, Embedding) VALUES ($text, $embedding)";

            insertComand.Parameters.AddWithValue("$text", chunk);
            insertComand.Parameters.AddWithValue("$embedding", FloatArrayToBytes(vector));

            insertComand.ExecuteNonQuery();
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }
}

Here, the InitializeDatabase() method creates the basic structure of the SQLite database, if it doesn’t already exist. First, it establishes a connection to the file defined in _dbPath, which is the same path configured in the class constructor. Then, it opens this connection and executes an SQL command responsible for creating the table PolicyChunks.

Note that the table consists of three columns: Id for the primary key, Text, which will store the text segment (or chunk) extracted from the policy file, and Embedding, a BLOB (Binary Large Object), that is, a binary field where the numerical vector that semantically represents that text segment will be stored. This means that the database is ready to receive and store the text data and their respective embeddings.

The LoadPolicyIntoDatabaseAsync() method is responsible for loading the policy content and saving its embeddings to the database.

First, it reads the entire content of the policy file, located at _policyPath, and then divides it into smaller parts using the SplitIntoChunks() method. This division is important because OpenAI’s language models have input size limits. Therefore, the text is broken into blocks of up to 500 characters or tokens.

Then, a new connection to the database is opened, and each text segment (chunk) is processed. For each segment, it checks if the content is already stored in the table. This is done through a query that counts how many records have the same text. If the segment already exists, it is ignored to avoid duplication.

When a new segment is found, the method requests the OpenAI embeddings model to generate a numerical vector representing the meaning of that text. The result is then converted to a float array, which is then transformed into bytes using the FloatArrayToBytes() method, to be compatible with the BLOB type of the database.

Finally, the vector and the text are inserted together into the PolicyChunks table.

If any error occurs during the process, such as a communication failure with the API, for example, the exception is displayed in the console, allowing processing to continue with the remaining segments.

Now let’s add the most important part of the service, where the intelligent search and generation of responses based on the company’s return policy takes place. So, add the following code to the PolicyService class:

public async Task<string> GetAnswerAsync(string question)
{
    var queryEmbedding = await _embeddingClient.GenerateEmbeddingAsync(question);
    var queryVector = queryEmbedding.Value.ToFloats().ToArray();

    var topChunks = GetTopChunks(queryVector, 3);

    var context = string.Join("\n\n", topChunks);

    List<ChatMessage> messages = new()
    {
        ChatMessage.CreateSystemMessage("You are a helpful assistant that answers based on company return policies."),
        ChatMessage.CreateUserMessage($"Use only the following policy text to answer the question:\n\n{context}\n\nQuestion: {question}")
    };

    var response = await _chatClient.CompleteChatAsync(messages);
    return response.Value.Content[0].Text.Trim();
}

private List<string> GetTopChunks(float[] queryEmbedding, int topN)
{
    using var conn = new SqliteConnection($"Data Source={_dbPath}");
    conn.Open();

    var selectCmd = conn.CreateCommand();

    selectCmd.CommandText = "SELECT Text, Embedding FROM PolicyChunks";
   
    using var reader = selectCmd.ExecuteReader();

    var scoredChunks = new List<(string Text, double Score)>();
    
    while (reader.Read())
    {
        var text = reader.GetString(0);
        var embeddingBytes = (byte[])reader["Embedding"];
        var embedding = BytesToFloatArray(embeddingBytes);

        var similarity = CosineSimilarity(embedding, queryEmbedding);
        scoredChunks.Add((text, similarity));
    }

    return scoredChunks
        .OrderByDescending(x => x.Score)
        .Take(topN)
        .Select(x => x.Text)
        .ToList();
}

private static IEnumerable<string> SplitIntoChunks(string text, int maxLength)
{
    for (int i = 0; i < text.Length; i += maxLength)
        yield return text.Substring(i, Math.Min(maxLength, text.Length - i));
}

private static double CosineSimilarity(float[] v1, float[] v2)
{
    double dot = 0.0, mag1 = 0.0, mag2 = 0.0;
    for (int i = 0; i < v1.Length; i++)
    {
        dot += v1[i] * v2[i];
        mag1 += v1[i] * v1[i];
        mag2 += v2[i] * v2[i];
    }
    return dot / (Math.Sqrt(mag1) * Math.Sqrt(mag2));
}

private static byte[] FloatArrayToBytes(float[] array)
{
    var bytes = new byte[array.Length * sizeof(float)];
    Buffer.BlockCopy(array, 0, bytes, 0, bytes.Length);
    return bytes;
}

private static float[] BytesToFloatArray(byte[] bytes)
{
    var floats = new float[bytes.Length / sizeof(float)];
    
    Buffer.BlockCopy(bytes, 0, floats, 0, bytes.Length);
    return floats;
}

Now, let’s analyze each method:

1. GetAnswerAsync(string question)

This method receives the user’s question and returns an AI-generated answer based on the policy content stored in the database.

First, it transforms the question into an embedding vector, using the same embedding model configured previously. This numerical vector (queryVector) represents the semantic meaning of the question.

Next, the method calls GetTopChunks(), which searches the database for the chunks most similar to the meaning of the question, i.e., the parts of the policy that contain information relevant to the answer. It requests the three most relevant chunks (topChunks), and then combines these texts into a single string called context.

With the context ready, the method assembles a list of messages to send to the chat model. The first message is an instruction, stating that the assistant should only answer based on the company policy. The second message contains both the policy text and the user’s original question.

Finally, the code calls the CompleteChatAsync() method of the OpenAI client, which returns a generated response based on the provided context. The final text is extracted, cleaned and then returned.

2. GetTopChunks(float[] queryEmbedding, int topN)

This method identifies which chunks in the database are most semantically similar to the question asked.

It opens a connection to the SQLite database and reads all records from the PolicyChunks table, which contains the texts and their embeddings.

For each record, it calculates the cosine similarity between the query vector (queryEmbedding) and the stored text vector. This calculation generates a number between 0 and 1; the closer to 1, the more similar the meaning between the two texts.

After calculating the scores, the method sorts the results in descending order and returns the topN most relevant chunks (in this case, three). These chunks will serve as the knowledge base for the model to answer correctly.

3. SplitIntoChunks(string text, int maxLength)

This method divides long texts into smaller parts, respecting a defined maximum size (for example, 500 characters).

It iterates through the original text and, in each iteration, returns a chunk that can be processed without exceeding the model’s token limit. It is essential to use techniques like this when working with large documents in RAG systems.

4. CosineSimilarity(float[] v1, float[] v2)

This method is the mathematical basis of the semantic search system. It calculates the angle between two vectors in the embedding space—the smaller the angle (or the larger the cosine), the closer the meanings of the texts represented by those vectors.

It is with this metric that the system determines which sections of the policy are most relevant to a specific question.

5. FloatArrayToBytes(float[] array) and BytesToFloatArray(byte[] bytes)

These two methods convert between arrays of numbers and bytes. Since SQLite does not have a native data type to store arrays of floats, the embeddings are converted into a binary format (BLOB) before being saved to the database. When they need to be used again, these bytes are converted back into an array of floats, preserving all the information of the original vector.

Adding the API Key

To access the OpenAI API, you need an API key. With the key in hand, add the following code to the application’s appsettings.json file:

"OpenAI": {
  "ApiKey": "YOUR_OPEN_AI_API_KEY"
},

Finally, in the Program class, add the following code:

using ReturnPolicy.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSingleton<PolicyService>();

var app = builder.Build();
app.UseStaticFiles();
app.MapControllers();

app.Run();

Running the Application and Testing the RAG

Now that everything is configured, we can run the application and test the endpoint that will generate the response. In this post, we’ll use Progress Telerik Fiddler Everywhere for this. Run the application and make the following request:

Route: POST - https://localhost:PORT/api/policy/ask

Body:

{
    "question": "Can I return an opened product?"
}

So the generated response will be something like this:

The complete response returned by the model was:

According to the return policy, most new, unopened items can be returned within 30 days for a full refund. If you have an opened product that is defective or damaged, it can be returned or exchanged at any time. If you need further assistance, please contact our support team.

Note that the answer provided by the model is aligned with the policy, which states that new and unused items can be returned within 30 days. Furthermore, it demonstrates clarity and objectivity by directly addressing the user’s question, conveying confidence and concern for the customer, which contributes to a good support experience.

Conclusion

The RAG technique allows for the generation of contextualized and intelligent responses, integrating the retrieval of relevant information with advanced synthesis capabilities. The responses produced by RAGs reduce ambiguities, improve the user experience and increase the reliability of interactions, especially in scenarios where document-based accuracy is essential.

In this post, we created a complete RAG system in ASP,NET Core, integrating it with OpenAI services for generating embeddings and producing contextualized responses. I hope this content serves as a practical reference, facilitating the adoption of the RAG technique whenever you have the opportunity to apply it in your projects.

If this all seems like a lot of work, there are professional RAG platforms you can explore, such as Progress Agentic RAG.

Progress Agentic RAG

Progress Agentic RAG is a RAG-as-a-Service platform that simplifies the creation of augmented reality (AR) retrieval and generation solutions. Instead of requiring proprietary infrastructure or multiple separate tools, it offers a ready-to-use environment for indexing documents, files and even videos, along with integrated metrics to evaluate RAG quality.

In practice, Progress Agentic RAG stands out for:

• Generative search for websites, which can interpret user intent and build responses using existing content on the page itself.
• Use in sensitive areas, such as the financial sector, supporting decision-making without compromising privacy and security.
• The ability to handle unstructured data, covering more than 60 formats: PDFs, videos, spreadsheets, texts, among others. This greatly helps teams like legal departments, who need quick and accurate answers.
• Intelligent video indexing, allowing the location of specific segments and generating responses based on audiovisual content.

For developers, Progress Agentic RAG functions as an intelligence layer that can be integrated with minimal effort. This reduces the need to build a RAG pipeline from scratch and accelerates the development of generative AI-based solutions.

Keep reading: Understand more about RAG and get a walk-through of Progress Agentic RAG.

It’s probably too obvious to mention, but: When your user is working with a Graphical User Interface (like, for example, a webpage) you’re mandated to get everything the user needs on the screen.

If you have a grid that has more rows than will fit on the screen, that mandate boils down to getting “the row the user wants” onto the screen, ideally without forcing the user to scroll-and-scan to find it.

In many of the Progress Kendo UI Grids, the scrollToItem method lets you get the row you or the user wants onto the screen, just by asking for the object the user wants. Using scrollToItem, you can pull a row that’s part of the grid’s page but not currently visible onto the screen, pull a row already on the screen to the top of the grid, or (in many cases) even pull rows not in the grid’s current page onto the screen. Your users, rather than having to scroll to find the item they want, can jump straight to it or you can put a row you know your user needs to see onto the screen.

The scrollToItem method is available in the KendoGrid for Angular, ASP.NET MVC and jQuery.

While the React Data Grid and the Blazor Grid don’t have scrollToItem, you can get some of the same behavior by accessing a row’s underlying HTML <tr> element and using the DOM’s scrollIntoView method … but the Kendo scrollToItem method is simpler to use and, even better, ties into your data model rather than the page’s HTML. The only real limitation on scrollToItem is that it doesn’t work with grouped paging.

Configuring the Project

To demonstrate using scrollToItem, I used the KendoGrid for ASP.NET MVC in an ASP.NET Core 8 Razor Page project. My first step was to add the Telerik.UI.for.AspNet.Core and Microsoft.AspNetCore.Mvc.NewtonSoft.Json NuGet packages to my project. After that, in the project’s Program.cs file, I added these statements before the builder.Build() statement:

builder.Services.AddKendo();
builder.Services.AddMvc().AddNewtonsoftJson(options =>
   options.SerializerSettings.ContractResolver =
    new DefaultContractResolver());

I generated a List of Product objects for my grid to display in an action method in an action method I called Get in a controller I called ProductsManager. To support retrieving data from my grid through that action method, I also added this statement after the Program.cs file’s builder.Build() statement:

app.MapControllers();

To complete configuring the project, I added these <link> and <script> tags to my project’s _Layout.cshtml file:

<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
<link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
<link rel="stylesheet" href="~/ScrollItem.styles.css" asp-append-version="true" />
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>
<link rel="stylesheet" href="https://kendo.cdn.telerik.com/themes/12.0.1/bootstrap/bootstrap-main.css" />
<script src="https://code.jquery.com/jquery-3.7.0.min.js"></script>
<script src="https://kendo.cdn.telerik.com/2025.3.1002/js/kendo.all.min.js"></script>
<script src="https://kendo.cdn.telerik.com/2025.3.1002/js/kendo.aspnetmvc.min.js"></script>

Configuring the Grid

For my case study, I set up a grid with a very short window:

<kendo-grid name="productGrid" height="250">

</kendo-grid>

Inside that kendo-grid element, I nested a datasource element that would retrieve 20 rows into that short space, so that I’ll have lots of rows in the grid’s page that weren’t “on the screen” to play with. Inside the datasource element, I put a schema element, with a model element inside it.

That model element is key to having the scrollToItem method work: Users can ask for a row in the grid to be displayed by using the property specified in the model element’s id attribute. The property you use here must be unique for each row on the page so, nine times out of ten, the property you pick is going to be the property on your object’s that holds the corresponding table’s primary key.

In my case, for the Product object I’m displaying in each row of my grid, I used the object’s ProductID property:

<datasource type="DataSourceTagHelperType.Ajax" page-size="20">
  <schema>
    <model id="ProductID">
    </model>
  </schema>

The scrollToItem method works as long as scrolling is enabled for the grid, in either of the grid’s virtual or endless scrolling modes.

That means that you don’t need to include a scrollable element in your grid’s definition (the defaults are fine), but, if you do include the element:

• If the enabled attribute is present, it must be set to true
• If either of the virtual or endless attributes are present, at lest one of them must be set to true

Inside the datasource element, you’ll also need a transport element to specify where your data is coming from. (I used the Url object’s Action method to call my Get action method in my ProductsManager controller.):

  </schema>
  <transport>
    <read url='@Url.Action("Get", "ProductsManager")'  />
  </transport>
</datasource>

Following the datasource element, you define the columns you want displayed in the grid (and you don’t need to include the column that you’ll use to pull the right row onto the screen):

<columns>
  <column field="ProductName" title="Name" />
  <column field="Category" title="Category" />
  <column field="Price" title="Price" />
</columns>

Using scrollToItem

With all of that in place, you can write some JavaScript code to pull a row onto the screen. For this case study, I added a textbox to allow the user to enter the ProductID of the item they wanted to pull onto the screen. In the textbox’s onblur event I called a function I named MoveToItem, passing a reference to the textbox to that function:

<br/>
<input onblur="MoveToItem(this)" />
<br />

To support calling the grid’s scrollToItem method, I need a reference to the grid. In any real application, I’ll probably need that reference multiple times so, rather than keep retrieving that reference, I declared a global variable to hold the reference and loaded that variable from a jQuery onready function:

<script>
    let grid;
    $(() => {
        grid = $("#productGrid").kendoGrid();
    });

Below that function, I added my MoveToItem function. In that function, I called the grid’s scrollToItem method, passing the method the value property of the textbox I passed to the function (after checking that the textbox has something in it value property, of course):

const MoveToItem = (txt) => 
{
    if (txt.value)
    {
        grid.scrollToItem(txt.value);
    }
};

When that command executes, the row with the matching ProductID becomes the top row in the grid (assuming there are enough rows to fill the rest of the grid—if there aren’t enough rows, the grid will display the last rows in the grid, including the row with the matching ProductID).

Fetching New Data

That is, as long as the user passes a valid ProductID or that ProductID is on the current page. What do you do when that isn’t true?

The best solution for ensuring only valid ProductIDs are passed to your function is, of course, to have the user select a ProductID from a dropdown list rather than entering whatever they want into a textbox. A dropdown list would also let the user select a product name from the dropdown list but allow you to pass a ProductID to your function.

A typical dropdown list would look like this:

<select onchange="MoveToItem(this)">
  <option value="top">Select a product</option>
  <option value="A1">Chai Tea</option>
 ...

And the JavaScript function to work with it would look like this:

const MoveToItem = (sel) => {
  alert(sel.value);
  grid.scrollToItem(sel.value);
}

But what if, for some reason, a dropdown list isn’t an option or the user’s entry is valid but the object isn’t in the grid’s current page? Provided you have virtual scrolling enabled, you can handle both of those scenarios by passing a callback function as the second parameter to the scrollToItem method.

The callback function is only called if scrollToItem can’t scroll to the item specified in its first parameter. So, for the “invalid choice” scenario, you can use that callback function to provide an error message. Basic code would look like this:

const MoveToItem = (txt) => 
{
  if (txt.value)
  {
    grid.scrollToItem(txt.value, 
    function () { 
        if (<…check for invalid value…>) 
        {
          alert("Invalid ProductID: " + txt.value);
        }
      }
    );
  }
}

However, that callback function is also passed an object that you can use to pull a row not in the current grid page onto the screen … provided you know the row’s position in your virtual list. All you need to do (after you determine the row’s position in your virtual list) is pass the row’s position to the object’s success method.

This sample code doesn’t attempt to find the right object that but just pulls the first row back onto the screen when the requested object isn’t found on the current page:

const MoveToItem = (e) => 
{
  if (e.value)
  {
    grid.scrollToItem(txt.value, 
      function (o) { 
        if (<…check for invalid value…>) 
      {
        alert("Invalid ProductID: " + txt.value);
      }
      else
      {
        o.success(1);
      }
    }
  }
}

In a GUI, your first goal is to provide your user whatever they need right in front of them. The scrollToItem method is the tool that enables you to do that while letting the user jump straight to the row they want.

Explore all the grids Progress provides with a free 30-day trial of the Progress Telerik DevCraft bundle:

Try Telerik DevCraft

The Retry Pattern helps developers create APIs that are prepared for adverse situations when communicating with external services, such as databases and even other APIs.

In this post, we’ll explore the main challenges faced when working with distributed applications that communicate with each other and discover how the Retry Pattern can be used as a resilience strategy to deal with common failures in these scenarios.

We’ll also see how to implement the Retry Pattern in an ASP.NET Core application using a retry pipeline through the Polly library.

Common Integration Issues

Any application that communicates with APIs or external services is susceptible to the risk of communication failures, including timeouts, temporary unavailability, network errors or request limits. While often underestimated, these issues are common and can compromise the user experience and system reliability.

In this context, we can highlight the following issues that modern systems face when handling integrations:

Temporary Network Errors

When accessing the network, 100% availability is not always guaranteed. Packets can be lost, connections can drop and providers can experience momentary instability. For example, a payment API takes longer than expected to respond, and its call times out (TimeoutException). In practice, the transaction may have been processed, but the application did not receive confirmation.

Temporary Unavailability of External Services

Services may undergo maintenance, experience overload or be offline for a few minutes. For example, an ecommerce website queries a pricing API to update a product’s price. If the API is unavailable, the system may fail and display the outdated price to the customer, causing harm and stress for both the consumer and the company selling the product.

Inconsistent or Invalid Data

There is always a risk that external APIs may return incomplete data, in an unexpected format or with business errors. For example, a registration API returns addresses without a ZIP code or with invalid characters, breaking the system’s internal validations.

These are just some of the many scenarios in which an API can fail to perform its intended task, resulting in significant problems and losses for the development team and the company. Fortunately, some solutions help mitigate these and other risks by automatically retrying a failed operation in the hope that it will succeed on a second attempt. Next, we’ll explore the Retry Pattern, which stands out as a solution for dealing with these temporary failures.

Understanding the Retry Pattern

The Retry Pattern is a resilience pattern whose central idea is to retry a failed operation, rather than simply giving up on the first attempt. This is useful and, in many cases, indispensable, as distributed systems tend to experience temporary problems, such as momentary network instability or even server overload. Therefore, when a communication or processing failure occurs between two services, it is advisable to at least try again.

These failures are usually corrected after a period of time. If the action that triggered the failure is retried after a reasonable delay, it is very likely to be successful. For example, imagine a payment service is momentarily overloaded and returns a “Service Unavailable (503)” error. In this case, it does not mean that the service is permanently down, but rather that it was unable to process the request at that time. If the application retries after a few seconds, it is very likely that the payment will be completed successfully.

Scenarios like this show that the Retry Pattern can be extremely useful, as it helps prevent temporary glitches from resulting in significant losses, maintaining a stable user experience and reducing the need for potential manual intervention.

The image below demonstrates two scenarios, with and without the use of the Retry Pattern.

Implementing Retry Pattern in ASP.NET Core

To implement the Retry Pattern, we’ll consider a scenario where a product catalog API needs to access another API to retrieve product image data. The premise is that we can’t leave the client without the product image. So, even if the first request fails, we have to try again.

So, first, we’ll create a simple product catalog API and implement a retry policy and a secondary API to return product images. Finally, we’ll force an error on the first two attempts and a success on the third, to validate that the policy is working.

You can access the complete source code in this GitHub repository: PollyProducts source code.

Polly for Resilience

Polly is a library focused on resilience and fault tolerance for .NET applications.

It is widely known and helps systems handle temporary failures when calling external APIs, databases, network services and more, allowing developers to implement resilience policies to anticipate temporary unavailability scenarios.

In addition to basic features like automatic operation retry, Polly offers advanced features like circuit breaker, which temporarily stops new calls after a consecutive number of failures, avoiding overloading unavailable services. Another important feature is fallback, which defines an alternative action when the main operation fails, for example, returning cached data if the API is down.

Creating the Product Catalog API

So, first, let’s create the API that will make requests to the secondary API to return data from the product catalog. This is where we’ll create a pipeline with a retry policy.

To create the base application, you can run the following commands in your terminal:

dotnet new web -o PollyProducts

Then, run the following commands to download and install the Polly NuGet Packages:

dotnet add package Polly

dotnet add package Microsoft.Extensions.Http.Polly

Next, let’s create the retry policy class. For that, create a new folder called “Policies” and, inside it, create the following class:

using Polly;
using Polly.Extensions.Http;
using Polly.Retry;
using System.Net;

namespace PollyProducts.Policies;

public static class ContextRetryPolicy
{
    public static ResiliencePipeline<HttpResponseMessage> CreatePipeline()
    {
        var builder = new ResiliencePipelineBuilder<HttpResponseMessage>();

        builder.AddRetry(new RetryStrategyOptions<HttpResponseMessage>
        {
            MaxRetryAttempts = 3,

            DelayGenerator = args =>
            {
                var delay = TimeSpan.FromSeconds(Math.Pow(4, args.AttemptNumber)); 
                return new ValueTask<TimeSpan?>(delay);
            },

            ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
                .Handle<HttpRequestException>()
                .HandleResult(response =>
                    (int)response.StatusCode >= 500 || 
                    response.StatusCode == HttpStatusCode.RequestTimeout
                ),

            OnRetry = args =>
            {
                var reason = args.Outcome.Exception?.Message
                             ?? args.Outcome.Result?.StatusCode.ToString()
                             ?? "Unknown reason";

                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"[Retry {args.AttemptNumber}] Retrying in {args.RetryDelay.TotalSeconds}s due to {reason}");
                Console.ResetColor();

                return default;
            }
        });

        return builder.Build();
    }
}

Let’s analyze the code above. In it, we use ResiliencePipelineBuilder<HttpResponseMessage> to implement the pipeline concept available in Polly 8. This allows the creation of configurable flows that can seamlessly combine multiple strategies such as retry, circuit breaker, fallback and timeout. In this case, the pipeline specializes in working with HTTP responses.

The AddRetry() configuration adds a retry policy. We define three attempts (MaxRetryAttempts = 3) and an exponential interval between them, where: first attempt: 4¹ = 4s, second attempt: 4² = 16s, and third attempt: 4³ = 64s. This avoids bombarding the service with requests in succession and gives it time to recover.

Furthermore, we use the ShouldHandle to define when the retry should occur, covering two scenarios: network exceptions (HttpRequestException) and server errors (5xx)/timeouts (408). This avoids unnecessary retries on client errors (4xx), which are usually not temporary.

Finally, every time the retry occurs, we print a colored message to the console, which we will use later to verify the retry behavior in action.

The next step is to configure the Program class and create the endpoint to request, so in the Program class, add the following code:

using PollyProducts.Policies;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient("LocalProductImageClient", client =>
{
    client.BaseAddress = new Uri("http://localhost:5005/");
});

var retryPipeline = ContextRetryPolicy.CreatePipeline();

var app = builder.Build();

app.MapGet("/products/{id}/", async (int id, IHttpClientFactory httpClientFactory) =>
{
    var client = httpClientFactory.CreateClient("LocalProductImageClient");
    int attempt = 0;

    HttpResponseMessage response = await retryPipeline.ExecuteAsync(async token =>
    {
        attempt++;

        Console.ForegroundColor = ConsoleColor.Cyan;
        Console.WriteLine($"[Attempt {attempt}] Requesting /photos/{id}");
        Console.ResetColor();

        var resp = await client.GetAsync($"/photos/{id}", token);

        Console.WriteLine($"[Attempt {attempt}] Response: {(int)resp.StatusCode} {resp.StatusCode}");

        return resp;
    });

    if (!response.IsSuccessStatusCode)
    {
        return Results.Problem("Image service is temporarily unavailable.");
    }

    var content = await response.Content.ReadAsStringAsync();

    return Results.Ok(new
    {
        ProductId = id,
        ImageInfo = content.Substring(0, Math.Min(content.Length, 120)) + "...",
        RetrievedAt = DateTime.UtcNow,
        Attempts = attempt
    });
});

app.Run();

In the ContextRetryPolicy class, we created a pipeline with a retry policy using Polly. Now, let’s see this policy in action.

In the code above, we use the API to consume another local HTTP service and retrieve product images, which we will create later.

First, we register the HttpClient (LocalProductImageClient) pointing to the base URL of the image service. Then, the application creates the pipeline using ContextRetryPolicy.CreatePipeline(). Within the pipeline, the retry policy is created, which will be used to encapsulate the call to the external service, so that if something fails, the system will retry before giving up.

Thus, whenever the /products/{id}/images endpoint is called, the application obtains an HttpClient from the factory and initiates the request to /photos/{id} on the external service.

With each retry attempt, the attempt number, the requested route and the response result are printed to the console. This will be useful for understanding real-time retry behavior, allowing us to see when Polly intervenes when testing the application.

If, after all attempts, the response is still unsuccessful, the API will return an error indicating that the image service is temporarily unavailable. Otherwise, it reads the response content, extracts a snippet for display, and returns a JSON object containing the product ID, a summary of the response, the time of the request and the number of attempts made.

Creating the Product Image API

The Product Image API will simulate the return of product image data. We’ll use it to test the retry policy in the Catalog API. So, to create the base application, run the command below:

dotnet new web -o BaseImages

Then, in the Program class, add the following code:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/photos/{id}", (int id) =>
{
    return Results.Ok(new
    {
        Id = id,
        Url = $"https://samplepics.photos/id/{id}/200/200",
        Title = $"Photo {id}"
    });
});

app.Run("http://localhost:5005");

In the code above, we define a minimal API that acts as a local image service.

First, we define a GET route (/photos/{id}) that receives an image identifier and returns a mock response in JSON format. Finally, the application runs on a fixed port (http://localhost:5005). Setting the port is important in this context because it keeps the base address used in the main API’s HttpClient stable.

So, everything we needed to implement the retry policy is ready. Now let’s run both APIs and test the possible scenarios.

Simulating Retries

To simulate retries, first run the Catalog API and make a request to the route: https://localhost:PORT/products/1 and observe the logs in the console. The first and second attempts will appear in the console:

The attempt error occurred because the images API is not enabled. Then run the second API (BaseImage), so now the Catalog API will be able to connect to the Images API, and the third attempt will be successful, as shown in the image below:

Note that the first attempts resulted in an error, but the third managed to connect to the image API and returned the requested data.

Conclusion and Next Steps

Scenarios where applications communicate with each other, receiving and sending data, are common in distributed systems. Therefore, it’s essential to design a system that verifies this communication actually occurs. This is where the Retry Pattern shines, for the construction of web APIs that are resistant to unexpected failures.

In this post, we covered the main problems that can occur in distributed applications and how to deal with them by implementing a retry policy with the open-source Polly library for ASP.NET Core.

And it doesn’t end there. Polly has many other powerful features you can explore, such as fallback, which lets you do something else when a request fails, or hedging, which allows you to send multiple requests at once and use the fastest response.

It’s that time of year: A new version of the .NET platform has shipped. .NET 10 landed last month as an LTS release, with support through November 2028.

To complement Jon Hilton’s .NET 10 Has Arrived—Here’s What Changed for Blazor article and Assis Zang’s What’s New in .NET 10 for ASP.NET Core, let’s look at .NET 10 improvements through the viewpoint of an API developer.

Throughout this post, we’ll walk through updates using a real-world example: an order management API with validation, OpenAPI docs and Entity Framework Core.

NOTE: The examples use Minimal APIs for brevity, but most of these improvements can be used for controller-based APIs as well.

Built in Validation for Minimal APIs

Before .NET 10, teams building Minimal APIs ended up rolling their own validation. The result? Endpoint code that was more about policing inputs than implementing business logic.

Here’s a simplified example that shows the problem.

public static class OrderEndpoints
{
    public static void MapOrderEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/api/orders");
        group.MapPost("/", CreateOrder);
        group.MapGet("/{id}", GetOrder);
    }

    private static async Task<IResult> CreateOrder(
        CreateOrderRequest request,
        OrderDbContext db)
    {
        if (string.IsNullOrWhiteSpace(request.CustomerEmail))
            return Results.BadRequest("Customer email is required");

        if (request.Items is null || request.Items.Count == 0)
            return Results.BadRequest("Order must contain at least one item");

        foreach (var item in request.Items)
        {
            if (item.Quantity < 1)
                return Results.BadRequest("Quantity must be at least 1");
            if (item.ProductId <= 0)
                return Results.BadRequest("Invalid product ID");
        }

        var order = new Order
        {
            CustomerEmail = request.CustomerEmail,
            Items = request.Items.Select(i => new OrderItem
            {
                ProductId = i.ProductId,
                Quantity = i.Quantity
            }).ToList(),
            CreatedAt = DateTime.UtcNow
        };

        db.Orders.Add(order);
        await db.SaveChangesAsync();

        return Results.Created($"/api/orders/{order.Id}", order);
    }

    private static async Task<IResult> GetOrder(int id, OrderDbContext db)
    {
        var order = await db.Orders.FindAsync(id);
        return order is null ? Results.NotFound() : Results.Ok(order);
    }
}