Two requests arrive at your application at the exact same moment. Both read the same data, both attempt to update it, and everything appears to work correctly. Yet one update silently overwrites the other. This is a classic race condition. In this post, you’ll see how these problems arise and how to prevent them using common concurrency control techniques.

Working with systems that execute multiple operations in milliseconds is not a distant reality. On the contrary, in medium- and large-scale applications, this is a common scenario.

But along with this level of concurrency comes a problem that is often overlooked: race conditions. When not handled properly, they can lead to inconsistencies and even silently corrupt data.

In this post, we will explore the concept of race conditions, understand how to identify them in practice, and discuss strategies to protect our applications against this type of issue.

What Is a Race Condition?

According to Microsoft documentation on race conditions and deadlocks, a race condition occurs when two threads access and modify a shared resource at the same time. The final result depends on the order in which these operations are executed.

The problem is that this order is not guaranteed; it can vary with each execution. This leads to unpredictable behavior, such as inconsistent data, lost updates or invalid states.

Imagine two requests trying to update an account balance at the same time. Both read the same initial value, perform separate calculations and save the result. Depending on which one saves last, one update may overwrite the other, even if both were performed correctly in isolation.

When Do Race Conditions Occur?

Race conditions don’t appear “out of nowhere.” They usually arise from some very common code and architectural patterns. Below, we’ll look at two of the best-known: Read-Modify-Write and Check-Then-Act.

Read-Modify-Write

The idea here is simple: you read a value, make some modification to it and then write it back. The problem starts when two or more executions do this at the same time. Consider the image below:

Note that both readings happen simultaneously, returning the value of 50. However, Thread A adds 20 to the initial value, while Thread B adds 10. The problem occurs when Thread A updates the initial value (50) to 70, while Thread B updates it 1 second later with the value of 60, completely disregarding the value previously added by Thread A.

The result is an incorrectly calculated value, something that would certainly cause losses in a production environment.

Check-Then-Act

The Check-Then-Act pattern is often even more subtle than the previous pattern. The problem with this pattern is not in updating a value, but in making a decision based on a state that may change before the action takes place. Consider the image below:

In this case we have two threads that check the stock quantity of a product. In both queries, the quantity is 1, and even though there is a check, both purchases were executed based on an invalid state. After all, when Thread A executed the purchase, there was no longer any quantity available for Thread B. If this problem had occurred in a real environment, the client of Thread B would have been left without the product.

Avoiding Race Conditions

Now that we’ve learned how to identify a race condition, let’s understand how to prevent it from happening. There are different strategies to protect ASP.NET Core applications against concurrency issues, and choosing the most appropriate approach depends on the scenario.

The main point is to understand that any concurrent operation involving shared state needs to be handled with care.

Understanding the Concept of Thread Safety

Thread safety is the ability of code or a resource to function correctly even when accessed simultaneously by multiple threads.

We can say that thread-safe code means that data is not corrupted, the state remains valid, and the behavior does not depend on the order of execution of the threads.

1. Using Locks

A lock is a mechanism used to make an operation thread-safe. It allows only one thread to execute a given piece of code at a time.

Consider the code below:

using System;
using System.Threading;
using System.Threading.Tasks;

public class ProductService
{
    private static readonly object _lock = new();

    // Simulating a stock quantity
    private int _stock = 1;

    public void Purchase(string customer)
    {
        Console.WriteLine($"{customer} is waiting to enter the critical section...");

        lock (_lock)
        {
            Console.WriteLine($"{customer} entered the critical section.");

            if (_stock <= 0)
            {
                Console.WriteLine($"{customer} could not complete the purchase. Product out of stock.");
                return;
            }

            Console.WriteLine($"{customer} is processing the purchase...");

            // Simulating a slow operation
            Thread.Sleep(3000);

            _stock--;

            Console.WriteLine($"{customer} completed the purchase.");
            Console.WriteLine($"Remaining stock: {_stock}");
        }

        Console.WriteLine($"{customer} left the critical section.");
    }
}

public class Program
{
    public static async Task Main()
    {
        var service = new ProductService();

        var task1 = Task.Run(() => service.Purchase("Customer A"));
        var task2 = Task.Run(() => service.Purchase("Customer B"));

        await Task.WhenAll(task1, task2);
    }
}

You can run this code in Fiddle and get the following result:

The idea here is to simulate a scenario where only one unit of stock is available for two customers attempting to make a purchase simultaneously. Note that we declare a static object _lock, which acts as a guardian for the critical section of the code, so only one thread at a time can execute the logic block that checks and decrements the stock.

When the request is triggered, two distinct tasks are initiated in parallel for customers A and B. If we didn’t use the locking structure, both could read the stock value as available at the same time, resulting in a duplicate sale of an item that only exists once, which constitutes a race condition.

However, the use of the lock instruction forces a waiting queue. While the first customer processes their purchase and the system waits (Thread.Sleep), the second customer remains held at the entrance of the critical section.

Only after the first customer’s transaction is completed and the stock is updated to zero is the lock released for the next customer. Upon entering the critical section, the second client performs a logical security check, realizes that the stock has been depleted by the previous processing and ends the purchase attempt without causing data inconsistencies.

The end result is a predictable execution flow, where we guarantee data integrity in a critical scenario under concurrent demand.

2. Using SemaphoreSlim

As we saw above, a lock blocks the current thread until the critical region is released. This may not always be a good strategy, as in some cases it can reduce the scalability of the application. In these cases, SemaphoreSlim may be a more suitable alternative.

In ASP.NET Core, SemaphoreSlim is a built-in class used to limit the number of threads that can access a resource or a section of code simultaneously. When set to 1, it works similarly to a lock, allowing only one execution at a time. Consider the example below:

using System;
using System.Threading;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        var service = new ProductService();

        var task1 = Task.Run(() => service.PurchaseAsync("Customer A"));
        var task2 = Task.Run(() => service.PurchaseAsync("Customer B"));

        await Task.WhenAll(task1, task2);

        Console.WriteLine("Finished.");
    }
}

public class ProductService
{
    private readonly SemaphoreSlim _semaphore = new(1, 1);
    private int _stock = 1;

    public async Task PurchaseAsync(string customer)
    {
        Console.WriteLine($"{customer} is waiting to enter the critical section...");

        await _semaphore.WaitAsync();

        try
        {
            Console.WriteLine($"{customer} entered the critical section.");

            if (_stock <= 0)
            {
                Console.WriteLine($"{customer} could not complete the purchase. Product out of stock.");
                return;
            }

            Console.WriteLine($"{customer} is processing the purchase...");

            // Simulates an asynchronous operation
            await Task.Delay(3000);

            _stock--;

            Console.WriteLine($"{customer} completed the purchase.");
            Console.WriteLine($"Remaining stock: {_stock}");
        }
        finally
        {
            _semaphore.Release();

            Console.WriteLine($"{customer} left the critical section.");
        }
    }
}

You can run this code in Fiddle and get the following result:

In this code, we create an instance of SemaphoreSlim, passing an initial and maximum value of 1 as a parameter. Thus, when two threads attempt to execute PurchaseAsync simultaneously, the first thread enters SemaphoreSlim while the second waits.
After the first operation is completed, the semaphore is released and the second thread can finally continue.

As in the example with lock, this prevents two operations from altering the stock at the same time. Tthe difference here is that the threads are asynchronous, and we also have the possibility of configuring an initial and maximum value for the number of simultaneous threads.

3. Using Thread-Safe Collections

Another scenario prone to race condition problems is using collections shared between multiple threads. Structures such as List<T>, Dictionary<TKey, TValue> and HashSet<T> were not designed for concurrent access. This means that collections of these types allow multiple threads to read and modify their data, generating inconsistent data and unpredictable behavior.

Consider the example below:

   private readonly Dictionary<Guid, Product> _products = new();

    public void AddProduct(Product product)
    {
        _products.Add(product.Id, product);
    }

If multiple requests attempt to add or update items at the same time, the application may throw exceptions or even corrupt the internal state of the collection. The problem occurs because Dictionary<TKey, TValue> is not prepared for synchronization.

For concurrent scenarios, .NET provides thread-safe collections through the namespace System.Collections.Concurrent, one of the most commonly used being ConcurrentDictionary<TKey, TValue>. Thus, we can use ConcurrentDictionary with safe concurrent access between multiple threads:

   private readonly ConcurrentDictionary<Guid, Product> _concurrentProducts = new();

    public void AddConcurrentProduct(Product product)
    {
        _concurrentProducts.TryAdd(product.Id, product);
    }

    public Product? GetProduct(Guid id)
    {
        _concurrentProducts.TryGetValue(id, out var product);

        return product;
    }

Now multiple threads can read _concurrentProducts at the same time, and concurrent operations are handled internally.

4. Using Optimistic Concurrency

Optimistic concurrency is another option for avoiding race conditions, especially in modern applications.

Unlike previously seen approaches such as locking or SemaphoreSlim, it does not attempt to prevent simultaneous accesses. Instead, it assumes that conflicts are rare and only detected when they occur.

Imagine that multiple operations can read the same data simultaneously. The first update happens normally, but subsequent updates fail if the data has been changed in the middle of the process. This prevents silent overwrites and provides consistency.

Consider the image below:

Note that both threads read the value at the same time (stock = 10, version 1), but Thread A was faster and updated the value first (stock = 9, version 2). When Thread B tries to update the value, an exception is generated because version 2 already exists. This verifies the consistency of the object’s initial state; in this case, the stock quantity does not receive an invalid state.

Implementing Optimistic Concurrency with EF Core

Entity Framework Core has a mechanism for using Optimistic Concurrency. To implement it, in an entity class we define a Version column as follows:

using System.ComponentModel.DataAnnotations;

namespace PracticingRaceConditions.Models;

public class Product
{
    public Guid Id { get; internal set; }
    public string Name { get; set; } = string.Empty;

    public int Stock { get; set; }

    [Timestamp]
    public byte[] Version { get; set; } = default!;
}

This Version column informs EF Core that it will be used by the Optimistic Concurrency mechanism, and when two threads attempt to update the same record with the same version, an exception will be thrown.

To simulate the error, we can do the following:

public async Task SimulatingPurchaseAsync()
{
    var options = new DbContextOptionsBuilder<ProductDbContext>()
        .UseSqlite("Data Source=productsDb")
        .Options;

    // Request A
    using var contextA = new ProductDbContext(options);

    // Request B
    using var contextB = new ProductDbContext(options);

    var productA = await contextB.Products.FirstOrDefaultAsync();

    var productB = await contextB.Products.FirstOrDefaultAsync();

    productA.Stock--;
    productB.Stock--;

    // Request A saves first
    await contextA.SaveChangesAsync();

    try
    {
        // Request B attempts to save using an outdated version
        await contextB.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        Console.WriteLine("Concurrency conflict detected!");
    }
}

If we execute the SimulatingPurchaseAsync() method, we will get the following output in the console:

Note that when executing the SimulatingPurchaseAsync() method, we simulate two stock changes at the same time. When saving the result of Thread A, execution occurs normally because a version 2 of the product did not yet exist. But when trying to save the result of Thread B, a DbUpdateConcurrencyException exception is thrown, because EF Core detected that a version 2 was again trying to update the record.

In this way, we can use the EF Core’s Optimistic Concurrency mechanism to prevent the race condition problem.

Conclusion

The race condition problem occurs when two threads access and modify the same resource at the same time, which can result in an invalid state depending on the order in which the operations are performed.

In this post, we’ve seen common examples where race conditions can occur, and learned how protect our code from these problems through approaches like Locks, SemaphoreSlim, Thread-Safe Collections and Optimistic Concurrency with EF Core. I hope this post has helped you understand what race conditions are and how to protect your applications from errors resulting from this type of problem.

In this post, you’ll learn how to structure an ASP.NET Core project following CRUD best practices, even when the premise is simple. The idea here is to build something you can actually use as a portfolio.

In addition, we’ll focus on decisions that experienced developers make daily: how to avoid unnecessary coupling, how to better model the domain, and how to prepare your application to grow without becoming chaotic.

By the end of the post, you’ll have a solid foundation on how to create a CRUD application ready to evolve into something bigger, maybe with authentication, messaging, caching, or even an event-driven architecture.

The Problem with Generic CRUDs

You’ve probably faced a requirement like this at some point: Create a simple, straightforward CRUD that only performs the basic operations of Create, Read, Update and Delete, with entities representing tables, and everything working in a few minutes. And that’s not wrong. The problem starts when this same model, designed for prototyping, is taken to production without being prepared for future evolution.

One of the clearest signs of a basic CRUD is the use of anemic entities, classes that only have properties, without any behavior:

public class User
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

Here, the entity does not protect its own state. Therefore, it can be created with an empty name, it can have an invalid email, it can be changed from anywhere. In other words, there is no business rule, just a simple data structure.

Another classic symptom of a prematurely scaled CRUD is having rules and validations scattered throughout the code. In basic CRUDs, when rules appear, they are scattered a bit in the Controller class, a bit in the Service class, and in the worst cases they don’t even exist.

Consider the example below:

   if (string.IsNullOrWhiteSpace(user.Name))
        return Results.BadRequest();

This solves the immediate problem, but creates a bigger one: the rule doesn’t belong to the domain, it’s loose in the system. Therefore, as the system grows, validations can be duplicated, lose consistency and become harder to find everywhere because they are scattered.

The biggest problem here is that you’ve only modeled the data, not the system. Basic CRUDs focus on basic operations: creating, reading, updating and deleting data. But real systems are about behavior: A user can register, they can deactivate their account, they can change their email based on internal validations, they can have a preferred name, they can change their address …

When you only model data, the system loses meaning and becomes just a data handling tool, which can easily be replaced by anything else, like a simple Excel spreadsheet for example.

The opposite of this are applications that, despite using only basic operations, are prepared for new features that will likely be needed. The image below illustrates the main points of both approaches:

Creating a CRUD Ready for Production

Now that we’ve reviewed some examples to avoid, let’s see how to create a complete CRUD application, organizing each part of the code according to best practices and preparing the project for evolution. You can access the complete project code in this GitHub repository: Campus Hub source code.

Architecture and Basic Structure

The application will be a CRUD to manage university courses, which can be registered, updated and deactivated. We will use the principles of Clean Architecture combined with tactical Domain-Driven Design (DDD) to create the basic structure of the project. Thus, the application will have the following project organization:

src/

• Presentation -> CampusHub.Api
• Application -> CampusHub.Application
• Domain -> CampusHub.Domain
• Infrastructure -> CampusHub.Infrastructure

Let’s run the .NET commands to create the projects. In a terminal, execute the command below:

dotnet new sln -n CampusHub

This will create a new solution (CampusHub.sln). Then, to create the projects within the src directory, run the following command:

dotnet new webapi -n CampusHub.Api -o src/CampusHub.Api
dotnet new classlib -n CampusHub.Application -o src/CampusHub.Application
dotnet new classlib -n CampusHub.Domain -o src/CampusHub.Domain
dotnet new classlib -n CampusHub.Infrastructure -o src/CampusHub.Infrastructure

Now, to add the projects to the solution, run the following command:

dotnet sln add src/CampusHub.Api/CampusHub.Api.csproj
dotnet sln add src/CampusHub.Application/CampusHub.Application.csproj
dotnet sln add src/CampusHub.Domain/CampusHub.Domain.csproj
dotnet sln add src/CampusHub.Infrastructure/CampusHub.Infrastructure.csproj

Finally, run the following commands to add the dependencies between the projects:

dotnet add src/CampusHub.Application reference src/CampusHub.Domain
dotnet add src/CampusHub.Infrastructure reference src/CampusHub.Domain
dotnet add src/CampusHub.Infrastructure reference src/CampusHub.Application
dotnet add src/CampusHub.Api reference src/CampusHub.Application
dotnet add src/CampusHub.Api reference src/CampusHub.Infrastructure

Then, in the CampusHub.Infrastructure.cs add the following NuGet packages:

  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="8.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="8.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.0" />
  </ItemGroup>

Domain Layer

In the domain layer, we will place the project’s entities and enums. Therefore, we will have a class to represent the Course entity and an enum to represent the course statuses. So, within the CampusHub.Domain project, create a folder called Entities and add the following class inside it:

using CampusHub.Domain.Enums;

namespace CampusHub.Domain.Entities;

public class Course
{
    private const int MinNameLength = 3;
    private const int MaxNameLength = 200;
    private const int MinWorkload = 1;

    public Guid Id { get; private set; }
    public string Code { get; private set; } = string.Empty;
    public string Name { get; private set; } = string.Empty;
    public int WorkloadHours { get; private set; }
    public int MaxStudents { get; private set; }
    public CourseStatus Status { get; private set; }

    // EF Core requirement
    private Course() { }

    private Course(string code, string name, int workloadHours, int maxStudents)
    {
        Id = Guid.NewGuid();
        SetCode(code);
        SetName(name);
        SetWorkload(workloadHours);
        SetMaxStudents(maxStudents);

        Status = CourseStatus.Draft;
    }

    public static Course Create(string code, string name, int workloadHours, int maxStudents)
    {
        return new Course(code, name, workloadHours, maxStudents);
    }

    // Behavior methods
    public void UpdateDetails(string name, int workloadHours, int maxStudents)
    {
        EnsureNotArchived();

        SetName(name);
        SetWorkload(workloadHours);
        SetMaxStudents(maxStudents);
    }

    public void ChangeCapacity(int maxStudents)
    {
        EnsureNotArchived();

        SetMaxStudents(maxStudents);
    }

    public void Activate()
    {
        if (Status == CourseStatus.Active)
            throw new InvalidOperationException("Course is already active.");

        Status = CourseStatus.Active;
    }

    public void Archive()
    {
        if (Status == CourseStatus.Archived)
            throw new InvalidOperationException("Course is already archived.");

        Status = CourseStatus.Archived;
    }


    // Private validation logic
    private void SetCode(string code)
    {
        if (string.IsNullOrWhiteSpace(code))
            throw new ArgumentException("Course code cannot be empty.");

        Code = code.Trim().ToUpper();
    }

    private void SetName(string name)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("Course name cannot be empty.");

        if (name.Length < MinNameLength || name.Length > MaxNameLength)
            throw new ArgumentException($"Course name must be between {MinNameLength} and {MaxNameLength} characters.");

        Name = name.Trim();
    }

    private void SetWorkload(int workloadHours)
    {
        if (workloadHours < MinWorkload)
            throw new ArgumentException("Workload must be greater than zero.");

        WorkloadHours = workloadHours;
    }

    private void SetMaxStudents(int maxStudents)
    {
        if (maxStudents <= 0)
            throw new ArgumentException("Max students must be greater than zero.");

        MaxStudents = maxStudents;
    }

    private void EnsureNotArchived()
    {
        if (Status == CourseStatus.Archived)
            throw new InvalidOperationException("Archived courses cannot be modified.");
    }
}

Note that this entity has an excellent structure. It is not anemic, meaning it has behaviors such as the Activate(), Archive() and UpdateDetails() methods.

Furthermore, you can never create an invalid Course because the verification methods protect against creating an invalid state. For example, an archived course cannot be modified, and an active course cannot be reactivated.

Now, create a new folder called Enums and add the following enum to it:

namespace CampusHub.Domain.Enums;

public enum CourseStatus
{
    Draft = 0,
    Active = 1,
    Archived = 2
}

Application Layer

The application layer is where we will configure the service classes with CRUD methods and Data Transfer Objects (DTOs). So, within the CampusHub.Application project, create a new folder called DTOs and create the following records inside it:

namespace CampusHub.Application.DTOs;

public record CourseResponseDto(
    Guid Id,
    string Code,
    string Name,
    int WorkloadHours,
    int MaxStudents,
    string Status
);

namespace CampusHub.Application.DTOs;

public record CreateCourseDto(
    string Code,
    string Name,
    int WorkloadHours,
    int MaxStudents
);

namespace CampusHub.Application.DTOs;

public record UpdateCourseDto(
    string Name,
    int WorkloadHours,
    int MaxStudents
);

Then, create a new folder called Interfaces and add the following interfaces to it:

using CampusHub.Domain.Entities;

namespace CampusHub.Application.Interfaces;

public interface ICourseRepository
{
    Task AddAsync(Course course);
    Task<Course?> GetByIdAsync(Guid id);
    Task<List<Course>> GetAllAsync();
    Task Update(Course course);
    Task<bool> ExistsByCodeAsync(string code);
}

using CampusHub.Application.DTOs;

namespace CampusHub.Application.Interfaces;

public interface ICourseService
{
    Task<Guid> CreateAsync(CreateCourseDto dto);
    Task UpdateAsync(Guid id, UpdateCourseDto dto);
    Task ActivateAsync(Guid id);
    Task ArchiveAsync(Guid id);
    Task<CourseResponseDto?> GetByIdAsync(Guid id);
    Task<List<CourseResponseDto>> GetAllAsync();
}

Finally, create a new folder called Services and add the class below to it:

using CampusHub.Application.Interfaces;
using CampusHub.Domain.Entities;
using CampusHub.Application.DTOs;

namespace CampusHub.Application.Services;

public class CourseService : ICourseService
{
    private readonly ICourseRepository _repository;

    public CourseService(ICourseRepository repository)
    {
        _repository = repository;
    }

    public async Task<Guid> CreateAsync(CreateCourseDto dto)
    {
        var exists = await _repository.ExistsByCodeAsync(dto.Code);
        if (exists)
            throw new InvalidOperationException("Course code already exists.");

        var course = Course.Create(
            dto.Code,
            dto.Name,
            dto.WorkloadHours,
            dto.MaxStudents
        );

        await _repository.AddAsync(course);

        return course.Id;
    }

    public async Task UpdateAsync(Guid id, UpdateCourseDto dto)
    {
        var course = await _repository.GetByIdAsync(id)
            ?? throw new InvalidOperationException("Course not found.");

        course.UpdateDetails(dto.Name, dto.WorkloadHours, dto.MaxStudents);

        await _repository.Update(course);
    }

    public async Task ActivateAsync(Guid id)
    {
        var course = await _repository.GetByIdAsync(id)
            ?? throw new InvalidOperationException("Course not found.");

        course.Activate();

        await _repository.Update(course);
    }

    public async Task ArchiveAsync(Guid id)
    {
        var course = await _repository.GetByIdAsync(id)
            ?? throw new InvalidOperationException("Course not found.");

        course.Archive();

        await _repository.Update(course);
    }

    public async Task<CourseResponseDto?> GetByIdAsync(Guid id)
    {
        var course = await _repository.GetByIdAsync(id);

        if (course is null)
            return null;

        return MapToResponse(course);
    }

    public async Task<List<CourseResponseDto>> GetAllAsync()
    {
        var courses = await _repository.GetAllAsync();

        return courses.Select(MapToResponse).ToList();
    }

    private static CourseResponseDto MapToResponse(Course course)
    {
        return new CourseResponseDto(
            course.Id,
            course.Code,
            course.Name,
            course.WorkloadHours,
            course.MaxStudents,
            course.Status.ToString()
        );
    }
}

Here we have all the methods we need to execute the CRUD functions. Note that to modify the state of the objects we use the methods created in the domain class.

Infrastructure Layer

Now let’s create the infrastructure layer, used for communication with external parts of the application such as external APIs and databases. Within the CampusHub.Infrastructure project, create a new folder called Data and add the following classes to it:

using CampusHub.Domain.Entities;
using Microsoft.EntityFrameworkCore;

namespace CampusHub.src.CampusHub.Infrastructure.Data;

public class AppDbContext : DbContext
{
    public DbSet<Course> Courses => Set<Course>();

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

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);

        base.OnModelCreating(modelBuilder);
    }
}

using CampusHub.Domain.Entities;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

namespace CampusHub.src.CampusHub.Infrastructure.Data;

public class CourseConfiguration : IEntityTypeConfiguration<Course>
{
    public void Configure(EntityTypeBuilder<Course> builder)
    {
        builder.ToTable("Courses");

        builder.HasKey(c => c.Id);

        builder.Property(c => c.Code)
            .IsRequired()
            .HasMaxLength(20);

        builder.HasIndex(c => c.Code)
            .IsUnique();

        builder.Property(c => c.Name)
            .IsRequired()
            .HasMaxLength(200);

        builder.Property(c => c.WorkloadHours)
            .IsRequired();

        builder.Property(c => c.MaxStudents)
            .IsRequired();

        builder.Property(c => c.Status)
            .IsRequired()
            .HasConversion<int>(); // Enum -> int

        builder.Property(c => c.Id)
            .ValueGeneratedNever();
    }
}

Here we made the necessary configurations for the EF Core implementation, defining database details such as the table name, maximum number of characters for the Name property and others.

Next, create a new folder called Repositories and add the following class to it:

using CampusHub.Application.Interfaces;
using CampusHub.Domain.Entities;
using CampusHub.src.CampusHub.Infrastructure.Data;
using Microsoft.EntityFrameworkCore;

namespace CampusHub.Infrastructure.Repositories;

public class CourseRepository : ICourseRepository
{
    private readonly AppDbContext _context;

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

    public async Task AddAsync(Course course)
    {
        await _context.Courses.AddAsync(course);
        await _context.SaveChangesAsync();
    }

    public async Task<Course?> GetByIdAsync(Guid id)
    {
        return await _context.Courses.FirstOrDefaultAsync(c => c.Id == id);
    }

    public async Task<List<Course>> GetAllAsync()
    {
        return await _context.Courses.ToListAsync();
    }

    public async Task<bool> ExistsByCodeAsync(string code)
    {
        var normalizedCode = code.Trim().ToUpper();

        return await _context.Courses
            .AnyAsync(c => c.Code == normalizedCode);
    }

    public async Task Update(Course course)
    {
        _context.Courses.Update(course);
        await _context.SaveChangesAsync();
    }
}

In the repository class, we create the implementation of the CRUD methods that execute the operations on the database.

The last class in the infrastructure layer will be used to configure the dependency injection and define the connection string. So, inside the project add the class below:

using CampusHub.Application.Interfaces;
using CampusHub.Infrastructure.Repositories;
using CampusHub.src.CampusHub.Infrastructure.Data;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace CampusHub.Infrastructure;

public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
    {
        services.AddDbContext<AppDbContext>(options =>
        options.UseMySql(
            configuration.GetConnectionString("DefaultConnection"),
            ServerVersion.AutoDetect(configuration.GetConnectionString("DefaultConnection"))
        ));

        services.AddScoped<ICourseRepository, CourseRepository>();

        return services;
    }
}

API Layer

The API is the final layer of the application, here we will define the controller classes and other settings such as the database connection string. Inside the Controllers folder, add the following controller:

using CampusHub.Application.DTOs;
using CampusHub.Application.Interfaces;
using Microsoft.AspNetCore.Mvc;

namespace CampusHub.Api.Controllers;

[ApiController]
[Route("api/[controller]")]
public class CoursesController : ControllerBase
{
    private readonly ICourseService _service;

    public CoursesController(ICourseService service)
    {
        _service = service;
    }

    [HttpPost]
    public async Task<IActionResult> Create(CreateCourseDto dto)
    {
        var id = await _service.CreateAsync(dto);

        return CreatedAtAction(nameof(GetById), new { id }, null);
    }

    [HttpGet("{id:guid}")]
    public async Task<IActionResult> GetById(Guid id)
    {
        var course = await _service.GetByIdAsync(id);

        if (course is null)
            return NotFound();

        return Ok(course);
    }

    [HttpGet]
    public async Task<IActionResult> GetAll()
    {
        var courses = await _service.GetAllAsync();

        return Ok(courses);
    }

    [HttpPut("{id:guid}")]
    public async Task<IActionResult> Update(Guid id, UpdateCourseDto dto)
    {
        await _service.UpdateAsync(id, dto);

        return NoContent();
    }

    [HttpPost("{id:guid}/activate")]
    public async Task<IActionResult> Activate(Guid id)
    {
        await _service.ActivateAsync(id);

        return NoContent();
    }

    [HttpPost("{id:guid}/archive")]
    public async Task<IActionResult> Archive(Guid id)
    {
        await _service.ArchiveAsync(id);

        return NoContent();
    }
}

Then, in the Program class, replace the existing code with the code below:

using CampusHub.Application.Services;
using CampusHub.Application.Interfaces;
using CampusHub.Infrastructure;

var builder = WebApplication.CreateBuilder(args);

// Services

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();

// Application

builder.Services.AddScoped<ICourseService, CourseService>();

// Infrastructure

builder.Services.AddInfrastructure(builder.Configuration);

// Build

var app = builder.Build();

// Middleware

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Finally, in the file appsettings.json, add the following configuration. (Don’t forget to add your credentials!):

 "ConnectionStrings": {
    "DefaultConnection": "server=localhost;port=3306;database=campushub;user=YOUR_USER;password=YOUR_PASSWORD;"
  }
,

Running EF Core Commands

To apply the migration commands, in the project root, open a new terminal and run the commands below.

Creating the Migration Files

dotnet ef migrations add InitialCreate --project src/CampusHub.Infrastructure --startup-project src/CampusHub.Api --output-dir Data/Migrations

Applying the Migration Commands

dotnet ef database update --project src/CampusHub.Infrastructure --startup-project src/CampusHub.Api

What Does the Final Structure Look Like?

After implementing all the steps above, the project will have the following structure:

When Does a Complete CRUD Not Pay Off?

In this post, we created a complete CRUD, with all the necessary elements for its evolution. However, this complexity can exponentially increase development time and the level of knowledge required to maintain the project.

With this in mind, in some scenarios, simplicity is preferable. For example, when the system basically stores and retrieves data without relevant business rules. In scenarios such as basic registrations, auxiliary tables or internal administrative panels, adding layers such as services, rich entities and DDD patterns tends to generate more complexity than value, making the code more difficult to maintain without a justified need.

It is also not worthwhile to invest in a sophisticated architecture in the initial phases of a product, such as MVPs or systems still in validation. In these cases, the priority is speed and adaptation to frequent changes, and a simple structure allows for faster evolution without the burden of unnecessary abstractions.

On the other hand, a more elaborate CRUD makes sense when the domain has important rules, states, complex validations or when errors can have a significant impact. In these scenarios, a more structured architecture, as demonstrated in the post, helps protect the domain, maintain consistency and facilitate the system’s evolution over time (all parts are in their proper places).

The final decision of whether or not to use a complete and evolve-ready CRUD should therefore always take into account the level of complexity of the problem.

Conclusion and Next Steps

Knowing the best approach when creating new web applications is always a challenge, but we must keep in mind that if the project requires complex business rules, validations and errors that can have a significant impact, this is a strong indication that the application should not be a simple and generic CRUD.

In this post, we learned how to create a complete CRUD, with each layer representing a part of Clean Architecture, and using DDD development principles to implement a well-structured domain with private properties and behaviors.

But far beyond the basic structure presented in this post, a complete CRUD also involves unit tests, complex validations (FluentValidation), authentication and authorization with modern methods (JW Tokens for example), and many other elements. I hope this post serves as a starting point and helps you create CRUD applications that are not only ready to function, but also to evolve with quality over time.

Exceptions have been part of the .NET ecosystem since the earliest versions of the .NET Framework. Today, with the platform’s continuous evolution, their use is simpler and more integrated than ever. The problem, however, arises when they are used inappropriately or imprecisely.

In this post, we will explore in which situations the use of exceptions is truly recommended and when more appropriate alternatives should be considered. Furthermore, we will see in practice some of the most modern features available in ASP.NET Core for implementing exception handling aligned with best practices.

What Are Exceptions in the Context of ASP.NET Core?

In ASP.NET Core, exceptions are objects that represent unexpected events that occur during program execution and interrupt its normal flow. Common examples of flow interruption include null reference errors, invalid user input, and database connection problems.

In practice, when an exception is thrown, the .NET runtime starts looking for somewhere that knows how to handle it, typically a try/catch statement, as shown in the example below:

try
{
    var result = 10 / 0;
}
catch (Exception ex)
{
    throw new Exception("Error: " + ex.Message);
}

If this exception is not handled, it returns to the beginning of the execution and eventually reaches the ASP.NET Core pipeline, resulting in an HTTP error, usually a 500 - Internal Server Error.

When Should Exceptions Be Avoided?

One of the most common mistakes in backend applications is using exceptions for expected situations. If code already expects something to happen, then it’s not exceptional, it’s predictable.

The principle of exceptions is to reserve exceptions for unpredictable situations.

A common example of a situation where exceptions should be avoided is for input data validation. Data validation should never use exceptions as a rule. Note the example below:

if (string.IsNullOrEmpty(user.BankAccountNumber))
{
    throw new Exception("BankAccountNumber is required");
}

The problem here is that the system expects the client to send a user with invalid data. In other words, this is part of the normal flow, not an exception. In this case, the correct approach would be to treat this as data validation and simply return a 400 Bad Request:

if (string.IsNullOrEmpty(user.BankAccountNumber))
{
    return Results.BadRequest("BankAccountNumber is required");
}

When Does Using Exceptions Make Sense?

If exceptions shouldn’t be used in the normal flow, then when do they make sense? In backend applications like ASP.NET Core, exceptions should be used when something truly unexpected happens and the application cannot continue safely or should not continue at all.

Below, we’ll look at practical scenarios where exceptions actually make sense.

Infrastructure Failures

This is a very common scenario. If the database fails here, it’s not possible to proceed normally, meaning it’s an exception:

try
{
    var user = await dbContext.Users.FindAsync(id);
    return Results.Ok(user);
}
catch (Exception ex)
{
    return Results.InternalServerError($"Error retrieving user. Error details: {ex.Message}");
}

⚠️ Impossible or Inconsistent States

Despite frontend and backend validations, inconsistent states can reach the application core. If this happens, something is certainly wrong, and this corrupted state cannot be saved to the database or continue its path. In this case, an exception must be generated:

if (BankAccountNumber.Length < 8)
{
    throw new InvalidOperationException("The bank account number must have at least 8 digits at this point");
}

If the system logic guarantees that BankAccountNumber will always have at least 8 characters at this point, then this indicates a bug, data inconsistency or even a flow error, and the exception is the last resort to prevent an inconsistent state at this stage of the process.

Dependency on External Services

If the external service is mandatory for the flow and the absence of data completely prevents correct processing, then you are dealing with a real error and the exception represents a technical problem.

In this case, it is correct to throw an exception because the process cannot continue with inconsistent data. Furthermore, it is important to clarify that the error occurred in the integration between the services, as demonstrated in the example below:

   var customer = await externalService.GetCustomerAsync(customerId);

    if (customer == null)
    {
        throw new InvalidOperationException("Unable to retrieve customer data from the external service: CustomerService");
    }

Result Pattern as an Alternative

If exceptions shouldn’t be used for normal flow, the question arises: what would be a good alternative to represent expected errors?

One of the most widely used alternatives today is the Result Pattern. The Result Pattern is a design pattern used to manage execution flow and errors, returning a structured object instead of throwing exceptions for expected failures.

Instead of throwing exceptions, the method returns an object indicating whether it succeeded or failed and why.

Implementing the Result Pattern

To use the Result Pattern, we will create a simple application and then create the classes and methods. The complete source code with examples is available in this GitHub repository: PracticingExceptionHandling source code.

To create the base, you can use the command below in your terminal:

dotnet new web -o PracticingExceptionHandling

Open the application and create the following class within it:

namespace PracticingExceptionHandling;

public class Result
{
    public bool IsSuccess { get; }
    public string Error { get; }

    protected Result(bool isSuccess, string error)
    {
        IsSuccess = isSuccess;
        Error = error;
    }

    public static Result Ok() => new Result(true, null);
    public static Result Fail(string error) => new Result(false, error);
}

public class Result<T> : Result
{
    public T Value { get; }

    private Result(T value) : base(true, null)
    {
        Value = value;
    }

    private Result(string error) : base(false, error)
    {
    }

    public static Result<T> Ok(T value) => new Result<T>(value);
    public static new Result<T> Fail(string error) => new Result<T>(error);
}

Note that two Result classes are implemented, both aiming to explicitly represent the success or failure of an operation as well as the error details. The base class defines the common structure for any result. It has the IsSuccess property, which indicates whether the operation was successful, and the Error property, which contains the error message in case of failure.

The generic Result<T> class extends this idea to operations that return a value. When the operation is successful, in addition to IsSuccess being true, the result also carries a Value of type T. For this, there are two distinct private constructors: one for success, which receives the value, and another for failure, which receives only the error message. This avoids the creation of invalid states within the class itself.

The static methods Ok and Fail in the generic version follow the same pattern as the base class, but now allow data to be returned along with the result. This is useful in scenarios such as searches, validations or external integrations, where you want to return a value on success or a clear explanation on error, without throwing exceptions for expected situations.

An important point is that the consumer of the result must always check IsSuccess before accessing Value. This is a desirable behavior, as it forces the API user to explicitly handle failures, preventing silent errors or unexpected flows.

Now create a new class called UserService and add the following code to it:

namespace PracticingExceptionHandling;

public class UserService
{
    public Result<User> CreateUser(User newUser)
    {
        if (string.IsNullOrWhiteSpace(newUser.Name))
            return Result<User>.Fail("Name is required");

        var user = new User()
        {
            Id = newUser.Id,
            Name = newUser.Name,
            BankAccountNumber = newUser.BankAccountNumber,
            Status = 1
        };

        return Result<User>.Ok(user);
    }
}

Here we have the CreateUser method which validates whether the Name property is null or contains only spaces. If either of these conditions is true, the method immediately returns a failure result Result<User>.Fail, preventing the creation of an invalid user and explicitly stating the reason for the error.

If the validation passes, a new User object is instantiated with the data provided in the request, also applying a default value for Status. Finally, the method returns a success result Result<User>.Ok, encapsulating the created object.

The next step is to call the CreateUser method, so in the Program class, add the following endpoint:

app.MapPost("/users/create", (User newUser, UserService userService) =>
{
    var result = userService.CreateUser(newUser);

    if (!result.IsSuccess)
        return Results.BadRequest(new { error = result.Error });

    return Results.Ok(result.Value);
});

In this endpoint, we define a POST route /users/create that receives a User object and a UserService instance. Upon receiving the request, the endpoint calls the CreateUser method, which returns a Result<User>. This return encapsulates both success and potential failure.

Next, the endpoint checks the IsSuccess property. If the result indicates failure, it returns a 400 Bad Request, including the error message (result.Error) in the response body, clearly explaining the reason for the rejection to the client. If the operation is successful, the endpoint returns a 200 OK with the created object (result.Value).

In this way, we use the Result Pattern as a clear contract between the layers, which improves the readability and predictability of the API’s behavior, reserving exceptions only for unpredictable scenarios.

✨ Expressive Exceptions

A common mistake when using exceptions is creating weak or generic exceptions. We’ve already seen that exceptions should be reserved for unpredictable errors; in this case, when an error occurs, it’s important to obtain as much information as possible about why that exception happened. Consider the example below:

throw new Exception("User not found");

The problem here is that the system knows something went wrong but doesn’t know exactly what went wrong (that is, the reason for the error).

To solve this, we can create a custom exception. Custom exceptions are classes that represent domain or application specific errors. Consider the following example:

public class UserNotFoundException : Exception
{
    public UserNotFoundException(string id)
        : base($"User with id {id} was not found")
    {
    }
}

Now the error has an identity. It provides user details and makes it explicit that this is a domain exception and is important to the application, much more explicit than a generic exception.

Now see how it looks in the call:

❌ Generic

throw new Exception("User not found");

✅ Specific (Custom Exception)

throw new UserNotFoundException(id);

With custom exceptions, we obtain better tracking (logs), the possibility of specific handling and more expressive code.

Creating Exceptions with Helper Methods

When using custom exceptions, it’s common to have duplicate exceptions, for example, when the same exception is thrown in multiple parts of the class. Note the example below:

public User(string name)
{
    if (string.IsNullOrWhiteSpace(name))
        throw new InvalidUserException("Name cannot be empty");

    Name = name;
}

public void UpdateName(string name)
{
    if (string.IsNullOrWhiteSpace(name))
        throw new InvalidUserException("Name cannot be empty");

    Name = name;
}

In both cases, the same exception is being thrown, using the same details. To reuse exceptions, we can create helper methods and even generic methods depending on the context in which they are used. In the case above, we can create a method that expects the name of a property and returns a custom exception and use it everywhere it is useful:

   public User(string name)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw NewInvalidPropertyException("Name");

        Name = name;
    }

    public void UpdateName(string name)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw NewInvalidPropertyException("Name");

        Name = name;
    }

    private static InvalidUserException NewInvalidPropertyException(string property)
    {
        return new InvalidUserException($"{property} cannot be empty");
    }

Conclusion

Exceptions are an excellent feature of ASP.NET Core and are especially useful in unpredictable scenarios or as a last line of defense to prevent invalid states from progressing through the flow or persisting in the database. The problem arises when they are used to handle expected errors or in a generic way, without providing sufficient details.

In this post, we explore best practices in the use of exceptions and examine the Result Pattern as a more suitable alternative for predictable scenarios.

I hope this post helps you make better decisions when using exceptions, when to avoid them and how to apply them effectively in your applications.

If you’ve worked with .NET for any length of time, you’ve made peace with the .sln file. Not because it’s good (it isn’t) but because it’s the format we have. It’s verbose, GUID-laden and a reliable source of merge conflicts on Friday afternoons. It’s the format we tolerate, not the one we’d choose.

The good news is there’s a new format in town. The .slnx format is Microsoft’s XML-based replacement for the venerable .sln file, and it has been steadily gaining first-class support across Visual Studio, the .NET CLI, MSBuild and Rider over the last year. As of .NET 9.0.200 and Visual Studio 17.13+, you can use it for real projects without crossing your fingers. And as of .NET 10, dotnet new sln defaults to .slnx.

In this post, let’s talk about what .slnx is, why it exists, what it gets right and where you might get tripped up.

A Quick SLN Retrospective

To appreciate why we’re getting a new format, let’s remember what we’ve been working with. Here’s a typical fragment of an .sln file.

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.10.34804.81
MinimumVisualStudioVersion = 10.0.40219.1
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MyApi", "MyApi\MyApi.csproj", "{F95781B3-A973-4D19-9585-974DA143E6A1}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{8FC526EA-218B-4615-8410-4E1850611F38}"
ProjectSection(SolutionItems) = preProject
Directory.Build.props = Directory.Build.props
EndProjectSection
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Release|Any CPU = Release|Any CPU
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{F95781B3-A973-4D19-9585-974DA143E6A1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{F95781B3-A973-4D19-9585-974DA143E6A1}.Debug|Any CPU.Build.0 = Debug|Any CPU
{F95781B3-A973-4D19-9585-974DA143E6A1}.Release|Any CPU.ActiveCfg = Release|Any CPU
{F95781B3-A973-4D19-9585-974DA143E6A1}.Release|Any CPU.Build.0 = Release|Any CPU
EndGlobalSection
EndGlobal

Oof. The SLN format is a custom Microsoft format that has some weird quirks. Every project gets a GUID. Solution folders are themselves projects with their own GUIDs. Configuration combinations even get cross-multiplied so a four-project solution with two configurations and two platforms produces 16 lines of nearly identical setup.

The pain points are well known to us all. If even two developers add a project at the same time, both edit GlobalSection(ProjectConfigurationPlatforms), and Git throws its hands up.

GUIDs, bless their hearts, are not for human eyes. It’s a nightmare trying to figure out which project owns which configuration block. And outside of Visual Studio, generating or modifying .sln files reliably often requires a tool like slngen because no one wants to write the parser themselves.

This is what the .slnx tries to fix.

Looking Inside the .slnx

Here’s the same project, but expressed as .slnx.

<Solution>
  <Folder Name="/Solution Items/">
    <File Path="Directory.Build.props" />
  </Folder>
  <Project Path="MyApi/MyApi.csproj" />
</Solution>

Notice how we have no GUIDs, no cross-multiplied configuration table and no EndGlobalSection markers. Even a developer who is foreign to the .slnx format can read it and immediately understand it.

Expanding a little, here’s an example from a layered solution.

<Solution>
  <Folder Name="/Solution Items/">
    <File Path=".editorconfig" />
    <File Path="Directory.Build.props" />
    <File Path="Directory.Packages.props" />
  </Folder>
  <Folder Name="/src/">
    <Project Path="src/Application/Application.csproj" />
    <Project Path="src/Domain/Domain.csproj" />
    <Project Path="src/Infrastructure/Infrastructure.csproj" />
    <Project Path="src/Web.Api/Web.Api.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/UnitTests/UnitTests.csproj" />
    <Project Path="tests/IntegrationTests/IntegrationTests.csproj" />
  </Folder>
</Solution>

If you compare this to the equivalent .sln, you’re looking at maybe a third of the lines, with none of the GUID overhead. If you need to override configurations for a specific project (like, say your test project shouldn’t build in Release mode) you can express that with a Configurations element on the project. In reality, most projects won’t need it at all. If you do, you can review examples in microsoft/vs-solutionpersistence and its samples wiki.

If the .slnx looks similar to a .csproj, that’s intentional. Microsoft’s reasoning is that XML is already the format the rest of MSBuild speaks, the team already had a parser for it, and features like comments and attributes are first-class citizens. A JSON or YAML format might have been trendier, but it would have forced the team to invent semantics for things .csproj already has solved problems for.

Migrating Existing Projects

Existing projects are a different conversation. Here’s what you get by migrating, and how to do it cleanly.

• Merge conflicts are more manageable. Because there are no GUIDs that change every time you touch a project, the diffs you see in PRs are meaningful. If you add a project, you see one line added. Move a project to a different folder, and you see the path change. Nobody has to play GUID detective.
• You can reasonably edit by hand. You’ll never want to hand-edit a .sln unless it’s an emergency. With .slnx, opening it in your editor of choice is perfectly reasonable. I’ve fixed broken solution layouts in a text editor faster than Visual Studio would have let me click through the dialogs.
• Tooling has standardized what a solution is. Microsoft has open-sourced the parser as the Microsoft.VisualStudio.SolutionPersistence NuGet package. This means MSBuild, the .NET CLI and third-party tools are all reading the same file the same way.

Based on the official dotnet sln reference, the actual conversion is one command.

dotnet sln migrate

If you run this in a directory with an .sln file, you’ll get an .slnx file beside it. From Visual Studio, you can also use File -> Save Solution As… and pick XML Solution File (.slnx) from the dropdown. Rider supports a similar flow.

You don’t want to keep both files in the repository. The dotnet sln commands don’t reliably pick the right one when you have both, and it’s easy for the two to get out of sync as people add or remove projects. Pick when to cut over, delete the old file and move on. While there is a community tool called dotnet-sln-sync that helps, that should only be used temporarily and not long term.

As you convert over, here’s a quick checklist to avoid any headaches:

• Verify your global.json allows the right SDK. You need at least .NET 9.0.200 for full CLI support. If your global.json pins to something older, the migrate command won’t work.
• Check your CI build agents. If you’re on self-hosted Azure DevOps agents, for example, confirm they’re running an SDK new enough to handle .slnx.
• Audit your pipelines. Anywhere you have references directly to .sln, update the path. Wildcard references like **/*.sln will miss the new file. If you are using templates where you have a mix of .sln and .slnx, a pattern like **/*.sln* will be useful.
• Look out for dependent tools. Tools like slngen don’t yet support .slnx at the time of this post (you can track the issue here). If you’re reliant on a tool outside of the Microsoft umbrella, check before you migrate.

Some Rough Edges

The .slnx format is no longer “preview” in any practical sense, but the ecosystem around it is still catching up.

• Visual Studio file association. Double-clicking a .slnx file doesn’t open Visual Studio by default. You can fix this with a file association or just open it from inside the IDE.
• C# Dev Kit in VS Code. It works, but you may need to set dotnet.defaultSolution to the path of your .slnx if it isn’t auto-detected.
• Globbing. You can’t write <Project Path="src/**/*.csproj" /> and have it discover projects automatically. The team’s reasoning, captured in the globbing feature request, is that globbing slows down solution loading on large repos because Visual Studio has to scan the file system before it can render anything. That makes sense, but I think plenty of us would happily trade a slower cold load for never having to add another project entry by hand.
• Third-party tools. Anything that parses .sln directly needs to update. Hopefully the open-source parser library accelerates that, but you’ll find holdouts.

None of these are dealbreakers for new projects. For older codebases with a lot of tooling baked in, it’s worth doing a small pilot before flipping the whole repo.

Wrapping Up

The .slnx format isn’t a revolutionary feature. It doesn’t change how you write code, it doesn’t add new build capabilities, and it doesn’t speed up your application. It is, however, one of those quality-of-life upgrades that quietly results in fewer merge conflicts, less time staring at GUIDs, less friction in your CI pipelines once they’re set up.

If you’re starting a new .NET solution, just use .slnx from day one. And with .NET 10, you’ll get it without lifting a finger. If you’re maintaining an existing .sln file, plan a migration when you have a slow week, audit your tooling and cut over cleanly. The format isn’t going anywhere, and getting ahead of the transition is easier than waiting for some downstream tool to force your hand.

Thanks for reading, and happy coding!

Further Reading

• New, simpler solution file format
• Introducing support for SLNX in the .NET CLI
• microsoft/vs-solutionpersistence
• dotnet sln command reference
• .NET 10 breaking change: dotnet new sln defaults to SLNX

If you’ve ever created an API in ASP.NET Core using the classic approach of dividing it into Controllers, Services and Repositories, you’ve probably faced some difficulties in creating the necessary structure. With each new feature, more files are scattered, more cross-dependencies appear, and it becomes more difficult to understand what truly belongs to each use case.

But what if, instead of organizing the code by technical layers, you organized it by system functionalities? That’s exactly what Vertical Slice Architecture proposes.

Instead of a giant folder for Services and another for Repositories, each functionality becomes a vertical “slice” of the system, containing everything it needs: endpoint, business rules, validations, DTOs and data access. Each request then has its own isolated flow.

In this post, we’ll explore Vertical Slice Architecture and how to apply it in a practical ASP.NET Core project.

Layered Architecture and Its Trade-offs

Layered Architecture is one of the best-known and most widely used architectural styles in enterprise software development. It’s commonly found in ASP.NET Core, Java/Spring and other enterprise platforms. The main point of this style is that it organizes the system into horizontal layers, each with well-defined responsibilities.

The classic architecture typically divides the system into four main layers (despite variations):

1. Presentation (UI / API): Controllers, endpoints, user interfaces
2. Application / Service: Orchestrates use cases
3. Domain / Business: Business rules
4. Infrastructure / Data Access: Database, external integrations, files, etc.

Each layer depends only on the layer immediately below it (or on abstractions), creating a predictable flow of dependencies.

Despite its popularity, this approach has some drawbacks, such as flow coupling. Although the layers are separate, use cases traverse all of them: Controller -> Service -> Domain -> Repository -> Database. This creates structural flow coupling.

A simple change in one use case can require changes in multiple layers. This results in scattered files and constant navigation between projects/folders to find important parts of the code.

Another negative point is that this architecture organizes code by technical type, not by functionality. For example, if you want to understand the “Create Order” use case, you will need to open multiple files in different folders (Controllers, Services folder, Repositories folder, etc.).

When can Layered Architecture start to become a problem? In large systems with many use cases, a high volume of changes per feature, a complex domain that requires strong modeling, and large teams working on multiple fronts. In scenarios like this, an excellent alternative is Vertical Slice Architecture.

Vertical Slice Architecture as an Alternative

Vertical Slice Architecture is an architectural style where the system is designed and organized by features (functionalities), rather than by technical layers as in traditional layer-based approaches.

Vertical Slice emerged as an alternative to problems with traditional approaches, such as the difficulty in maintenance due to classes being scattered throughout the program.

The proposal of Vertical Slice is simple: organize the code by functionality (feature) and not by technical type. Imagine you need to create functionalities for creating and canceling an order.

In a layered approach, we would have the standard structure:

Controller 
- OrderController 
Service 
- OrderService
Repository 
- OrderRepository
Dtos 
- OrderDto

In a Vertical Slice Architecture, you would organize things by use case:

Features/
CreateOrder/
CreateOrderEndpoint.cs
CreateOrderHandler.cs
CreateOrderRequest.cs
CreateOrderValidator.cs

CancelOrder/
CancelOrderEndpoint.cs
CancelOrderHandler.cs
CancelOrderRequest.cs
CancelOrderValidator.cs

Much clearer now, isn’t it? The image below shows a simple comparison between Vertical Slice Architecture and Layered Architecture:

Implementing Vertical Slice Architecture

Now we’re going to create an API using Vertical Slice Architecture. Our API will be used to manage a subscription service. You can access the complete code in this GitHub repository: Vertical Slice Subs Source Code.

Our project will follow this structure:

Creating the Domain Model

To create the base application, you can use the following command in the terminal:

dotnet new web -o SubscriptionManagement

Then, inside the project, create a new folder called “Features,” and inside it another folder called “Subscriptions”. Add the following class and enum to the folder Subscriptions:

namespace SubscriptionManagement.Features.Subscriptions;

public class Subscription
{
    public Guid Id { get; private set; } = Guid.NewGuid();
    public string ServiceName { get; private set; } = default!;
    public decimal Price { get; private set; }
    public DateOnly StartDate { get; private set; }
    public DateOnly? TrialEndsAt { get; private set; }
    public SubscriptionStatus Status { get; private set; }

    private Subscription() { }

    public Subscription(string serviceName, decimal price, DateOnly startDate, DateOnly? trialEndsAt)
    {
        ServiceName = serviceName;
        Price = price;
        StartDate = startDate;
        TrialEndsAt = trialEndsAt;
        Status = SubscriptionStatus.Active;
    }

    public void Cancel()
    {
        if (Status == SubscriptionStatus.Canceled)
            throw new InvalidOperationException("Subscription already canceled.");

        Status = SubscriptionStatus.Canceled;
    }
}

namespace SubscriptionManagement.Features.Subscriptions;

public enum SubscriptionStatus
{
    Active = 1,
    Canceled = 2
}

The next step is to create the database related files. In the root of the project, create a new folder called “Infrastructure” and add the following class to it:

• AppDbContext

using Microsoft.EntityFrameworkCore;
using SubscriptionManagement.Features.Subscriptions;

namespace SubscriptionManagement.Infrastructure;

public class AppDbContext : DbContext
{
    public DbSet<Subscription> Subscriptions => Set<Subscription>();

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

Feature 1: CreateSubscription

Command

Our first feature will be used to create a new subscription. Inside the Features/Subscriptions/ folder, create a new folder called “CreateSubscriptions” (all the classes below should be created within this structure: Features/Subscriptions/CreateSubscriptions), and inside it, add the following record:

public record CreateSubscriptionCommand(
    string ServiceName,
    decimal Price,
    DateOnly StartDate,
    DateOnly? TrialEndsAt
);

Validator

Next, let’s create a validator. Create the class below:

using FluentValidation;

namespace SubscriptionManagement.Features.Subscriptions.CreateSubscriptions;

public class CreateSubscriptionValidator : AbstractValidator<CreateSubscriptionCommand>
{
    public CreateSubscriptionValidator()
    {
        RuleFor(x => x.ServiceName)
            .NotEmpty()
            .MaximumLength(100);

        RuleFor(x => x.Price)
            .GreaterThan(0);

        RuleFor(x => x.TrialEndsAt)
            .GreaterThan(x => x.StartDate)
            .When(x => x.TrialEndsAt.HasValue);
    }
}

Handler

The concept of a Handler is common in projects that use Vertical Slice Architecture. A Handler is the component responsible for executing the application’s use case—that is, it contains the logic of the functionality.

Typically, the Handler is the class or function that receives a command or query and executes the corresponding operation, coordinating business rules, database access, calls to other services and response return.

Handlers work well in architectures that use Command Query Responsibility Segregation (CQRS), especially when using MediatR. Here, the concept doesn’t depend on MediatR; it already exists simply with the organization by slices.

Now, let’s create our first Handler. To do this, create the classes below:

namespace SubscriptionManagement.Features.Subscriptions.CreateSubscriptions;

public record CreateSubscriptionCommand(
    string ServiceName,
    decimal Price,
    DateOnly StartDate,
    DateOnly? TrialEndsAt
);

using SubscriptionManagement.Infrastructure;

namespace SubscriptionManagement.Features.Subscriptions.CreateSubscriptions;

public static class CreateSubscriptionHandler
{
    public static async Task<IResult> Handle(CreateSubscriptionCommand command, AppDbContext dbContext)
    {
        var subscription = new Subscription(
            command.ServiceName,
            command.Price,
            command.StartDate,
            command.TrialEndsAt
        );

        dbContext.Subscriptions.Add(subscription);
        await dbContext.SaveChangesAsync();

        return Results.Created($"/subscriptions/{subscription.Id}", subscription);
    }
}

Note that the handler class has a method to create a new subscription, and returns an HTTP Created status.

Endpoint

In Vertical Slice Architecture, it’s also common to declare separate endpoints. In this case, we’ll have one endpoint for each use case. Create the following class:

using FluentValidation;
using SubscriptionManagement.Infrastructure;

namespace SubscriptionManagement.Features.Subscriptions.CreateSubscriptions;

public class CreateSubscriptionEndpoint
{
    public static void Map(WebApplication app)
    {
        app.MapPost("/subscriptions", 
            async (CreateSubscriptionCommand command, 
                AppDbContext dbContext, 
                IValidator<CreateSubscriptionCommand> validator) =>
            {
                var validation = await validator.ValidateAsync(command);

                if (!validation.IsValid)
                    return Results.ValidationProblem(validation.ToDictionary());

                return await CreateSubscriptionHandler.Handle(command, dbContext);
            });
    }
}

Here we are defining an endpoint for creating a new subscription. It starts by validating the data, and if it’s valid, it uses the handler to create the new record and return the expected status.

Feature 2: CancelSubscription

The subscription creation flow is ready. Now let’s consider the cancellation use case. Following the same logic as before, within the Features/Subscriptions structure, create a new folder called CancelSubscriptions and add the following classes to that folder:

Command

namespace SubscriptionManagement.Features.Subscriptions.CancelSubscriptions;

public record CancelSubscriptionCommand(Guid Id);

Handler

using Microsoft.EntityFrameworkCore;
using SubscriptionManagement.Infrastructure;

namespace SubscriptionManagement.Features.Subscriptions.CancelSubscriptions;

public static class CancelSubscriptionHandler
{
    public static async Task<IResult> Handle(
        CancelSubscriptionCommand command,
        AppDbContext dbContext)
    {
        var subscription = await dbContext.Subscriptions
            .FirstOrDefaultAsync(x => x.Id == command.Id);

        if (subscription is null)
            return Results.NotFound();

        try
        {
            subscription.Cancel();
            await dbContext.SaveChangesAsync();
        }
        catch (InvalidOperationException ex)
        {
            return Results.BadRequest(new { error = ex.Message });
        }

        return Results.NoContent();
    }
}

Endpoint

using SubscriptionManagement.Infrastructure;

namespace SubscriptionManagement.Features.Subscriptions.CancelSubscriptions;

public static class CancelSubscriptionEndpoint
{
    public static void Map(WebApplication app)
    {
        app.MapDelete("/subscriptions/{id:guid}",
            async (Guid id, AppDbContext dbContext) =>
            {
                var command = new CancelSubscriptionCommand(id);
                return await CancelSubscriptionHandler.Handle(command, dbContext);
            });
    }
}

Program Class

The final step is to configure the Program class to use the endpoints we created above, to save time, we’ll use an in-memory database. So add the following code to the Program class:

using FluentValidation;
using Microsoft.EntityFrameworkCore;
using SubscriptionManagement.Features.Subscriptions.CancelSubscriptions;
using SubscriptionManagement.Features.Subscriptions.CreateSubscriptions;
using SubscriptionManagement.Infrastructure;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(opt =>
    opt.UseInMemoryDatabase("subscriptions-db"));

builder.Services.AddValidatorsFromAssemblyContaining<CreateSubscriptionValidator>();

var app = builder.Build();

CreateSubscriptionEndpoint.Map(app);
CancelSubscriptionEndpoint.Map(app);

app.Run();

Note that the Program class is quite simple, only creating configurations such as the use of the in-memory database, validations and the calling of the endpoint methods: CreateSubscriptionEndpoint.Map(app); and CancelSubscriptionEndpoint.Map(app);.

Testing the Application

Now, let’s run the endpoints and verify that the application is functional.

Run the application and make a POST request to the route http://localhost:5127/subscriptions using the JSON below as the body:

{
  "serviceName": "Aspflix",
  "price": 39.90,
  "startDate": "2026-03-01",
  "trialEndsAt": "2026-03-15"
}

If everything goes well, you will receive the following response in a debugger like Progress Telerik Fiddler Everywhere:

And to test the cancellation, simply execute a DELETE request to the route: http://localhost:5127/subscriptions/ID_HERE.

And you will receive the following response:

If you try to cancel again, you will receive a validation error.

Conclusion

Vertical Slice Architecture offers an alternative approach focused on system functionalities, rather than predefined structures.

As we saw in the article, this brings advantages such as ease of maintenance, due to the low cognitive requirements for understanding the project. It also offers agility in finding functions, as business rules are separated by use case. Furthermore, we implemented a subscription project in ASP.NET Core using Slice Architecture.

I hope this post helps you decide which architectural approach to use when creating or refactoring your projects.

I remember exactly where I was when Visual Studio 2026 dropped back in November: at my desk, watching the Microsoft launch event with one eye and refactoring an IDataReader implementation with the other.

The keynote was typical Microsoft. There was a lot of “reimagining how developers work.” There was, of course, a slide with the word “intelligent” on it at least eight times. And the word “Copilot” appeared on screen so many times I started to wonder if Microsoft’s marketing team had been replaced by an infinite loop that just prints Copilot forever.

Then I installed the thing.

The first week with VS 2026 was the most disoriented I’ve felt in a Visual Studio release since the menu bar went all-caps in 2012 and I spent a month reading angry forum threads about it.

In 2026, I was tripped up by the just-slightly different Solution Explorer, the Copilot panel that lives where my Test Explorer used to live, the general Copilot onslaught and the interesting design choices. I felt like everything on my desk had been moved slightly to the left.

That was temporary. As with most new technology, eventually things felt normal again. I was finding workflows that genuinely beat my old ones and I stopped noticing the cosmetic changes. So here’s where I am six months later … same machine, same kind of solution I work in every day, just a different IDE around it.

We meet again, old friend. At least the menu bar isn't in caps.

Six months in, I feel comfortable. Six months is long enough to live with the rough edges, and find what’s genuinely useful. So I’m here to share them with you.

As an aside: to keep my sanity intact, I’m going to use the word “Copilot” only when I absolutely have to. Microsoft has decided that every feature in Visual Studio is now Copilot-something … Copilot Chat, Copilot Edits, Copilot Agent, Copilot Workspaces, GitHub Copilot, Copilot for Azure, Copilot for Pull Requests and so on. So when I say “the agent” or “the AI thing in the sidebar,” you’ll know what I mean.

The Performance Story Is Real

I’ll lead with this, mostly because it was the thing I was most skeptical about. Every Visual Studio release for the past decade has touted “X% faster solution load!” and, to me, every Visual Studio release for the last decade has felt (roughly) the same speed once you test it with your beefy codebase.

VS 2026 is genuinely faster. Not “marketing-faster” … actually faster. The 64-bit-everywhere story that started with VS 2022 has matured into something that handles large solutions without the periodic “please hold” pauses we’re all familiar with. In Microsoft’s VS2026 launch post, they say they cut hangs by over 50%.

The IntelliSense responsiveness is the part I notice most. Typing a . after an object now produces suggestions roughly when I expect them to appear. A low bar? Definitely, but previous versions frequently limboed under it.

Agent Mode Is Useful, When You Pick the Right Job

GitHub Copilot’s agent mode in Visual Studio 2026—or, as Microsoft prefers, GitHub Copilot Agent Mode powered by Copilot in Visual Studio with Copilot—has improved tremendously since Visual Studio 2022. Six months in, I think it’s genuinely useful, but for a specific set of tasks.

In my experience, it works well with scoped, well-defined refactors. If I want to ask: Hey Copilot, add a new health check for this Cosmos container and follow the pattern in my existing health checks. (Yes, I sometimes talk to Copilot like a home assistant.) Or: Take my new controller and add the same logging pattern as the others in this project. And, after discovering some methods in a codebase with 11 nested if statements: Convert this for loop to a LINQ expression but keep it readable. It’s effective enough that I’ve stopped writing this kind of code by hand.

In my experience, things get harder when the agent needs to understand why something exists. The agent will happily refactor a piece of code that only exists because of, say, a weird third-party integration constraint from 2018, and the resulting code will be cleaner, more maintainable … and broken in production. Did I actually break something in production? Not this time. But I would have.

To be fair to the agent, this is exactly where it needs context. It doesn’t read minds (although it sure does try). Here’s a pattern I’ve leaned on.

// AGENT NOTES:
// - This service must remain synchronous; the upstream caller cannot
//   be made async without a contract change.
// - The string "PRIME" is required by the third-party integration. 
//   I don't like it but they won't change it. Do not "improve" it 
//   to PersonType.Prime.ToString().
// - Cancellation tokens must be forwarded; do NOT pass `default`.

When the agent has clear context like this, it really delivers. Below is the agent producing two new health check files plus a registration update in Program.cs, all from one prompt asking it to mirror an existing pattern. The result is a careful refactoring with the right substitutions swapped in. That’s exactly the kind of work I’m happy to hand off.

The agent panel and one of the two generated files. Three files changed, zero hand-written by me. (My team is thankful for the latter.)

This sounds like babysitting, and it is. Welcome to AI-driven development, my friends. The 10 seconds of setup saves me from a 10-minute cleanup later. When the prep is solid, the result is solid.

For more information on custom instructions, check out the Microsoft documentation.

Test Explorer Isn’t Frustrating

In my experience, the Test Explorer seems to be much improved in Visual Studio 2026. If I had to sum it up in previous versions, I’d say “it’s fine” … after all, do we ever get jazzed about tests? In previous releases, I kept saying “it’s fine” until I had a few thousand tests, at which point it started getting opinionated about which tests to run.

The new version is faster, the filtering predictably works, and it doesn’t lose track of which tests are running when you switch branches mid-execution. Try it yourself. Run your full test suite and watch the Test Explorer not embarrass itself. It’s a small joy.

One of those things you don't notice until it stops getting in your way.

Better Git Integration

Visual Studio’s Git tooling has historically been one of the IDE’s more underwhelming features. Until recently, my workflow was:

1. Make code changes in Visual Studio.
2. Run Git commands in my terminal (or a third-party tool like GitHub Desktop)
3. Ignore the IDE’s Git panel entirely.

With VS 2026, I’m finally doing real Git work inside the tool. The new staging interface is better. The conflict resolution UI is also better than it used to be. The “please show me an actual diff and not a vague summary” feature is good.

Now, it’s no GitKraken and it doesn’t try to be. But it’s good enough that I no longer switch over to a terminal for routine operations, and that works for me.

Three-way merge view, in the IDE I'm already in. Rejoice!

Hot Reload That Reloads More Often

Hot Reload has been one of those features that worked on Friday afternoons if I said “please work” (especially for ASP.NET Core). Any other time, I’d change a method body, save, watch the IDE think very hard about it, and then get: “Hot Reload was unable to apply your changes. Restart the application?”

The “hot” in “Hot Reload” was stretching the truth at times (with the understanding that getting it right isn’t as simple in .NET as it is for languages like JavaScript).

With VS 2026, I now reach for it instinctively instead of cynically. Method-body edits in controllers, services and Razor pages just apply. You change a string in a controller, hit Save and see the change. You know, the way it was supposed to work in 2021. The way it kind of worked in 2023. The way it now actually works in 2026.

When Hot Reload can’t apply a change (because the change requires a metadata update or you’ve added a field or whatever the actual reason is), the IDE now tells me clearly why instead of vaguely throwing up its hands. That alone goes a long way. I know whether to keep iterating or to just restart the host.

Debugger Improvements (Especially with Async Traces)

Have you ever stared at an async stack trace and felt your soul leave your body? Just me?

Historically, when an exception bubbled up from somewhere deep in an async/await chain, the stack trace was a wall of MoveNext calls and state machine internals. It was tremendously useful if you wanted to learn about the C# compiler, but not great if you wanted to know which of your methods actually threw.

Things are looking better in Visual Studio 2026. The debugger now stitches together async call chains into something that reads like the call graph you actually wrote. The MoveNext noise is collapsed by default. The original calling method is shown as the parent frame and not buried six levels down. When an exception is thrown inside a Task.WhenAll, you can see which task threw without reverse-engineering the parallel structure.

An async exception, with the actual call chain visible. No MoveNext translation required.

On top of that, conditional breakpoints feel faster to evaluate, and the tracepoints (where you can log a message without breaking) is a one-click affair instead of a buried right-click option.

Small wins. But debugging is the thing I do every day, and small wins on the thing you do every day add up fast.

The Verdict

Look, the Copilot stuff is genuinely impressive. The agent demos at the keynote were the kind of thing that makes you want to fire up the installer immediately. And after six months, I’ll admit that I use it every day.

But Visual Studio 2026 is a genuine step forward for the boring reasons. The performance is real. The Test Explorer doesn’t stress me out. The debugger provides stack traces a human can read. The agent mode handles the kind of work I’d previously do by hand. Those are the wins that show up in my daily work, not the ones that show up in keynote demos.

If you’re on Visual Studio 2022 and wondering whether to upgrade: yes. Ignore the marketing, and let the unglamorous improvements do their job. Six months later, you won’t be excited about Visual Studio 2026 … and that’s exactly the point. You’ll just be working faster.

DevUI is a lightweight standalone application included with Microsoft Agent Framework that helps developers run, inspect, and debug agents and workflows during development. The tool provides a web-based interface for interactive testing alongside an OpenAI-compatible API backend, making it easier to iterate on workflows before integrating them into a larger application.

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));
}