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

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

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

Configuring Your Project

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

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

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

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

Loading Your Document

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

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

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

RadFixedDocument doc;
PdfFormatProvider prov = new();

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

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

RadFlowDocument doc;
DocxFormatProvider prov = new();

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

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

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

RadFlowDocument doc;
RtfFormatProvider prov = new();

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

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

RadFlowDocument doc;
HtmlFormatProvider prov = new();

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

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

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

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

Modifying the Documents

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

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

RadFixedDocumentEditor editor = new RadFixedDocumentEditor(doc);

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

RadFlowDocumentEditor editor = new RadFlowDocumentEditor(doc);

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

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

Typical code, then, looks like this:

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

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

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

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

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

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

RadFlowDocumentEditor editor = new RadFlowDocumentEditor(doc);

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

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

Searching a spreadsheet works similarly. The differences:

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

My find code with a workbook would look like this:

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

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

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

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

Saving Your Documents

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

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

Converting Documents

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

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

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

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

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

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

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

Typical code would look like this:

CsvFormatProvider prov = new();

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

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

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

PdfFormatProvider prov = new();

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

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

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

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

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

Try DevCraft

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

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

One Class to Rule Them All

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

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

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

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

Organization Is the Key ️

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

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

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

Creating the Project

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

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

dotnet new web -n CustomerAdmin

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

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

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

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

var builder = WebApplication.CreateBuilder(args);

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

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

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

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

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

var app = builder.Build();

app.UseCors("Default");

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

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

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

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

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

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

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

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

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

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

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

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

    return Results.Ok(customer);
});

app.Run();

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

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

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

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

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

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

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

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

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

Putting Things in Order

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

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

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

namespace CustomerAdmin.Models;

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

namespace CustomerAdmin.Models;

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

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

using CustomerAdmin.Models;
using Microsoft.EntityFrameworkCore;

namespace CustomerAdmin.Infrastructure.Data;

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

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

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

namespace CustomerAdmin.Infrastructure.Email;

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

namespace CustomerAdmin.Infrastructure.Email;

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

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

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

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

namespace CustomerAdmin.Infrastructure.Extensions;

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

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

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

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

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

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

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

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

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

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

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

        return Results.Ok(customer);
    }
}

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

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

namespace CustomerAdmin.Infrastructure.Extensions;

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

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

        return app;
    }
}

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

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

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

namespace CustomerAdmin.Infrastructure.Extensions;

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

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

        services.AddHttpClient();
        return services;
    }

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

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

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

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

using CustomerAdmin.Infrastructure.Middlewares;

namespace CustomerAdmin.Infrastructure.Extensions;

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

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

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

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

namespace CustomerAdmin.Infrastructure.Middlewares;

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

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

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

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

using CustomerAdmin.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.MapCustomerEndpoints();

app.Run();

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

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

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

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

Taking a Shortcut with Carter

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

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

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

dotnet add package Carter --version 10.0.0

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

namespace CustomerAdmin.Modules.Customers;

using System.ComponentModel.DataAnnotations;

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

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

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

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

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

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

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

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

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

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

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

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

        return Results.Ok(customer);
    }
}

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

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

using Carter;
using CustomerAdmin.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddCarter();

var app = builder.Build();

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

app.MapCarter();

app.Run();

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

Conclusion

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

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

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

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

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

Understanding the RAG Concept

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

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

How Does RAG Work?

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

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

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

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

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

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

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

Creating a RAG in ASP,NET Core

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

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

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

Prerequisites

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

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

2. A project created on the OpenAI website

3. The following models configured in your API key:

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

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

dotnet new web -o ReturnPolicy

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

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

namespace ReturnPolicy.Models;

public record QuestionRequest(string Question);

Creating the Return Policy File

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

Return Policy - Updated July 2025

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

To be eligible for a return:

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

Please contact our support team before sending any returns.

Creating the Logic for Generating the Response

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

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

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

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

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

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

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

            var client = new OpenAIClient(apiKey);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        if (exists) continue;

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

            var insertComand = conn.CreateCommand();

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

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

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

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

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

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

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

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

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

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

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

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

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

    var topChunks = GetTopChunks(queryVector, 3);

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

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

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

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

    var selectCmd = conn.CreateCommand();

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

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

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

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

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

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

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

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

Now, let’s analyze each method:

1. GetAnswerAsync(string question)

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

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

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

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

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

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

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

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

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

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

3. SplitIntoChunks(string text, int maxLength)

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

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

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

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

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

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

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

Adding the API Key

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

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

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

using ReturnPolicy.Services;

var builder = WebApplication.CreateBuilder(args);

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

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

app.Run();

Running the Application and Testing the RAG

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

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

Body:

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

So the generated response will be something like this:

The complete response returned by the model was:

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

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

Conclusion

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

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

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

Progress Agentic RAG

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

In practice, Progress Agentic RAG stands out for:

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

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

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

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

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

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

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

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

Configuring the Project

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

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

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

app.MapControllers();

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

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

Configuring the Grid

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

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

</kendo-grid>

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

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

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

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

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

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

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

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

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

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

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

Using scrollToItem

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

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

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

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

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

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

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

Fetching New Data

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

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

A typical dropdown list would look like this:

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

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

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

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

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

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

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

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

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

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

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

Try Telerik DevCraft

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

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

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

Common Integration Issues

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

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

Temporary Network Errors

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

Temporary Unavailability of External Services

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

Inconsistent or Invalid Data

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

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

Understanding the Retry Pattern

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

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

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

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

Implementing Retry Pattern in ASP.NET Core

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

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

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

Polly for Resilience

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

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

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

Creating the Product Catalog API

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

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

dotnet new web -o PollyProducts

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

dotnet add package Polly

dotnet add package Microsoft.Extensions.Http.Polly

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

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

namespace PollyProducts.Policies;

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

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

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

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

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

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

                return default;
            }
        });

        return builder.Build();
    }
}

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

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

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

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

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

using PollyProducts.Policies;

var builder = WebApplication.CreateBuilder(args);

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

var retryPipeline = ContextRetryPolicy.CreatePipeline();

var app = builder.Build();

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

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

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

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

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

        return resp;
    });

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

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

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

app.Run();

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

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

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

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

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

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

Creating the Product Image API

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

dotnet new web -o BaseImages

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

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

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

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

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

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

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

Simulating Retries

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

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

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

Conclusion and Next Steps

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

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

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

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

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

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

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

Built in Validation for Minimal APIs

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

Here’s a simplified example that shows the problem.

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

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

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

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

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

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

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

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

There were ways around this: you could use filters, helper methods or third-party validators. Even so, it was frustrating that Minimal APIs didn’t have the baked-in validation experience you have with controller-based APIs.

.NET 10 adds built-in validation support for Minimal APIs. You can enable it with one registration call:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<OrderDbContext>();

// Enables built-in validation for Minimal APIs
builder.Services.AddValidation();

var app = builder.Build();

Once enabled, ASP.NET Core automatically applies DataAnnotations validation to Minimal API parameters. This includes query, header and request body binding.

You can also disable validation for a specific endpoint using DisableValidation(), which is handy for internal endpoints or partial updates where you intentionally accept incomplete payloads.

With validation handled by the framework and the attributes added to our models, endpoints can focus on business logic.

Validation Error Responses

When validation fails, ASP.NET Core returns a standardized ProblemDetails response with an errors dictionary.

A typical response looks like this.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "CustomerEmail": [
      "The CustomerEmail field is required."
    ],
    "Items[0].Quantity": [
      "Quantity must be between 1 and 1000"
    ]
  }
}

OpenAPI 3.1: Modernizing API Documentation

.NET 10’s built-in OpenAPI document generation supports OpenAPI 3.1 and JSON Schema 2020-12. The default OpenAPI version for generated documents is now 3.1.

OpenAPI 3.1 aligns better with modern JSON schema expectations and improves how tools interpret your schemas.

using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi(options =>
{
    // OpenAPI 3.1 is the default, but you can be explicit
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_1;

    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info = new OpenApiInfo
        {
            Title = "Order Management API",
            Version = "v1",
            Description = "Enterprise order processing system",
            Contact = new OpenApiContact
            {
                Name = "API Support",
                Email = "api-support@company.com"
            }
        };

        return Task.CompletedTask;
    });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    // JSON at /openapi/v1.json
    app.MapOpenApi();

    // YAML at /openapi/v1.yaml
    app.MapOpenApi("/openapi/{documentName}.yaml");
}

app.Run();

Note the YAML route: in .NET 10, you generate YAML by using a route ending in .yaml or .yml, typically with {documentName} in the path.

Schema Improvements in Practice

OpenAPI 3.0 often expressed nullability using nullable: true.

components:
  schemas:
    ShippingAddress:
      type: object
      nullable: true
      properties:
        street:
          type: string
          nullable: true
        city:
          type: string

OpenAPI 3.1 allows us to use union types:

components:
  schemas:
    ShippingAddress:
      type: ["object", "null"]
      properties:
        street:
          type: ["string", "null"]
        city:
          type: string

This tends to play nicer with tooling that relies heavily on JSON Schema semantics such as OpenAPI Generator and NSwag.

EF Core 10: Named Query Filters

Global query filters are a staple for multi-tenant apps and soft deletes. The classic problem was granularity: IgnoreQueryFilters() disabled all filters at once.

EF Core 10 introduces named query filters, so you can selectively disable one filter while keeping another.

public class OrderDbContext : DbContext
{
    private readonly int _tenantId;

    public OrderDbContext(DbContextOptions<OrderDbContext> options, ITenantProvider tenant)
        : base(options)
        => _tenantId = tenant.TenantId;

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

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>()
            .HasQueryFilter("SoftDelete", o => !o.IsDeleted)
            .HasQueryFilter("TenantIsolation", o => o.TenantId == _tenantId);
    }
}

Now an admin endpoint can disable soft delete without disabling tenant isolation:

public static class AdminEndpoints
{
    public static void MapAdminEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/api/admin")
            .RequireAuthorization("Admin");

        group.MapGet("/orders/deleted", GetDeletedOrders)
            .WithSummary("Gets deleted orders for the current tenant only");
    }

    private static async Task<IResult> GetDeletedOrders(OrderDbContext db)
    {
        var deletedOrders = await db.Orders
            .IgnoreQueryFilters(new[] { "SoftDelete" }) 
            .Where(o => o.IsDeleted)
            .Select(o => new { o.Id, o.CustomerEmail, o.DeletedAt })
            .ToListAsync();

        return Results.Ok(deletedOrders);
    }
}

This capability is small, but it’s exactly the kind of real-world safety improvement that helps prevent cross-tenant data leaks.

C# 14 Improvements

.NET 10 ships alongside C# 14. For API developers, a few features immediately reduce boilerplate and improve readability.

The field Keyword: Eliminate Backing-field Boilerplate

C# 14 introduces field-backed properties, where you can reference the compiler-generated backing field directly using the field keyword.

public sealed class Order
{
    public string CustomerEmail
    {
        get;
        set
        {
            if (string.IsNullOrWhiteSpace(value))
                throw new ArgumentException("Email cannot be empty.", nameof(value));

            field = value.Trim().ToLowerInvariant();
        }
    }
}

Null-conditional Assignments

C# 14 allows null-conditional operators (?. and ?[]) on the left-hand side of assignments and compound assignments. The right-hand side is evaluated only when the receiver isn’t null. This is great for processing patches.

public sealed record OrderPatchRequest(string? NewStatus, int? NewPriority, string? NewCity);

public static class OrderPatchService
{
    public static void ApplyPatch(Order? order, OrderPatchRequest? patch)
    {
        if (patch is null) return;

        order?.Status = patch.NewStatus ?? order?.Status;
        order?.Priority = patch.NewPriority ?? order?.Priority;
        order?.Shipping?.City = patch.NewCity ?? order?.Shipping?.City;
    }
}

Note: Increment/decrement operators (++, --) aren’t allowed with null-conditional assignments. Compound assignments like += are supported.

For more details on this feature, check out the post Write Cleaner Code with C# 14’s Null-Conditional Assignment Operator.

Extension Members: Properties, Static Members and Operators

C# 14’s headline feature is extension members, which add extension properties, static extension members and even operators using the new extension block syntax.

Don’t you just love the syntax?

public static class OrderExtensions
{
    extension(Order source)
    {
        public decimal TotalValue =>
            source.Items.Sum(i => i.Quantity * i.UnitPrice);

        public bool IsHighValue => source.TotalValue > 1000m;

        public string Summary =>
            $"Order #{source.Id}: {source.Items.Count} items, ${source.TotalValue:F2} total";
    }

    extension(Order)
    {
        public static Order CreateEmpty(int tenantId) => new Order
        {
            TenantId = tenantId,
            CreatedAt = DateTime.UtcNow,
            Items = new List<OrderItem>(),
            Status = "Draft"
        };
    }
}

For more details on extension members, check out Extension Properties: C# 14’s Game-Changing Feature for Cleaner Code. (I don’t get paid by the click, I swear.)

Server-Sent Events: Simplifying Real-Time Updates

ASP.NET Core in .NET 10 adds a built-in ServerSentEvents result for Minimal APIs, so you can stream updates over a single HTTP connection without manually formatting frames.

using System.Runtime.CompilerServices;
using Microsoft.AspNetCore.Http.HttpResults;

public record OrderStatusUpdate(int OrderId, string Status, string Message, DateTime Timestamp);

public static class OrderStreamingEndpoints
{
    public static void MapStreamingEndpoints(this WebApplication app)
    {
        app.MapGet("/api/orders/{id:int}/status-stream", StreamOrderStatus)
           .WithSummary("Stream real-time order status updates");
    }

    private static ServerSentEventsResult<OrderStatusUpdate> StreamOrderStatus(
        int id,
        OrderDbContext db,
        CancellationToken ct)
    {
        async IAsyncEnumerable<OrderStatusUpdate> GetUpdates(
            [EnumeratorCancellation] CancellationToken cancellationToken)
        {
            string? last = null;

            while (!cancellationToken.IsCancellationRequested)
            {
                var order = await db.Orders.AsNoTracking()
                    .FirstOrDefaultAsync(o => o.Id == id, cancellationToken);

                if (order is null)
                {
                    yield return new(id, "ERROR", "Order not found", DateTime.UtcNow);
                    yield break;
                }

                if (!string.Equals(order.Status, last, StringComparison.Ordinal))
                {
                    yield return new(order.Id, order.Status, $"Order is now {order.Status}", DateTime.UtcNow);
                    last = order.Status;
                }

                if (order.Status is "Delivered" or "Cancelled")
                    yield break;

                await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
            }
        }

        return TypedResults.ServerSentEvents(GetUpdates(ct), eventType: "order-status");
    }
}

Client-side consumption is quite simple, too:

<script>
  function trackOrderStatus(orderId) {
    const es = new EventSource(`/api/orders/${orderId}/status-stream`);

    es.onmessage = (event) => {
      const update = JSON.parse(event.data);
      console.log(update);
      if (update.status === "Delivered" || update.status === "Cancelled") {
        es.close();
      }
    };

    es.onerror = () => console.error("SSE connection error");
    return es;
  }
</script>

Should You Upgrade to .NET 10?

.NET 10 is an LTS release. If you’re starting a new project, it’s a no-brainer.

If you’re upgrading from .NET 8 or .NET 9, a few things to keep in mind:

• Minimal API validation: If you’ve been hand-rolling validation, .NET 10’s AddValidation support can remove a surprising amount of custom code.
• OpenAPI: Built-in OpenAPI generation defaults to 3.1 and supports YAML endpoints via .yaml/.yml routes.
• EF Core: Named query filters are a real safety upgrade for multi-tenant apps, and JSON column support continues to improve (including bulk update support).
• C# 14: You can adopt new features incrementally. Even if you ignore extension members entirely, field and null-conditional assignment will show up in your codebase quickly.

The upgrade path is generally smooth: change the target in your .csproj, run tests, fix warnings and ship.

Wrapping Up

.NET 10 delivers meaningful improvements for API developers through thoughtful enhancements rather than revolutionary changes. The combination of built-in Minimal API validation, OpenAPI 3.1 and C# 14 quality-of-life features add up to a more productive and safer development experience.

Happy coding!

References

Platform updates

• Announcing .NET 10 (Microsoft)
• .NET Support Policy (Microsoft)
• What’s new in .NET 10 (Microsoft Learn)

ASP.NET Core/API Updates

• Minimal APIs quick reference – validation support (Microsoft Learn)
• Generate OpenAPI documents (Microsoft Learn)
• TypedResults.ServerSentEvents API docs (Microsoft Learn)
• ASP.NET 10: Validating incoming models in Minimal APIs (Tim Deschryver)
• And just like that .NET 10 ships tomorrow (Safia Abdalla)

Language Updates

• What’s new in EF Core 10 (Microsoft Learn)
• What’s new in C# 14 (Microsoft Learn)
• Introducing C# 14 (Microsoft .NET Blog)
• Extension members tutorial (Microsoft Learn)

.NET 10 has arrived, bringing important improvements to ASP.NET Core with a focus on efficiency and productivity. In this post, you will see the main new features: from single-file applications written in C#, to new extension methods for LINQ and EF Core, among other updates that promise to further improve your development experience.

1. New C# File-Based Applications

Despite support for higher-level instructions (introduced in .NET 6), before .NET 10, a traditional project with a .csproj file was still required to create a C# application.

With the arrival of .NET 10, a new file-based application model was introduced, allowing the creation of a complete application using only a single file with the .cs extension, without the need for a separate project file.

Let’s look at an example where we need to create an application that calls an external API and returns user data. In this case, we could do the following:

1. Create a file with the .cs extension called GetUserData.cs.
2. Open the file with your favorite code editor and insert the following code:

using System.Net.Http;
using System.Threading.Tasks;

var url = "https://jsonplaceholder.typicode.com/users/1";

using var http = new HttpClient();

var response = await http.GetAsync(url);

response.EnsureSuccessStatusCode();

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

Console.WriteLine("API Response:");
Console.WriteLine(content);

This code makes a call to the JSON Placeholder API to return some sample data.

3. Open a terminal where the file is located and run the following command:

dotnet run GetUserData.cs

The result of the request is then displayed in the console:

In this example, we only display the data in the console, but imagine all the possibilities! With just a single .cs file, we can quickly create proofs of concept (POCs), automate small routines or even perform simple data update tasks.

Another important point to highlight about file-based applications is that they support SDK and NuGet package references through the #sdk and #package directives. Simply add them to the beginning of the file. Consider the example below:

#:sdk Microsoft.NET.Sdk.Web
#:package Newtonsoft.Json@13.0.3

using Newtonsoft.Json;

var app = WebApplication.Create();

app.MapGet("/serialize", () =>
{
    var user = new { Id = 1, Name = "Alice" };
    return JsonConvert.SerializeObject(user, Formatting.Indented);
});

app.Run();
return;

Here, we have another file called SerializeApp.cs which contains simple code to return serialized data. It uses the Microsoft.NET.Sdk.Web SDK and the Newtonsoft.Json@13.0.3 package. Note that we didn’t install anything, we only used the directives. So, we can run the application with the command dotnet run SerializeApp.cs, make a request to http://localhost:5000/serialize and see that it is 100% functional:

2. Extension Members

C# 14 is the latest version of C#, released alongside .NET 10, and it brought several improvements to the language, such as extension properties. Extension properties extend the concept of extension methods to add properties to types you don’t control, without needing to create wrappers or artificial inheritance. Consider the example below:

public static class EnumerableExtensions
{
    extension<T>(IEnumerable<T> source)
    {
        public bool IsEmpty => source.Any() == false;

        public IEnumerable<T> Where(Func<T, bool> predicate)
        {
            if (predicate is null)
                throw new ArgumentNullException(nameof(predicate));

            return Iterator();

            IEnumerable<T> Iterator()
            {
                foreach (var item in source)
                {
                    if (predicate(item))
                        yield return item;
                }
            }
        }

        public static IEnumerable<T> Identity => Enumerable.Empty<T>();

        public static IEnumerable<T> operator +(IEnumerable<T> first, IEnumerable<T> second) =>
            first.Concat(second);
    }
}

1. extension<T>(IEnumerable<T> source)

This block is the new extension scope. Here, source is treated as the receiving object, similar to this in classic extension examples. This means that any property or method defined within this block is perceived as part of IEnumerable<T> itself.

2. Extension property: IsEmpty

IsEmpty is declared as an instance property attached to IEnumerable<T>, where source is the collection being extended.

The property returns true when the sequence has no elements, equivalent to bool empty = !items.Any();, only now exposed as a property instead of a method.

Example of use:

var items = new[] { 1, 2, 3 };

// the property is used normally, as a member of the instance
bool empty = items.IsEmpty; 

3. Custom Extension Method: Where

public IEnumerable<T> Where(Func<T, bool> predicate)
{
...
}

This method conceptually overrides the traditional Enumerable Where(), demonstrating that methods can also be declared as extension members within the new block.

4. Static Extension Property: Identity

public static IEnumerable<T> Identity => Enumerable.Empty<T>();

Now it’s possible to create static properties within the extension scope. The Identity property always returns an empty string of the corresponding type.

Example of use:

var empty = EnumerableExtensions.Identity;

Note that static properties still need to be accessed by the type that declares the extension; they don’t become direct members of the target type.

5. Extension Operator: operator +

public static IEnumerable<T> operator +(IEnumerable<T> first, IEnumerable<T> second) =>

first.Concat(second);

This is one of the most interesting new features: operators can be defined as extensions, even when the original type doesn’t support them. This allows you to write operations like this:

var merged = new[] { 1, 2 } + new[] { 3, 4 }; // Result: {1,2,3,4}

3. The Field Keyword

The field keyword allows you to write the code for a property without having to manually create the field that stores its value. The compiler creates this field automatically, and field serves as a reference to this internal value.

Before C# 14, when you wanted to prevent a string property from receiving null, for example, it was necessary to declare a private field and manually write the get and set methods using that field. With field, all of this becomes more straightforward.

How it was done before:

private int _quantity;

public int Quantity
{
    get => _quantity;
    set
    {
        if (value < 0)
            throw new ArgumentOutOfRangeException(nameof(value), "Quantity cannot be negative.");

        _quantity = value;
    }
}

And now, using field:

public int Quantity
{
    get;
    set => field = value >= 0
        ? value
        : throw new ArgumentOutOfRangeException(nameof(value), "Quantity cannot be negative.");
}

You use it exactly like any normal property.

Setting a valid value:

var item = new Product();

item.Quantity = 10; // OK

Setting an invalid value:

item.Quantity = -5; // throws ArgumentOutOfRangeException

4. Assignment Using Null-Conditional

Starting with C# 14, you can assign values using the null-conditional operator ?:

order?.City = Normalize(city);

Before .NET 10, to perform a null check with assignment, you needed to do this:

if (order != null)
{
    order.City = Normalize(city);
}

//or

order = order is null 
    ? null 
    : (order.City = Normalize(city), order);

5. Minimal API Built-in Validation

In .NET 10, Minimal APIs have built-in validation, eliminating the need for external libraries or manual if blocks to validate DTOs.

In integrated validation, the model sent by the client is automatically validated as soon as it reaches the endpoint, using validation attributes from the System.ComponentModel.DataAnnotations namespace. If there are errors in the process, .NET automatically returns 400 Bad Request with details of the problem.

To implement this, simply do the following:

Program class

using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddValidation();

var app = builder.Build();

app.MapPost("/users",
    (CreateUserRequest user) =>
        TypedResults.Created($"/users/{user.Username}", user)
);

app.Run();

Data Transfer Object (DTO)

public class CreateUserRequest
{
    [Required]
    [MinLength(3)]
    public string Username { get; set; }

    [Required]
    [EmailAddress]
    public string Email { get; set; }

    [Range(1, 120)]
    public int Age { get; set; }
}

Note that to implement the new integrated validation, we use the extension method builder.Services.AddValidation();. So if we execute the route POST - /users with the following body:

{
    "username": "",
    "email": "wrong-email",
    "age": -1
}

We will receive the response below:

{
    "title": "One or more validation errors occurred.",
    "errors": {
        "Username": [
            "The Username field is required."
        ],
        "Email": [
            "The Email field is not a valid e-mail address."
        ],
        "Age": [
            "The field Age must be between 1 and 120."
        ]
    }
}

You can also disable built-in validation on endpoints using the .DisableValidation(); extension method:

app.MapPost("/users",
    (CreateUserRequest user) =>
        TypedResults.Created($"/users/{user.Username}", user)
).DisableValidation();

6. New Methods for Extending EF Core 10

.NET 10 brought some improvements to Entity Framework Core 10. Among them are the new extension methods, which always help to shorten the path. Let’s check out some of them.

1. LeftJoin() and RightJoin()

It is now possible to directly use .LeftJoin(...) and .RightJoin(...) in LINQ queries with EF, instead of having to use the old pattern with GroupJoin + DefaultIfEmpty(). EF Core provider translates LEFT JOIN / RIGHT JOIN in SQL.

The examples below demonstrate how to use both methods:

LeftJoin

var req = new CreateUserRequest
        {
            Username = "john",
            Email = "john@email.com",
            Age = 22,
        };

        var requested = new[] { req };

        var result = requested
            .LeftJoin(
                db.Users,
                req => req.Email,
                user => user.Email,
                (req, user) => new { Requested = req, ExistingUser = user }
            )
            .ToList();

        return Results.Ok(result);

Even if there is no user in the database, the item on the left (CreateUserRequest) always appears.

RightJoin

var requests = new List<CreateUserRequest>
        {
            new()
            {
                Username = "bob",
                Email = "bob@mail.com",
                Age = 22,
            },
        };

        var result = requests
            .RightJoin(
                db.Users,
                req => req.Email,
                user => user.Email,
                (req, user) => new { Request = req, User = user }
            )
            .ToList();

All database users are located on the “right” side. Even if there is no corresponding request, the user appears.

7. ExecuteUpdate and ExecuteUpdateAsync for JSON Columns

EF Core 10 offers full support for updating JSON data (when the database supports it, SQL Server 2025, Azure SQL for example). This allows you to map complex properties to JSON columns.

Thus, it’s possible to use ExecuteUpdate and ExecuteUpdateAsync to directly update properties within the JSON, without needing to load the entire entity into memory. This brings an advantage when storing semi-structured data within JSON columns. The example below demonstrates how to use this new feature:

await db
            .Users.Where(u => u.Email == request.Email)
            .ExecuteUpdateAsync(setters =>
                setters
                    .SetProperty(u => u.Username, request.Username)
                    .SetProperty(u => u.Age, request.Age)
            ); //Updating the property directly

8. Improvements to Mapping Complex Types, Structs and Owned Types

EF Core 10 expands support for complex types. Now it’s possible to map composite (complex) types that don’t have their own identity, assigning complex properties:

public class UserProfile 
{
    public string Bio { get; set; }
}

public class User
{
    public int Id { get; set;}
    public string Username { get; set; }
    public string Email { get; set; }
    public int Age { get; set; }
    public UserProfile Profile { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
        modelBuilder.Entity<User>().ComplexProperty(u => u.Profile);
}

var complexUser = new User
        {
            Username = user.Username,
            Email = user.Email,
            Age = user.Age,
            Profile = new UserProfile { Bio = $"Account for {user.Username}" },
        };

        db.Add(user);
        await db.SaveChangesAsync();

Note that we informed EF that the User entity has a complex property (Profile) through the extension method: .ComplexProperty(u => u.Profile);.

9. Named Query Filters

It is now possible to define multiple global filters (query filters) for an entity, each with its own name, and then enable or disable specific filters in queries. This allows you to have several different logical filters and control which one to apply to each query:

modelBuilder.Entity<User>().HasQueryFilter("MinAgeFilter", u => u.Age >= 18);

modelBuilder
            .Entity<User>()
            .HasQueryFilter("EmailDomainFilter", u => u.Email.EndsWith("@company.com"));

Ignoring filters:

// keeps the age filter, ignoring the email domain filter
var adults = db.Users.IgnoreQueryFilters(["EmailDomainFilter"]).ToList();

Conclusion

.NET 10 brought several improvements to ASP.NET Core, making features like EF Core even more versatile. In addition, one of the most anticipated new features was file-based apps, which allow you to run C# code using only a .cs file.

In this post, we covered the main points with practical examples for everyday use. I hope these new features help you implement simpler, more modern and efficient solutions in your projects.

Let’s say, for example, that you’ve been happily building ASP.NET Core applications using the Progress Telerik Visual Studio extensions to generate the start point for your projects. All is going well until you start to build a new application, confident that you know what you’re doing and how all of this stuff works … except, this time, when you start your application, it doesn’t actually work.

If the symptoms are that images aren’t displayed or stylesheets aren’t applied or video doesn’t play, or web service requests aren’t issued, then the problem may be a Content Security Policy (CSP).

To confirm if the problem is CSP, just press F12 in your browser, check the messages in the console window and see if you find a message like this one (the asterisks represent message content that will vary, depending on the problem):

Refused to load the https:// because it violates the following Content Security Policy directive.

If you’re using the default Telerik template as a starting point for your project, the culprit is a <meta> tag that’s automatically included in the project’s Layout.cshtml file (the file is the default base for all your views). Here’s the current version of that tag, formatted to make it easier to read:

<meta http-equiv="Content-Security-Policy"
  content="default-src 'self';
  
    img-src 'self'
      data:;

    script-src 'self'
      https://kendo.cdn.telerik.com
      https://code.jquery.com/
      https://cdn.kendostatic.com
      https://unpkg.com
      https://cdn.jsdelivr.net 'nonce-Telerik-Examples';
 
    style-src 'self'
      https://kendo.cdn.telerik.com
      https://unpkg.com
      https://cdn.jsdelivr.net;

    font-src 'self'  
      https://unpkg.com;

    connect-src 'self'
      ws:
      http:;" />

You could make your error go away by just deleting the tag, but that’s probably a mistake. This Content Security Policy (CSP) <meta> tag helps protect against code injection and cross-site-scripting (XSS) attacks.

Fundamentally, this CSP helps protect your project by limiting the sources where your page can retrieve scripts, stylesheets and images (or any other resource) to the sources listed in the <meta> tag.

However, it also means that if you’re downloading resources from something that Progress Telerik can’t consider (your organization’s stylesheet site, for example), well, then your application won’t work.

To fix it, you first need to know how to read the CSP added in the <meta> tag.

Reading the Default <meta> Tag

A CSP like the one added in the <meta> tag is divided into multiple sections (called directives), separated by semicolons. A directive begins with the directive name and is followed by series of space-delimited sources.

The key directive is default-src which, unless overridden in other directives, specifies where the page can download resources from (in CSP, default-src is considered the fallback when other directives aren’t provided). Here’s the default-src directive from the <meta> tag, listing one source—the keyword 'self':

default-src 'self';

The 'self' keyword limits downloads to resources from the same domain that your page was downloaded from. The other directives override that default list for specific types of content to add additional sources.

The img-src directive, for example, lets you specify sites that you want to enable for downloading images. The <meta> tag in your Telerik-generated project uses 'self' to download images from the same domain as the page but also adds any image using a URI that begins with data. (The data: URI lets you embed base64 encoded files directly into your page rather than having to download them separately.)

img-src 'self'
  data:;

The other directives specify sources for:

• Downloading JavaScript files: Your page’s domain, the Telerik site, plus some public and content delivery network sites like unpkg.com (script-src). The nonce keyword causes the server to generate a one-time random key that is included in the download and checked by the browser to verify that the script is coming from the requested server:

script-src 'self'
  https://kendo.cdn.telerik.com
  …
  https://cdn.jsdelivr.net 'nonce-Telerik-Examples';

• Downloading stylesheets: Same kind of sites as with script files (style-src)
• Downloading fonts: Both your page’s domain and unpkg.com (font-src)
• Calling WebSockets and web services: Requests to your page’s domain plus all WebSocket requests and HTTP/HTTPS requests (connect-src)

The result of this CPS is that every source not in those lists is blocked—that includes stylesheets, images, audio/video files and so on that aren’t coming from your application’s domain. Getting your application running, then, comes down to extending those lists to include those other sources.

Side note: When reading or modifying a CSP, allowing HTTP also allows HTTPS (and vice versa). An img-src directive that includes http:phvis.com, for example, would still allow this image tag to download its image over HTTPS:

<img src=https://phvis.com/SomePictureOnPetersSite.jpg />

Tailoring the Telerik <meta> Tag

Typically, you’ll run into a CSP problem because you’re accessing a resource from somewhere other than your page’s domain (for example, some shared image/stylesheet site or a video from a streaming site). When you do run into this problem, you have two ways of fixing it:

• Extend the default-src directive to include the other site. This makes sense if you’re downloading multiple resources from that site and have confidence in its security (a central corporate site with resources to be used on all of your organization’s pages).
• Extend the directive for the specific resource that’s being blocked (e.g., adding the URL where your organization’s stylesheets/images are kept).

That last option may include adding a new directive if the resource isn’t one of the types already listed in the CSP (e.g., if the blocked resource is a video or audio file on another site). For a video or audio file, for example, you need to add the media-src directive to the CSP (see the directives list for other types of resources).

On the other hand, if your organization requires something more restrictive (the “Block All, Allow Some” strategy) or you’d prefer something more flexible (the “Allow All, Control Some” strategy), you may want to swap in a different CSP altogether.

Defining a Content Security Policy

If you want to go beyond setting CSP pages for individual pages, you can configure your web server to return a CSP as one of the response headers for any request. If you do, you’ll also have more options than are available using the <meta> tag. I’ll continue with the <meta> tag, however.

The starting point for your CSP is a policy that has no content: A policy that specifies nothing allows everything. Continuing to use the <meta> tag as my example, a policy that allows everything would look like this:

<meta http-equiv="Content-Security-Policy" />

Or, more explicitly:

<meta http-equiv="Content-Security-Policy" />
  content="" />

Building from that, you can implement one of three strategies: “Allow All, Control Some,” “Block All, Allow Some” or “Allow Some, Control Some.”

Allow All, Control Some

Implementing an “Allow All” strategy begins with omitting the default-src directive which provides the fallback for any omitted directive. Without a default-src, any directive you don’t provide allows everything.

Starting from there, you control just the resources you’re interested in by including directives for those resources. This example only blocks scripts (they must come from the page’s domain or my site) while allowing every other kind of resource:

<meta http-equiv="Content-Security-Policy"
  content="script-src 'self'
    http://phvis.com" />

This strategy makes sense when you feel there are only a small number of resources you need to control. This is the riskiest strategy (have you controlled all the right resources?) but will have the least impact on your applications.

Block All, Allow Some

Another strategy is to block everything and then allow specific resources. With this strategy, your starting point is to provide a CSP with a default-src with no value—that will block all resources:

<meta http-equiv="Content-Security-Policy"
  content="default-src;" />

If you want to be more explicit, you can use 'none' to make it clear that you’re blocking everything:

<meta http-equiv="Content-Security-Policy"
  content="default-src 'none';" />

You can now selectively allow some resources to be downloaded. This example lets in images from the page’s domain and my site but still blocks stylesheets, WebSocket access, web service requests and everything else not mentioned in this CSP:

<meta http-equiv="Content-Security-Policy"
  content="default-src 'none';"
  img-src  'self'
    http://phvis.com" />

This is probably the safest strategy but will have the biggest impact on your applications (to be more exact: more applications will stop working). It will also lead to the longest CSP list and maintenance effort as you’ll keep having to add more directives as your sites access a wider variety of resources from a longer list of sources.

Allow Some, Control Some

The third strategy is to use default-src to specify any common source for all the resources you will allow (typically that’s just 'self'—your page’s domain). You then add directives for specific resources that require something more. This is the strategy that Telerik has used in its CSP.

As you add those other directives, remember that those new directives don’t extend default-src but, instead, override it. Essentially, that means that most/all of your additional directives will begin with whatever you have in the default-src directive.

This example allows any resource from my page’s domain and my site to be downloaded, except for images. For images, this policy allows images from the page’s domain, my site and the Telerik site:

<meta http-equiv="Content-Security-Policy"
  content="default-src 'self'
    http://phvis.com;

    img-src 'self'
      http://phvis.com
      http://Telerik.com" />

This strategy is, essentially, a trade-off between the other two: By providing a fallback in default-src that allows resources from your “safe” sites, it reduces the number of directives that you’ll have to add. You’ll now only need to add directives where you need to specify a different or longer set of resources than your default list of “safe” sites.

So: Yes, CSP can be annoying. But CSP helps protect you from being attacked. And, considering the embarrassment that comes from finding your site defaced or hacked, it’s probably worth implementing the strategy that saves you from explaining how that happened.

Learn more about Progress Telerik UI for ASP.NET Core and try it yourself, free for 30 days.

In a technology-driven and highly consumer-oriented world, using classic approaches like monoliths isn’t always the best choice. In these cases, microservices stand out as a flexible and viable option for creating and deploying independent services.

In this post, we’ll explore how microservices fit together architecturally, their advantages and disadvantages, and how to build a backend microservice in ASP.NET Core to manage customer feedback.

️ Microservices in Architecture

If you’ve worked or even studied programming in recent years, you’ve probably seen the word “microservice” somewhere. This is because microservices have never been so popular. Large technology companies have made this term almost synonymous with scalability, resilience and innovation.

However, it’s important to understand that microservices are not a ready-made formula for any project. They are, first and foremost, an architectural choice, and like any architectural decision, they should be based on the system’s needs, not simply on the desire to adopt the most popular approach.

In practice, microservices present themselves as an alternative to the monolithic model. In a monolith, all business logic coexists within a single application. However, in microservices, the application is divided into smaller, independent services, each responsible for a specific context.

The choice of microservices directly impacts the architecture and has proven to be an excellent choice in many scenarios. Let’s consider a scenario in which a microservice would be a recommended approach.

Imagine a scenario where we have three main services: Order, Payment and Feedback. In an ecommerce business, for example, Order and Payment are fundamental to the business’s operation, while Feedback, although important, plays a more secondary role. Now, consider the following situation: a bug occurs in the Feedback service. How would this impact the application if it were structured as a monolith vs. as a set of microservices?

In the monolithic model, all services are grouped in a single system, sharing the same codebase and running in the same process. This means that, even if the problem is limited to the Feedback functionality alone, there is a risk of compromising the stability of the entire system.

Furthermore, fixing Function requires a complete redeployment, including Order and Payment, even if these services were not affected. In other words, a small detail in a secondary area can become a bottleneck for the entire business, as demonstrated in the image below:

In the microservices model, each part of the system is isolated in its own process, with independent deployment, scalability and database. In this scenario, a bug in Feedback only impacts that specific service, and since it’s not essential to the purchasing process, it can be offline for a while without major complications.

Meanwhile, Order and Payment continue to function normally, without compromising the purchasing flow or payment processing, which are the heart of the business. Fixes are also faster, as only the problematic service needs to be updated.

It’s important to emphasize that, in this hypothetical scenario, we’re considering a worst-case scenario without going into too much detail. In this sense, while in a monolith, a seemingly harmless bug can cause instability throughout the system, the impact in microservices is much more localized and controlled. This is why, in scenarios where certain services are business-critical, such as Order and Payment, the microservices architecture offers significant advantages in terms of resilience and operational continuity.

Disadvantages of Microservices

While they offer benefits such as scalability, resilience and separation of responsibilities, microservices also have disadvantages that must be considered.

One of the main ones is architectural complexity. Dividing a system into dozens or hundreds of independent services requires significantly more orchestration, monitoring, deployment and communication between components. Furthermore, network traffic increases significantly, as calls that were previously internal to a monolithic process are now distributed among different services, potentially becoming a long-term risk.

Another challenge faced when choosing to use microservices is related to data management and transactional consistency. Each microservice tends to have its own database, which makes it difficult to maintain consistency between them and often requires the adoption of more sophisticated strategies, such as sagas or event sourcing. This complexity increases the team’s learning curve, demands greater maturity in DevOps practices and can increase infrastructure and operational costs.

Therefore, for organizations that do not have a solid foundation in these aspects, adopting microservices can result in a more fragile and expensive system than a well-structured monolith.

️ Building a Microservice

Now that we understand the software architecture aspects of microservices, let’s build a microservice with ASP.NET Core that uses SQL Server as a database and runs it in a Docker container.

First, let’s think about domain design. We need to clearly define the microservice’s responsibilities. It should solve a specific problem within the larger context of the system, without accumulating functions that don’t belong there. This clear boundary is what prevents a microservice from becoming a “mini-monolith.”

In this sense, the microservice we’re going to create will be responsible for managing customer feedback. It should receive basic customer data such as the customer’s name, the product or service they’re referring to, their rating (using a scale of 1-5, where 1 is very bad and 5 is very good), and an optional description. It should then insert this data into a database. Furthermore, it should make the entered data available for future evaluation.

From a design perspective, this microservice refers to a simple data-driven CRUD, where modeling and implementation are guided by the data and the database. CRUD (Create, Read, Update, Delete) refers to the fact that the microservice exposes simple endpoints that allow creating, querying, updating and deleting records, as shown in the image below.

Creating the Project and Downloading the Dependencies

You can access the complete application code in this GitHub repository: Customer Insights Source Code.

To create the project and solution, you can use the .NET commands below:

dotnet new sln -n CustomerInsights

dotnet new webapi -n CustomerInsights

dotnet sln CustomerInsights.sln add CustomerInsights/CustomerInsights.csproj

Then run the following commands to add the NuGet packages to the project:

cd CustomerInsights

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

dotnet add package Microsoft.EntityFrameworkCore.Tools

dotnet add package Microsoft.EntityFrameworkCore.Design

Creating the Entity Class

Now, let’s define the entity that will represent the microservice responsible for receiving, storing and providing customer feedback. In this case, we’ll have a class called Feedback.

So, within the project, create a new folder called “Entities” and add the following class to it:

namespace CustomerInsights.Entities;
public class Feedback
{
    public int Id { get; set; }
    public string CustomerName { get; private set; }
    public string Product { get; private set; }
    public int Rating { get; private set; }
    public string? Description { get; private set; }

    public Feedback() { }

    public Feedback(string customerName, string product, int rating, string? description = null)
    {
        if (string.IsNullOrWhiteSpace(customerName))
            throw new ArgumentException("Customer name is required.", nameof(customerName));

        if (string.IsNullOrWhiteSpace(product))
            throw new ArgumentException("Product or service is required.", nameof(product));

        if (rating < 1 || rating > 5) 
            throw new ArgumentOutOfRangeException(nameof(rating), "Rating must be between 1 and 5.");

        CustomerName = customerName;
        Product = product;
        Rating = rating;
        Description = description;
    }
}

Here we have a simple entity that represents customer feedback. Despite its simplicity, it follows best practices by keeping its properties private. Furthermore, creating a new record undergoes validations within the class itself, so that the domain is expressive and reveals its intent through the behavior it contains.

Creating the Data Layer

The data layer will contain the class that will communicate with the database. Since we’re using Entity Framework Core as the ORM (Object Relational Mapping), we need to set the DbContext class.

So, create a new folder called “Data” and add the following class inside it:

using CustomerInsights.Entities;
using Microsoft.EntityFrameworkCore;

namespace CustomerInsights.Data;

public class AppDbContext : DbContext
{
    public DbSet<Feedback> Feedbacks { get; set; } = null!;

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

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

        modelBuilder.Entity<Feedback>(entity =>
        {
            entity.ToTable("Feedbacks");

            entity.HasKey(f => f.Id);

            entity.Property(f => f.CustomerName)
                .IsRequired()
                .HasMaxLength(100);

            entity.Property(f => f.Product)
                .IsRequired()
                .HasMaxLength(100);

            entity.Property(f => f.Rating)
                .IsRequired();

            entity.Property(f => f.Description)
                .HasMaxLength(500);
        });
    }
}

The AppDbContext class will map the database entities, in this case, Feedback, in addition to making some properties, such as CustomerName, are mandatory when generating database migrations.

Creating the DTOs

To insert and recover data, we’ll create a DTO (Data Transfer Object) that will be received in the request. So, create a new folder called “Dtos” and within it, create the following record and class:

namespace CustomerInsights.Dtos;

public record CreateCustomerFeedbackDto(string CustomerName, string Product, int Rating, string? Description);

namespace CustomerInsights.Dtos;

public class FeedbackResponseDto
{
    public int Id { get; set; }
    public string CustomerName { get; set; } = string.Empty;
    public string Product { get; set; } = string.Empty;
    public int Rating { get; set; }
    public string? Description { get; set; }
}

Creating the Mappings

Mapping classes is necessary to avoid exposing entity classes outside the API, nor bringing in data from outside without proper treatment. So, create a new folder called “Mappings” and, inside it, add the following class:

using CustomerInsights.Dtos;
using CustomerInsights.Entities;

namespace CustomerInsights.Mappings;

public static class FeedbackMappings
{
    public static FeedbackResponseDto ToDto(this Feedback feedback)
    {
        return new FeedbackResponseDto
        {
            Id = feedback.Id,
            CustomerName = feedback.CustomerName,
            Product = feedback.Product,
            Rating = feedback.Rating,
            Description = feedback.Description
        };
    }

    public static IEnumerable<FeedbackResponseDto> ToDtoList(this IEnumerable<Feedback> feedbacks) => 
        feedbacks.Select(f => f.ToDto());

    public static Feedback ToEntity(this CreateCustomerFeedbackDto dto)
    {
        return new Feedback(
            dto.CustomerName,
            dto.Product,
            dto.Rating,
            dto.Description
        );
    }
}

Creating the Controller Class

The next step is to create a controller class to receive API calls and perform actions on the database. Create a new folder called “Controllers” and add the following controller class inside it:

using CustomerInsights.Data;
using CustomerInsights.Dtos;
using CustomerInsights.Entities;
using CustomerInsights.Mappings;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;

namespace CustomerInsights.Controllers;

[ApiController]
[Route("api/v1/[controller]")]
public class FeedbackController : ControllerBase
{
    private readonly AppDbContext _dbContext;

    public FeedbackController(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    // POST api/v1/feedback
    [HttpPost]
    [ProducesResponseType(typeof(Feedback), StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> Create([FromBody] CreateCustomerFeedbackDto feedbackDto)
    {
        try
        {
            var feedback = feedbackDto.ToEntity();

            _dbContext.Feedbacks.Add(feedback);
            await _dbContext.SaveChangesAsync();

            return CreatedAtAction(nameof(GetById), new { id = feedback.Id }, feedback);
        }
        catch (ArgumentOutOfRangeException ex)
        {
            return BadRequest(new { error = ex.Message });
        }
        catch (ArgumentException ex)
        {
            return BadRequest(new { error = ex.Message });
        }
    }

    // GET api/v1/feedback?pageNumber=1&pageSize=10
    [HttpGet]
    public async Task<IActionResult> GetAll([FromQuery] int pageNumber = 1, [FromQuery] int pageSize = 10)
    {
        var feedbacks = await _dbContext.Feedbacks
            .AsNoTracking()
            .OrderBy(f => f.Id)
            .Skip((pageNumber - 1) * pageSize)
            .Take(pageSize)
            .ToListAsync();

        return Ok(feedbacks.ToDtoList());
    }

    // GET api/v1/feedback/product/{product}?pageNumber=1&pageSize=10
    [HttpGet("product/{product}")]
    public async Task<IActionResult> GetByProduct(string product, [FromQuery] int pageNumber = 1, [FromQuery] int pageSize = 10)
    {
        var feedbacks = await _dbContext.Feedbacks
            .AsNoTracking()
            .Where(f => f.Product == product)
            .OrderBy(f => f.Id)
            .Skip((pageNumber - 1) * pageSize)
            .Take(pageSize)
            .ToListAsync();

        return Ok(feedbacks.ToDtoList());
    }

    // GET api/v1/feedback/{id}
    [HttpGet("{id}")]
    public async Task<IActionResult> GetById(int id)
    {
        var feedback = await _dbContext.Feedbacks
            .AsNoTracking()
            .FirstOrDefaultAsync(f => f.Id == id);

        if (feedback is null)
            return NotFound();

        return Ok(feedback.ToDto());
    }
}

Configuring the Program Class

Now, let’s configure the Program class, adding dependency injections and database initialization (DatabaseInit.MigrationInitialization). Add the following code to the Program class:

using CustomerInsights.Data;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();

// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

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

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

DatabaseInit.MigrationInitialization(app);

app.Run();

Then, in the appsettings.json file, add the SQL Server connection string:

"ConnectionStrings": {
    "DefaultConnection": "Server=mssql-server,1433;Initial Catalog=FeedbackDb;User ID=SA;Password=8/geTo'7l0f4;TrustServerCertificate=true"
  }

Applying Migrations

You can use the commands below to apply EF Core database migrations.

# Create the migrations
dotnet ef migrations add InitialCreate

# If you don't already have the EF Core Tools CLI installed globally
dotnet tool install --global dotnet-ef

Running the Microservice and Database in a Docker Container

Our microservice is ready to run. For that, we’ll use Docker. If you’re unfamiliar with Docker, I suggest these two posts that demonstrate how to deploy an ASP.NET Core application from scratch:

1. Deploying ASP.NET Core Applications with Docker—Part 1.
2. Deploying ASP.NET Core Applications with Docker—Part 2.

For educational purposes, we will run SQL Server in a Docker container, but in production environments, it is recommended to use cloud resources to maintain the database.

So, add the following Docker Compose file and Dockerfile to the application root:

• docker-compose.yml

version: "3.9"

services:
  customer-insights:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: customer-insights
    ports:
      - "5050:8080"
    depends_on:
      - mssql-server
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Server=mssql-server,1433;Initial Catalog=FeedbackDb;User ID=SA;Password=8/geTo'7l0f4;TrustServerCertificate=true

  mssql-server:
    image: mcr.microsoft.com/mssql/server:2022-latest
    container_name: mssql-server
    ports:
      - "1433:1433"
    environment:
      - ACCEPT_EULA=Y
      - MSSQL_SA_PASSWORD=8/geTo'7l0f4
    volumes:
      - mssqldata:/var/opt/mssql

volumes:
  mssqldata: