In this article, you'll learn how to modernize legacy applications by migrating from ASP.NET Framework to ASP.NET Core. This guide covers architectural differences, migration strategies, step-by-step implementation, and best practices for building scalable, high-performance web applications.

Table of Contents

• Prerequisites

• Understanding the Architectural Shift

• Key Challenges in Migration

• Migration Strategies

• Pre-Migration Assessment

• Step-by-Step Migration Process

• Performance and Scalability Gains

• Deployment Modernization

• Common Pitfalls

• Real-World Use Cases

• Best Practices Checklist

• When You Should NOT Migrate

• Future Enhancements

• Conclusion

Legacy systems built on the ASP.NET Framework have powered enterprise applications for over a decade. While stable and mature, these systems often struggle to meet modern requirements such as cross-platform deployment, cloud-native scalability, and high-performance workloads. As businesses evolve, the need to modernize these applications becomes unavoidable.

This is where ASP.NET Core comes in. Designed as a lightweight, modular, and high-performance Framework, ASP.NET Core enables developers to build scalable applications that run on Windows, Linux, and macOS.

In this article, we’ll explore a practical and technical approach to migrating legacy ASP.NET Framework applications to ASP.NET Core MVC. Instead of focusing on theory, the emphasis will be on architectural differences, migration strategies, and step-by-step execution.

Prerequisites

Before migrating to ASP.NET Core, developers should have a solid understanding of the MVC architecture, C#, and basic .NET development concepts. Familiarity with dependency injection, REST APIs, and Entity Framework will make the migration process significantly easier.

You should also have:

• .NET SDK installed (.NET 6 or later recommended)

• Basic knowledge of CLI commands

• Experience with NuGet package management

• Understanding of IIS or web hosting environments

• A version control system such as Git

For enterprise projects, access to staging environments and automated testing pipelines is highly recommended before beginning migration.

Understanding the Architectural Shift

Migrating to ASP.NET Core is not just a version upgrade—it’s a fundamental architectural shift.

From Monolithic to Modular

ASP.NET relies heavily on the System.Web assembly, which tightly couples components such as HTTP handling, session state, and caching. In contrast, ASP.NET Core removes this dependency and introduces a modular middleware pipeline.

Built-in Dependency Injection

Dependency Injection (DI) in ASP.NET required third-party libraries like Autofac or Ninject. ASP.NET Core includes DI natively, promoting better separation of concerns.

Unified Runtime

ASP.NET Core runs on the modern .NET ecosystem (for example, .NET 6+), which unifies previously fragmented runtimes and improves performance.

Configuration Overhaul

Configuration has moved from XML-based web.config files to flexible JSON-based systems like appsettings.json, supporting environment-specific configurations.

Key Challenges in Migration

Before diving into the process, it’s important to understand the challenges:

• Tightly coupled codebases: Legacy applications often mix business logic, UI, and data access.

• Unsupported APIs: Some APIs used in ASP.NET are not available in Core.

• Third-party dependencies: Older libraries may not support .NET Core.

• Authentication differences: Forms authentication and legacy identity systems require refactoring.

• Large monoliths: Breaking down large applications is time-consuming.

Ignoring these challenges often leads to failed or incomplete migrations.

Migration Strategies

Choosing the right migration approach is critical.

Big Bang Migration

This approach involves rewriting the entire application at once.

Pros:

• Clean architecture

• No legacy baggage

Cons:

• High risk

• Long timelines

• Requires full regression testing

This approach is rarely recommended for large systems.

Incremental Migration (Recommended)

The Strangler Fig Pattern is commonly used here. New features are built in ASP.NET Core while gradually replacing legacy components.

The Strangler Fig Pattern is named after a vine that grows around a host tree and gradually replaces it over time. In software modernization, this pattern involves building new functionality alongside the existing application and routing specific requests to the new system as components are migrated. Instead of replacing the entire application at once, teams incrementally “strangle” the legacy system until the new ASP.NET Core application fully takes over.

Benefits:

• Reduced risk

• Continuous delivery

• Easier debugging

Hybrid Approach

Run ASP.NET Framework and ASP.NET Core side by side. Certain modules (for example, APIs) can be migrated first while the UI remains unchanged.

Pros:

• Lower migration risk

• Minimal disruption

• Supports phased rollout

Cons:

• Increased operational complexity

• Additional deployment overhead

• Temporary architectural duplication

This approach is especially useful for large enterprise systems where maintaining business continuity is more important than completing the migration quickly.

Pre-Migration Assessment

A successful migration starts with proper planning.

Codebase Audit

• Identify reusable modules

• Detect tightly coupled components

• Analyze dependencies

Tooling Support

Use tools like:

• .NET Portability Analyzer

• API analyzers

These help determine compatibility with ASP.NET Core.

Define Scope

Decide what to migrate first:

• APIs

• UI (MVC Views)

• Background services

Step-by-Step Migration Process

Step 1: Upgrade Existing Application

Ensure your application is running on the latest version of ASP.NET Framework. This minimizes compatibility issues.

Step 2: Create a New ASP.NET Core MVC Project

Use the CLI:

dotnet new mvc -n ModernApp

This creates a clean project with a modern structure:

• Program.cs (entry point)

• Controllers/

• Views/

• wwwroot/

Step 3: Migrate Configuration

Replace web.config with appsettings.json.

Old (web.config):

<appSettings>
  <add key="ApiUrl" value="https://api.example.com" />
</appSettings>

New (appsettings.json):

{
  "ApiSettings": {
    "BaseUrl": "https://api.example.com"
  }
}

Access in code:

public class HomeController : Controller
{
    private readonly IConfiguration _config;

    public HomeController(IConfiguration config)
    {
        _config = config;
    }

    public IActionResult Index()
    {
        var url = _config["ApiSettings:BaseUrl"];
        return View();
    }
}

Step 4: Replace Global.asax with Middleware

ASP.NET Core uses a middleware pipeline instead of lifecycle events.

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

app.UseRouting();
app.UseAuthorization();

app.MapControllers();

app.Run();

This pipeline provides more control and flexibility compared to the old event-driven model.

Step 5: Migrate Controllers and Views

Controller logic remains similar, but return types change.

ASP.NET Framework:

public ActionResult Index()
{
    return View();
}

ASP.NET Core:

public IActionResult Index()
{
    return View();
}

Views (Razor) require minor updates, especially for tag helpers.

Step 6: Implement Dependency Injection

Replace tightly coupled services with DI.

public interface IProductService
{
    List<string> GetProducts();
}

public class ProductService : IProductService
{
    public List<string> GetProducts()
    {
        return new List<string> { "Laptop", "Phone" };
    }
}

Register service:

builder.Services.AddScoped<IProductService, ProductService>();

Use in controller:

public class ProductController : Controller
{
    private readonly IProductService _service;

    public ProductController(IProductService service)
    {
        _service = service;
    }

    public IActionResult Index()
    {
        var products = _service.GetProducts();
        return View(products);
    }
}

Step 7: Migrate Data Access Layer

Most legacy apps use Entity Framework. In ASP.NET Core, you’ll use Entity Framework Core.

DbContext Example:

public class AppDbContext : DbContext
{
    public DbSet<Product> Products { get; set; }

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

Register in Program.cs:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer("YourConnectionString"));

Step 8: Authentication and Authorization

ASP.NET Core provides flexible authentication mechanisms:

• Cookie-based authentication

• JWT tokens

• OAuth providers

Example:

builder.Services.AddAuthentication("CookieAuth")
    .AddCookie("CookieAuth", config =>
    {
        config.LoginPath = "/Account/Login";
    });

Step 9: Testing and Validation

Testing becomes critical during migration:

• Unit testing (xUnit, NUnit)

• Integration testing

• Regression testing

Ensure feature parity between old and new systems.

For example, after migrating a legacy ASP.NET Framework API to ASP.NET Core, you can validate behavior using integration tests to ensure responses match the original system.

Example: Integration Test (xUnit)

[Fact]
public async Task GetProducts_ShouldReturnSuccessStatus()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.GetAsync("/api/products");

    // Assert
    response.EnsureSuccessStatusCode();
}

You can also compare legacy and migrated endpoints side by side during transition:

• /legacy/api/products → ASP.NET Framework

• /api/products → ASP.NET Core

Then run parallel requests and validate response consistency in structure, status codes, and data integrity. This helps ensure that migration does not introduce behavioral regressions before fully decommissioning the legacy system.

Performance and Scalability Gains

ASP.NET Core introduces significant improvements:

• Kestrel Web Server: High-performance, cross-platform server

• Async-first design: Efficient request handling

• Lower memory usage

• Better throughput under load

These improvements make it ideal for microservices and cloud deployments.

Deployment Modernization

Legacy applications were traditionally tightly coupled to IIS-based hosting environments, which limited flexibility in deployment and scaling. With ASP.NET Core, applications can now be deployed using modern, portable, and automated infrastructure approaches that better support cloud-native development and continuous delivery.

Containerization

Containerization allows applications to be packaged with all their dependencies into a single, portable unit that can run consistently across different environments. With tools like Docker, ASP.NET Core applications can be deployed reliably across development, staging, and production without environment-specific configuration issues. This approach also simplifies scaling and rollback strategies in distributed systems.

FROM mcr.microsoft.com/dotnet/aspnet:6.0
COPY . /app
WORKDIR /app
ENTRYPOINT ["dotnet", "ModernApp.dll"]

CI/CD Integration

Continuous Integration and Continuous Deployment (CI/CD) pipelines automate the process of building, testing, and deploying applications. In migration scenarios, CI/CD becomes especially important because it ensures that both legacy and modernized components remain stable during incremental rollout. Platforms like GitHub Actions and Azure DevOps help teams validate changes quickly and reduce the risk of regression when transitioning from ASP.NET Framework to ASP.NET Core.

Using CI/CD also enables:

• Faster release cycles during phased migration

• Automated testing of migrated modules

• Safe rollback in case of deployment failures

This ensures automated builds, tests, and deployments.

Common Pitfalls

Underestimating Complexity

Migration is not just about converting code—it involves rethinking the entire architecture. Differences in middleware, configuration, and hosting models mean teams must redesign key components rather than simply port them.

Ignoring Dependencies

Many legacy applications rely on third-party libraries that may not support ASP.NET Core. Failing to assess compatibility early can lead to blockers, forcing last-minute rewrites or replacements.

Skipping Incremental Approach

Attempting a full “Big Bang” migration increases risk and often results in delays or failures. An incremental strategy allows teams to validate changes gradually and maintain system stability throughout the transition.

Poor Testing

Insufficient testing can introduce critical bugs into production systems. Comprehensive unit, integration, and regression testing are essential to ensure the new application matches the behavior of the legacy system.

Real-World Use Cases

Enterprise ERP Modernization

Large ERP systems built on ASP.NET often become difficult to scale and maintain due to tightly coupled architectures. Migrating these systems to ASP.NET Core allows organizations to modularize components, improve performance, and enable cloud deployment. This transition also makes it easier to introduce microservices and modern DevOps practices.

E-commerce Platform Scaling

E-commerce applications require high availability and the ability to handle traffic spikes. By moving to ASP.NET Core, businesses can take advantage of asynchronous processing, improved request handling, and container-based scaling. This ensures faster page loads, better user experience, and the ability to handle peak demand efficiently.

API-First Backend Transformation

Modern applications increasingly adopt an API-first approach, where the backend is designed as a set of independent services. ASP.NET Core simplifies building RESTful APIs with better routing, serialization, and performance. Organizations often migrate APIs first to establish a scalable backend, then gradually transition UI layers to align with the new architecture.

Best Practices Checklist

Start with a Small Module

Instead of migrating the entire application at once, begin with a low-risk module such as a reporting feature or internal API. This helps teams understand the migration process, identify challenges early, and build confidence before scaling the effort across the system.

Use Incremental Migration

An incremental approach, such as the Strangler Fig pattern, allows legacy and modern systems to coexist during the transition. This reduces downtime, minimizes risk, and ensures continuous delivery while gradually replacing legacy components with ASP.NET Core services.

Refactor for Dependency Injection Early

Dependency injection is a core principle in ASP.NET Core, and adopting it early simplifies future development. Refactoring tightly coupled components into loosely coupled services improves testability, maintainability, and overall code quality during and after migration.

Monitor Performance Continuously

Performance should be tracked throughout the migration process using logging and monitoring tools. Comparing metrics between the legacy system and the new implementation helps validate improvements and ensures that performance regressions are identified and addressed quickly.

Maintain Backward Compatibility

During migration, it is essential to ensure that existing clients and integrations continue to function correctly. Maintaining backward compatibility through versioned APIs or adapters allows a smooth transition without disrupting users or dependent systems.

When You Should NOT Migrate

Migration is not always the right decision. If a legacy application is stable, rarely updated, and meeting business requirements, a full migration may not justify the cost and engineering effort. Some enterprise systems also depend heavily on Windows-specific technologies or third-party libraries that have no ASP.NET Core equivalents.

You should avoid immediate migration when:

• Business risk outweighs modernization benefits

• The application is nearing retirement

• Critical dependencies are unsupported in .NET Core

• The team lacks resources for testing and refactoring

• Downtime or instability could severely impact operations

In such cases, maintaining the existing system while gradually modernizing specific modules may be a more practical strategy.

Future Enhancements

As organizations continue modernizing applications with ASP.NET Core, future enhancements often focus on scalability, automation, and cloud-native development practices. Migrating to ASP.NET Core creates a foundation that makes it easier to adopt newer architectural patterns and infrastructure technologies.

Microservices Adoption

After migration, many organizations gradually break large monolithic systems into microservices. This improves scalability, fault isolation, and independent deployment of application components while enabling faster development cycles.

Cloud-Native Deployment

ASP.NET Core applications are well-suited for deployment on cloud platforms such as Microsoft Azure, Amazon Web Services (AWS), and Google Cloud. Future enhancements may include auto-scaling, serverless workloads, and managed container orchestration.

Container Orchestration with Kubernetes

Containerized ASP.NET Core applications can be managed using Kubernetes for automated scaling, service discovery, and high availability. This is especially useful for enterprise-grade distributed systems.

Advanced Observability and Monitoring

Modern systems increasingly integrate observability platforms such as centralized logging, distributed tracing, and performance monitoring. Tools like Prometheus and Grafana help teams proactively detect issues and optimize performance.

API Gateway and Service Mesh Integration

As applications evolve into distributed architectures, API gateways and service meshes become valuable for traffic management, authentication, and security. This enhances communication between services while improving resilience and governance.

AI-Assisted Development and Automation

Modern .NET ecosystems increasingly integrate AI-powered coding assistants, automated testing, and intelligent CI/CD pipelines. These tools can reduce development time, improve code quality, and simplify long-term maintenance of migrated applications.

Conclusion

Migrating from ASP.NET Framework to ASP.NET Core MVC is a strategic modernization effort, not just a technical upgrade. While the process involves challenges—ranging from architectural changes to dependency issues—the long-term benefits are substantial.

By adopting an incremental approach, leveraging modern tools, and focusing on clean architecture, organizations can successfully transition to a platform built for performance, scalability, and cloud-native development.

ASP.NET Core is not just the future of .NET—it’s the foundation for building resilient, modern applications in today’s distributed world.

But we rarely talk about the downsides of microservices. In medium to large-scale systems, the number of services can grow quickly. Netflix reportedly runs over seven hundred microservices, and Uber manages more than two thousand. That kind of scale introduces a lot of moving parts, testing complexity, and debugging challenges across service boundaries. And all of this can severely impact developer experience (DX).

Recently, I came across a new framework called .NET Aspire, which dramatically simplifies local microservices development. Aspire handles service discovery, configuration management, and observability for distributed applications, giving you a complete view of your system through a built-in dashboard. This results in a much simpler, smoother local development experience compared to manually wiring up multiple services. In this guide, we'll explore how Aspire works and how it can help improve developer experience in microservices-based systems.

Prerequisites

Before we begin, ensure you have the following installed:

• .NET 8 SDK or later

• Docker Desktop

  • Aspire uses Docker to run dependencies like Redis, PostgreSQL, and so on.

  • Ensure Docker is running before starting

• Visual Studio 2022 (v17.9+) or Visual Studio Code with C# Dev Kit

• Basic understanding of:

  • C# and .NET development

  • Microservices architecture concepts

  • REST APIs and service communication

Optional but Recommended:

• Familiarity with Docker and containerization

• Experience with distributed application development

• Knowledge of observability concepts (logging, tracing, metrics)

Table of Contents

• Prerequisites

• Understanding Developer Experience in Microservices

• Introducing .NET Aspire

• How to Set Up .NET Aspire in Your Project

• Why This Matters for Developer Experience

• Framework: How to Adopt .NET Aspire Incrementally

• How to Use the .NET Aspire Dashboard

• Practical Scenarios: Solving Real-World DX Challenges with .NET Aspire

• Going Further

• Key Takeaways and When to Use .NET Aspire

• When (and When Not) to Use .NET Aspire

• Conclusion

Understanding Developer Experience in Microservices

When people talk about DX, they often think of it as tooling or ergonomics, things like good documentation, fast build times, and clean APIs. But in distributed systems, DX becomes much broader. It’s about how easily developers can set up, run, and reason about the systems they’re building.

In a monolithic application, starting your development environment might mean running a single command like dotnet run. But in a microservices-based system, you might need to start multiple APIs, databases, background workers, and queues, all with specific configuration dependencies. This extra overhead doesn’t just slow you down, it breaks your focus and adds friction to daily development.

Over time, that friction compounds.

• Onboarding new developers becomes slower.

• Debugging across service boundaries gets harder.

• Teams spend more time managing environments than writing features.

That’s why DX is so important in microservices architectures. It is not just about developer happiness, it’s about velocity, consistency, and confidence. If your local environment isn’t easy to run or reason about, every other process in your development lifecycle suffers.

This is where orchestration frameworks like .NET Aspire start to make a real difference. They handle the complexity of coordinating services, so developers can focus on building and iterating faster, the way modern software development is meant to work.

Introducing .NET Aspire

As microservice systems grow, local development environments often become a patchwork of scripts, Docker Compose files, and manual setup steps. Each developer ends up managing their own version of “how to get things running,” and small differences in configuration can lead to big inconsistencies across teams.

.NET Aspire is an orchestration framework designed to simplify this process. It provides a way to define, configure, and run your distributed applications as a single unit, directly within your .NET solution.

In practical terms, Aspire helps developers by handling three key areas automatically:

1. Service Orchestration
   Aspire can start multiple projects (APIs, workers, databases, and so on) in the correct order. It takes care of service dependencies so that, for example, your API doesn’t try to start before the database it depends on is ready.

2. Configuration Management
   Instead of juggling dozens of appsettings.json files or environment variables, Aspire provides a centralized configuration model. It shares connection strings, ports, and environment settings across services in a consistent way.

3. Observability and Insights
   Aspire includes built-in OpenTelemetry support and a dashboard that gives you real-time visibility into your running services, including their health, logs, and endpoints. This makes debugging and local monitoring much easier.

In many ways, Aspire does for services what Kubernetes does for containers, but with a sharper focus on local development and developer experience. It’s not meant to replace your production orchestration tools, it’s designed to make your everyday development smoother, faster, and less error-prone.

How to Set Up .NET Aspire in Your Project

We'll create a microservices setup and watch Aspire orchestrate it with minimal code. Make sure you're running .NET 8 or later. Aspire requires it.

Create a New Aspire Project

Start by creating a new Aspire app host using the .NET CLI:

dotnet new aspire-app -n MyCompany.AppHost

This command creates a new Aspire “host” project, the entry point that orchestrates your other microservices, APIs, and dependencies.

You’ll notice that the generated project contains a Program.cs file with an AppHostBuilder. This builder acts as the control center for your distributed system.

Add Your Microservices

You can now reference your existing projects or create new ones directly in the same solution. For example:

dotnet new webapi -n CatalogService
dotnet new webapi -n OrderService
dotnet new worker -n NotificationWorker

Then, add them to your Aspire host by editing Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

var catalog = builder.AddProject<Projects.CatalogService>("catalog");
var order = builder.AddProject<Projects.OrderService>("order")
                   .WaitFor(catalog); // ensure this starts after CatalogService
var notifications = builder.AddProject<Projects.NotificationWorker>("notifications");

builder.Build().Run();

In this example:

• AddProject registers each service with Aspire.

• .WaitFor() enforces startup dependencies (for example, OrderService depends on CatalogService).

• Aspire takes care of starting these services in the right order, sharing environment variables, and managing ports automatically.

Run All Services with One Command

Now, from your app host directory, run:

dotnet run

Aspire will:

• Start all the registered services.

• Allocate available ports.

• Inject shared configurations.

• Launch a local dashboard showing service health, endpoints, and logs.

You should see output like this:

Starting CatalogService...
Starting OrderService...
Starting NotificationWorker...
AppHost running on http://localhost:18888

And when you open the dashboard in your browser, you’ll see all your services, their statuses, and links to their APIs.

Add a Local Database (Optional)

To show how Aspire handles dependencies, let’s add a PostgreSQL container:

var db = builder.AddPostgres("postgres");
builder.AddProject<Projects.CatalogService>("catalog")
       .WithReference(db); // injects connection string automatically

Now when you run the app, Aspire will start PostgreSQL first, generate a connection string, and pass it to CatalogService. No manual setup or .env files required.

Why This Matters for Developer Experience

Before Aspire, getting your local environment running meant opening multiple terminals, waiting around for databases to start, and copying connection strings between projects. With Aspire, it's just one command. Everything starts automatically, configuration is shared across services, and you get observability built in. That's the developer experience win. Less time fighting your setup, more time actually coding.

Framework: How to Adopt .NET Aspire Incrementally

If you’re considering trying Aspire in your own team, you don’t have to migrate everything at once. In fact, the best approach is incremental adoption. Start small and expand gradually.

Here’s a simple framework you can follow:

Step 1: Start Small

Create an Aspire host and connect one or two key services.
This helps your team understand the orchestration flow before scaling up.

dotnet new aspire-app -n MyCompany.AppHost

Step 2: Add Dependencies Incrementally

As you grow, include more services and use .WaitFor() to define dependencies and startup order.

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("postgres");
builder.AddProject<Projects.CatalogService>("catalog")
       .WithReference(db);
builder.AddProject<Projects.ApiGateway>("gateway")
       .WaitFor("catalog");

builder.Build().Run();

Step 3: Integrate Observability

Leverage Aspire’s built-in OpenTelemetry integration for metrics and traces. You’ll instantly gain better insight into service interactions even without external tools.

Step 4: Share Your Setup

Commit your Aspire host to source control so every developer uses the same setup.
This ensures consistency across environments, reducing the classic “works on my machine” problem.

Note: Aspire doesn’t require a full rewrite. It works great as a starting layer while your team continues evolving your existing orchestration setup.

How to Use the .NET Aspire Dashboard

One of the standout features of .NET Aspire is its built-in dashboard, which gives you real-time visibility into your microservices while they run locally.

When you start your Aspire app host with dotnet run, it automatically spins up a local dashboard (by default at http://localhost:18888). This dashboard provides a centralized view of all your services — APIs, databases, background workers, and any connected dependencies.

Here’s what you’ll find inside:

Service Overview

The dashboard home page lists every service in your distributed application. For each one, you can see:

• Name and type (for example, cache, apiservice, webfrontend)

• Current state (Running, Starting, Stopped)

• Source

• Port and endpoint information

• Startup time and uptime

• Logs and metrics shortcuts

This immediately replaces the need to track multiple terminal windows or scroll through dozens of logs just to confirm everything started correctly.

The dashboard automatically detects unhealthy or failed services and highlights them, so you can identify startup issues early.

Navigating to Endpoints

Each service card includes quick links to its exposed endpoint, providing easy access to relevant tools and interfaces. For example, APIs may include links to Swagger UI or Scalar, databases may link to pgAdmin or similar management tools, and internal services may offer links to custom dashboards.

This setup allows users to test APIs or verify database connections directly from the dashboard without needing to remember specific ports or manually construct URLs.

Real-Time Logs

Clicking into a specific service opens a detailed view showing real-time logs streamed directly from that service.

This is especially helpful when debugging startup issues or service interactions. Instead of running dotnet run in separate terminals, you can view logs for all your services in one place, color-coded and timestamped for clarity.

Observability Built-In (OpenTelemetry)

Aspire includes OpenTelemetry by default, which means that even without additional configuration, you automatically gain access to several powerful observability features. These include distributed traces across service boundaries, metrics for performance monitoring, and correlated logs that help track requests spanning multiple services.

For teams already using tools like Grafana, Jaeger, or SigNoz, Aspire can export this telemetry data to your preferred observability platform with minimal setup.

With tracing enabled, you can follow a request as it travels from your API to your database, through background workers, and back, all from within the dashboard.

Why the Dashboard Improves Developer Experience

Without Aspire, running a local microservices environment typically requires managing multiple terminal windows, tracking ports manually, and searching through log files to diagnose failures.

Aspire consolidates these tasks into a single visual interface where developers can view all services, check dependencies, inspect logs, and monitor system health directly from the browser.

This integrated environment enables faster debugging, maintains developer focus, and simplifies work with complex systems by reducing the overhead of manual coordination.

Practical Scenarios: Solving Real-World DX Challenges with .NET Aspire

So far, we have looked at how Aspire works and what it provides out of the box. But to really understand its impact on developer experience, let’s go through a few real-world pain points that almost every team building with microservices has faced, and how Aspire helps solve them.

Starting Multiple Services in the Right Order

The Problem: In most microservices setups, service startup order matters. For instance, your API Gateway might depend on the User Service and Catalog Service, which both depend on a Database.
If you start these in the wrong order, the gateway fails to connect, and you end up restarting services manually until everything stabilizes.

How Aspire Solves It: Aspire provides a simple way to express dependencies using .WaitFor():

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("postgres");
var user = builder.AddProject<Projects.UserService>("user")
                  .WithReference(db);

var catalog = builder.AddProject<Projects.CatalogService>("catalog")
                     .WithReference(db);

var gateway = builder.AddProject<Projects.ApiGateway>("gateway")
                     .WaitFor(user)
                     .WaitFor(catalog);

builder.Build().Run();

Aspire automatically ensures that each service only starts after the services it depends on are fully ready.
No more manual sequencing or “start this one first” instructions in your README.

Port Conflicts and Configuration Drift

The Problem: Developers often encounter the dreaded “Port 5000 is already in use” or spend time editing configuration files to avoid conflicts. Over time, local setups diverge across the team, making onboarding and debugging harder.

How Aspire Solves It: Aspire dynamically manages ports and configuration at runtime. Each service gets a unique port assignment, and Aspire automatically shares connection information across services.

You can still set explicit ports when needed:

builder.AddProject<Projects.Frontend>("frontend")
       .WithHttpEndpoint(port: 5173);

This removes guesswork, keeps environments consistent, and ensures new developers can clone the repo and start everything without editing config files.

Simplifying New Developer Onboarding

The Problem: For many teams, onboarding means following a long README with dozens of setup steps, manual database migrations, and environment variable configurations. It can take hours, or even days before a new developer can run the system locally.

How Aspire Solves It: Aspire defines your entire environment in code. That means the setup process becomes as simple as cloning the repository and running one command:

dotnet run

Aspire will start all necessary services, configure dependencies, and bring up the dashboard for visibility. This transforms onboarding from a multi-hour process into something that can be completed in minutes, with far fewer setup issues.

Improving Debugging and Cross-Service Visibility

The Problem: Debugging in microservices often means jumping between logs, tracing requests across multiple services, or reproducing issues that only appear when several services run together.

How Aspire Solves It: With built-in observability and the Aspire dashboard, you can view logs across all services in one place, inspect health checks and metrics, and trace requests using OpenTelemetry. This makes it much easier to identify issues across service boundaries and speeds up debugging, especially during integration testing or local development.

Running Optional or External Services

The Problem: Sometimes you don’t need to run every service locally. For example, you might connect to a shared staging API or external dependency instead of running a local instance.

How Aspire Solves It: Aspire lets you make services optional using conditional checks:

if (Directory.Exists("../Frontend"))
{
    builder.AddProject<Projects.Frontend>("frontend");
}

This makes your setup flexible: you can run a minimal environment for development or a full environment for integration testing, all using the same configuration.

Why These Scenarios Matter

Each of these examples solves a specific friction point in the developer experience. Startup complexity, environment drift, onboarding time, and debugging difficulty.

By automating orchestration and configuration, Aspire frees developers from repetitive setup work and lets them focus on building features instead of managing infrastructure.

Going Further

Once you’re comfortable with Aspire’s basics, you can extend it beyond local orchestration to streamline other parts of your workflow.

• Integrate front-end applications
  Orchestrate React, Angular, or Node.js apps alongside your .NET services for a unified full-stack setup.

• Export telemetry data
  Send Aspire’s OpenTelemetry output to platforms like Grafana, Jaeger, or Azure Application Insights for deeper analysis.

• Use Aspire in CI/CD pipelines
  Bring up full environments for integration or smoke testing during continuous integration runs, all using your existing Aspire configuration.

• Explore community examples
  Check out the official Aspire samples and templates for advanced orchestration patterns, cloud integration, and observability setups.

Key Takeaways and When to Use .NET Aspire

As we’ve seen throughout this guide, .NET Aspire isn’t just another developer tool, it’s a framework built specifically to improve developer experience in microservices-based applications.

By orchestrating all your services in a consistent, declarative way, Aspire helps teams reduce friction, speed up setup, and make local environments more reliable and observable.

Key Takeaways

1. Developer Experience (DX) matters as your system grows.
   Microservices introduce flexibility and scalability, but they also add complexity; multiple services, ports, dependencies, and startup sequences. Without good orchestration, DX quickly degrades.

2. Aspire simplifies orchestration for local development.
   It automatically handles service startup, dependencies, configuration sharing, and observability all defined in code, right within your .NET solution.

3. The Aspire dashboard improves visibility.
   You get a centralized, real-time view of your entire system; services, logs, health, and endpoints eliminating the need for multiple terminals or manual tracking.

4. Onboarding new developers becomes faster and smoother.
   A single dotnet run command can spin up your entire development environment, reducing setup time from hours or days to minutes.

5. Built-in observability means better debugging and confidence.
   With OpenTelemetry integrated out of the box, developers can trace requests, monitor performance, and diagnose issues across services with minimal setup.

When (and When Not) to Use .NET Aspire

Use Aspire when:

Aspire makes sense if you're building .NET microservices and tired of complex local setup. It's especially valuable when your team is dealing with environment drift, slow onboarding, or startup sequences that feel like juggling. If you want one command to spin up your entire system, with observability built in from day one, Aspire is worth trying.

You might not need Aspire when:

Aspire might not be worth it if your current setup already works well. Maybe you're using Kubernetes or Docker Compose locally and everything runs smoothly. Or you're building a monolith or single service that doesn't need orchestration. Or your stack has a lot of non-.NET components that would need custom wiring. If your local development is already simple and stable, don't fix what isn't broken.

In other words:
Aspire shines in the local development and onboarding phase. Helping developers build, test, and iterate on distributed systems with minimal friction.
It’s not meant to replace production orchestrators like Kubernetes but to complement them by improving the developer’s day-to-day workflow.

Conclusion

Developer Experience is often overlooked when teams move to microservices, but it directly impacts productivity, quality, and morale. By using .NET Aspire, you can bring order, visibility, and simplicity back to your local development environment.

If you’re looking to streamline your microservices workflow, give Aspire a try. You’ll spend less time fighting your setup and more time building what actually matters; great software.

Ready to get started? Check out the official .NET Aspire documentation or clone one of the sample projects to see it in action.

If you made it to the end of this tutorial, thanks for reading! You can also connect with me on LinkedIn if you’d like to stay in touch.

gRPC is a modern, open-source RPC framework that leverages HTTP/2, Protocol Buffers, and advanced streaming capabilities to deliver exceptional performance. Unlike traditional REST APIs, gRPC offers strongly-typed contracts, automatic code generation, and built-in support for multiple programming languages. This makes it an ideal choice for microservices architectures and cross-platform development.

In this handbook, I’ll take you on a journey from absolute beginner to building production-ready gRPC services with ASP.NET Core. Whether you're migrating from REST APIs or starting fresh with gRPC, this guide will provide you with practical, hands-on experience and real-world examples.

What you'll learn:

• How to set up your first gRPC service in .NET

• How to define service contracts with Protocol Buffers

• How to implement unary, server streaming, and client streaming operations

• How to build CRUD (Create, Read, Update, Delete) operations

Let's dive in and discover how gRPC can revolutionize your API development experience!

You can find all the code in this GitHub Repository.

Table of Contents

1. gRPC Overview and How It Works with .NET

2. How to Set Up gRPC with .NET

3. How to Create the Product Model

4. How to Set Up the SQLite Database

5. How to Create Product Protocol Buffers

6. How to Implement CRUD Operations Services with gRPC

7. How to Implement gRPC CRUD Database Operations With SQLite

8. How to Test gRPC Services with Postman

9. How to Test Product Creation

10. How to Test All Product Operations

11. Conclusion

Perquisites

Before we start, make sure you have the following installed:

• .NET SDK

• Visual Studio Code

• Postman

gRPC Overview and How It Works with .NET

gRPC is a high-performance, cross-platform framework that works seamlessly with many technologies, including .NET Core.

Why choose gRPC with .NET?

There are many reasons why this is a good combination. First, of all, this combo is up to 8x faster than using REST APIs with JSON. Its strongly-typed contracts also help prevent runtime errors.

It also has built-in support for client, server, and bidirectional streaming, as well as seamless integration across different languages and platforms. Finally, it leverages HTTP/2 for multiplexing and header compression – so as you can see, these two tools are a super effective pair.

To understand in more detail why gRPC is so valuable, let's explore a common real-world scenario.

The Challenge: Microservices Communication

Imagine you're building a large e-commerce application. For better maintainability and scalability, you decide to split your monolithic application into smaller, focused services:

• Product Service – Handles product catalog, inventory, and product management

• Authentication Service – Manages user authentication, authorization, and user profiles

These services need to communicate with each other frequently. For example, before a user can add a product to their cart, the Product Service must verify with the Authentication Service that the user is logged in and has the proper permissions.

Traditional Approach: HTTP REST APIs

Traditionally, in .NET applications, we solve this inter-service communication using HttpClient to make REST API calls between services. While this works, it comes with several challenges:

• Network failures: API calls can fail unexpectedly, even when everything appears correct

• Performance bottlenecks: JSON serialization/deserialization adds overhead

• Slow response times: HTTP/1.1 limitations affect performance under high load

• Type safety: No compile-time contract validation between services

• Verbose payloads: JSON can be bulky compared to binary formats

The gRPC Solution

This is where gRPC shines. It addresses these challenges by providing some really helpful features in addition to the ones we’ve already discussed above like protocol buffers, code generation for client and server, and more.

When to Use gRPC in .NET

gRPC is particularly beneficial in certain scenarios, but it’s not a great choice in others. Here are some example use cases, as well as some to avoid:

✅ Perfect for:

• Microservices architecture: High-frequency service-to-service communication

• Real-time applications: Chat applications, live updates, gaming

• High-performance APIs: When speed and efficiency are critical

• Polyglot environments: Services written in different programming languages

• Internal APIs: Backend services that don't need browser compatibility

❌ Consider Alternatives When:

• Browser-based applications: Limited browser support (use gRPC-Web instead)

• Public APIs: REST might be more familiar to external developers

• Simple CRUD operations: Where REST's simplicity is sufficient

• Legacy system integration: When existing systems only support HTTP/1.1

gRPC vs REST: A Quick Comparison

Here’s a quick side-by-side comparison of their main features:

In this handbook, we'll build a complete Product Management system using gRPC with .NET, demonstrating how to implement efficient service-to-service communication with full CRUD operations.

How to Set Up gRPC with .NET

In this tutorial, we'll use Visual Studio Code to build our complete gRPC application. Let's start by creating a new gRPC project using the .NET CLI.

Creating Your First gRPC Project

Start by opening your terminal (you can use VS Code's integrated terminal or your system terminal) and navigate to your desired directory where you want to create the project.

Run the following command to create a new gRPC project:

dotnet new grpc -o ProductGrpc

What this command does:

• dotnet new grpc creates a new project using the gRPC template

• -o ProductGrpc specifies the output directory name for our project

Next, navigate into the project directory:

cd ProductGrpc

Then open the project in Visual Studio Code:

code .

Understanding the Project Structure

After running the command, you should see output similar to the following in your terminal, confirming that the project was created successfully:

Let's explore what the .NET gRPC template has generated for us:

ProductGrpc/
├── Protos/
│   └── greet.proto          # Protocol Buffer definition file
├── Services/
│   └── GreeterService.cs    # Sample gRPC service implementation
├── Program.cs               # Application entry point
├── ProductGrpc.csproj       # Project file
└── appsettings.json         # Configuration file

Key files:

• Protos/greet.proto: Defines the service contract using Protocol Buffers

• Services/GreeterService.cs: Contains the actual service implementation

• Program.cs: Configures and starts the gRPC server

• ProductGrpc.csproj: Contains project dependencies and build settings

Verifying the Setup

Let's make sure everything is working correctly by running the default application:

dotnet run

You should see output indicating that the gRPC server is running:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7042
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

🎉 Congratulations! You've successfully created your first gRPC application using the .NET CLI. The server is now running and ready to accept gRPC requests.

Let's move on to the next section, where we'll start building our Product Management system.

How to Create the Product Model

Now that we have our gRPC project set up, let's create our Product model. In .NET applications, models represent the data structure and business entities that our application will work with. Think of models as blueprints that define what properties our data objects should have.

Understanding Models in gRPC Applications

Models serve several important purposes:

• Data structure: They define the shape and properties of our business entities.

• Type safety: They ensure compile-time validation of our data.

• Business logic: They represent real-world objects in our application.

• Database mapping: They serve as entities for database operations.

Creating the Models Folder

Let’s organize our code by creating a dedicated folder for our models called Models in your project root directory.

Inside the Models folder, create a new file called Product.cs.

Your project structure should now look like this:

ProductGrpc/
├── Models/
│   └── Product.cs           # Our new Product model
├── Protos/
├── Services/
└── ...

Implementing the Product Model

Add the following code to your Product.cs file:

// Models/Product.cs
using System.ComponentModel.DataAnnotations;

namespace ProductGrpc.Models
{
    public class Product
    {

        public Guid Id { get; set; }
        public required string Name { get; set; }
        public required string Description { get; set; }
        public decimal Price { get; set; }

        public DateTime Created { get; set; } = DateTime.UtcNow;

        public DateTime Updated { get; set; } = DateTime.UtcNow;
        public string? Tags { get; set; }
    }
}

Modern C# features:

• required keyword: Ensures properties must be initialized when creating an object

• string?: Nullable reference type for optional properties

• Default values: Created and Updated automatically set to the current UTC

Why Use Guid for ID?

We're using Guid instead of int for our primary key for a few reasons:

• Uniqueness: Guaranteed to be unique across different systems

• Security: Harder to guess than sequential integers

• Distributed systems: No need for centralized ID generation

• Scalability: Perfect for microservices architecture

Namespace Considerations

Important Note: If you changed your project name when creating it, make sure your namespace matches your project name. For example:

• If your project is named MyProductService, use namespace MyProductService.Models

• If your project is named ProductGrpc, use namespace ProductGrpc.Models

🎉 Excellent work! You've successfully created your first business model that will serve as the foundation for our entire gRPC application.

Next Steps

Now that we have our Product model ready, let's move on to setting up SQLite as our database and configuring Entity Framework Core to handle our data persistence. This will allow us to store and retrieve our Product data efficiently.

How to Set Up the SQLite Database

To persist our product data, we need a database that can handle our CRUD (Create, Read, Update, Delete) operations efficiently. We'll use SQLite for this tutorial because it's lightweight, requires no separate server installation, and works perfectly for developing small-to-medium applications.

Installing the Required Packages

Before we create our database context, we need to install the necessary Entity Framework Core packages. Open your terminal and make sure you're in the root directory of your project, then run these commands:

dotnet add package Microsoft.EntityFrameworkCore.Design

dotnet add package Microsoft.EntityFrameworkCore.Sqlite

What these packages do:

• Microsoft.EntityFrameworkCore.Design provides design-time tools for EF Core (migrations, scaffolding)

• Microsoft.EntityFrameworkCore.SQLite is a SQLite database provider for Entity Framework Core

You should see output confirming the packages were added successfully:

info : PackageReference for 'Microsoft.EntityFrameworkCore.Design' version 'x.x.x' added to file 'ProductGrpc.csproj'.
info : PackageReference for 'Microsoft.EntityFrameworkCore.Sqlite' version 'x.x.x' added to file 'ProductGrpc.csproj'.

Creating the Database Context

Now let's create our database context, which acts as a bridge between our .NET objects and the database.

First, create a new folder called Data In your project root. Inside the Data folder, create a file called AppDbContext.cs.

Your project structure should now look like this:

ProductGrpc/
├── Data/
│   └── AppDbContext.cs      # Our new database context
├── Models/
│   └── Product.cs
├── Protos/
├── Services/
└── ...

Add the following code to your AppDbContext.cs file:

// Data/AppDbContext.cs
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Models;

namespace ProductGrpc.Data
{
    public class AppDbContext : DbContext
    {
        public AppDbContext(DbContextOptions<AppDbContext> options) : base(options)
        {
        }

        public DbSet<Product> Products { get; set; }
    }
}

Let’s understand the key components of DbContext:

• Constructor: Accepts DbContextOptions for configuration (connection string, provider, and so on)

• DbSet Products: Represents the Products table in our database

Registering the Database Context

Now we need to register our AppDbContext With the dependency injection container so our application can use it.

Open your Program.cs file and add the database configuration:

// Program.cs

using ProductGrpc.Data;
using ProductGrpc.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(opt=> 
    opt.UseSqlite("Data Source=ProductGrpc.db "));
// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();


app.Run();

Data Source=ProductGrpc.db creates a SQLite database file named ProductGrpc.db in your project directory.

Creating and Running Migrations

Now we need to create a migration to generate the database schema based on our Product model.

Start by creating the initial migration:

dotnet ef migrations add InitialCreate

This command will:

• Analyze your models and DbContext

• Generate migration files in a Migrations folder

• Create SQL commands needed to build your database schema

You should see output like this:

Build succeeded.
Done. To undo this action, use 'dotnet ef migrations remove'

Apply the migration to create the database:

dotnet ef database update

This command will:

• Execute the migration SQL commands

• Create the ProductGrpc.db file in your project directory

• Set up the Products table with all the correct columns

You should see output confirming the database was created:

Build succeeded.
Applying migration '20240101000000_InitialCreate'.
Done.

Verifying the Setup

After running the migration, you should see:

1. A new Migrations folder in your project with migration files

2. A ProductGrpc.db file in your project root (this is your SQLite database)

3. No errors in the terminal output

Your project structure should now look like this:

ProductGrpc/
├── Data/
│   └── AppDbContext.cs
├── Migrations/
│   ├── 20240101000000_InitialCreate.cs
│   └── AppDbContextModelSnapshot.cs
├── Models/
│   └── Product.cs
├── ProductGrpc.db            # Your SQLite database file
└── ...

Congratulations! You've successfully installed Entity Framework Core packages, created a database context, registered the context with dependency injection, generated and applied your first migration, and created a working SQLite database. Whew!

What's Next?

Now that our database is set up and ready, we can move on to creating our Protocol Buffer definitions (.proto files) and implementing our gRPC services for CRUD operations.

How to Create Product Protocol Buffers

Protocol Buffers (protobuf) are the heart of gRPC communication. They define the structure of your data and services in a language-neutral way, which then gets compiled into native C# code. Protocol Buffers use the efficient HTTP/2 protocol, making service-to-service communication fast and reliable.

Understanding Protocol Buffers vs REST APIs

To better understand Protocol Buffers, let's compare them to what you might already know from REST API development.

In REST API development, you typically define your API endpoints using controllers and action methods. The contract between client and server is often documented separately (like with OpenAPI/Swagger), and there's no compile-time guarantee that your documentation matches your actual implementation.

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}")]
    public async Task<ActionResult<ProductDto>> GetProduct(int id) { ... }

With gRPC, the service contract is defined first in the .proto file using the service keyword. This contract becomes the single source of truth, and both client and server code are generated from it, ensuring they're always in sync.

service ProductService {
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
}

Data Transfer and Serialization

REST APIs typically use JSON for data transfer, which is human-readable and widely supported. But JSON is text-based, which has a few negatives. First, it has larger payload sizes due to text encoding. It also comes with some runtime parsing overhead. It doesn’t have any built-in schema validation, and there’s a high potential for typos in field names

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Wireless Headphones",
  "price": 99.99
}

gRPC instead uses Protocol Buffers, which serialize data into a compact binary format. This provides significantly smaller payloads (up to 6x smaller than JSON), faster serialization/deserialization, strong typing with compile-time validation, and schema evolution without breaking changes.

Transport Protocol Differences

REST APIs run over HTTP/1.1, which has some limitations:

• One request-response cycle per connection

• Text-based headers (larger overhead)

• No built-in multiplexing

• Limited streaming capabilities

gRPC leverages HTTP/2, which offers some advantages:

• Multiplexing: Multiple requests over a single connection

• Header compression: Reduced overhead with HPACK

• Server push: The Server can initiate streams to clients

• Flow control: Better handling of slow consumers

Data Structure Definitions

In REST APIs, you define DTOs (Data Transfer Objects) as regular classes:

public class ProductDto
{
    public string Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

These DTOs exist only in your specific language and need manual synchronization across different services or languages.

In gRPC, you define Messages in the proto file:

message ProductModel {
  string id = 1;
  string name = 2;
  double price = 3;
}

These message definitions are language-agnostic and automatically generate equivalent classes in any supported programming language.

Here's a quick comparison table to summarize these differences:

Creating the Product Proto File

Navigate to the Protos folder in your project and create a new file called product.proto. Make sure the file extension is .proto.

Your project structure should look like this:

ProductGrpc/
├── Protos/
│   ├── greet.proto          # Default template file
│   └── product.proto        # Our new proto file
└── ...

Setting Up the Proto File Header

Add the following header to your product.proto file:

//  Protos/product.proto
syntax = "proto3";

option csharp_namespace = "ProductGrpc";

package product;

Here’s what’s going on:

• syntax = "proto3": Specifies that we're using Protocol Buffers version 3

• option csharp_namespace = "ProductGrpc": Sets the C# namespace for generated code

• package product: Defines the protobuf package name

Note: If you named your project differently, make sure the csharp_namespace matches your project name.

Defining the Product Service

In gRPC, services define the available operations (similar to interfaces in REST APIs). Add the following service definition:

// :Protos/product.proto
service  ProductsServiceProto {
  rpc CreateProduct(CreateProductRequest) returns (CreateProductResponse);
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
  rpc UpdateProduct(UpdateProductRequest) returns (UpdateProductResponse);
  rpc DeleteProduct(DeleteProductRequest) returns (DeleteProductResponse);
}

Service methods explained:

• rpc: Defines a remote procedure call

• CreateProduct: Method name

• (CreateProductRequest): Input message type

• returns (CreateProductResponse): Output message type

Defining Protocol Buffer Messages

Messages in gRPC are equivalent to DTOs in REST APIs. They define the structure of data being exchanged. Let's create all the messages we need:

Product Model Message:

// product.proto
message ProductModel {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string created_at = 5;
  string updated_at = 6;
  string tags = 7;
}

Create Operation Messages:

// Protos/product.proto
message CreateProductRequest {
  string name = 1;
  string description = 2;
  double price = 3;
  string tags = 4;
}

message CreateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

Read Operation Messages:

// Protos/product.proto
message GetProductRequest {
  string id = 1;
}

message GetProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

message ListProductsRequest {
  int32 page = 1;
  int32 page_size = 2;
}

message ListProductsResponse {
  bool success = 1;
  string message = 2;
  repeated ProductModel products = 3;
  int32 total_count = 4;
}

Update Operation Messages:

 // Protos/product.proto
message UpdateProductRequest {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string tags = 5;
}

message UpdateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

Delete Operation Messages:

// Protos/product.proto
message DeleteProductRequest {
  string id = 1;
}

message DeleteProductResponse {
  bool success = 1;
  string message = 2;
}

Understanding Protocol Buffer Syntax

There are a few key concepts you should understand about how protocol buffers work:

• Field Numbers: Each field has a unique number (for example, = 1, = 2) used for binary encoding

• Field Types: string, int32, double, bool are common scalar types

• repeated: Indicates an array/list (for example, repeated ProductModel products)

• Message Nesting: Messages can contain other messages (for example, ProductModel product)

Keep in mind that field numbers must be unique within a message, field numbers 1-15 use 1 byte encoding (more efficient), and you should never reuse field numbers (for backward compatibility).

Complete Product Proto File

Here's your complete product.proto file:

// Protos/product.proto
syntax = "proto3";

option csharp_namespace = "ProductGrpc";

package product;

// Product service definition
service  ProductsServiceProto {
  rpc CreateProduct(CreateProductRequest) returns (CreateProductResponse);
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
  rpc UpdateProduct(UpdateProductRequest) returns (UpdateProductResponse);
  rpc DeleteProduct(DeleteProductRequest) returns (DeleteProductResponse);
}

// Product model message
message ProductModel {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string created_at = 5;
  string updated_at = 6;
  string tags = 7;
}

// Create operation messages
message CreateProductRequest {
  string name = 1;
  string description = 2;
  double price = 3;
  string tags = 4;
}

message CreateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

// Read operation messages
message GetProductRequest {
  string id = 1;
}

message GetProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

message ListProductsRequest {
  int32 page = 1;
  int32 page_size = 2;
}

message ListProductsResponse {
  bool success = 1;
  string message = 2;
  repeated ProductModel products = 3;
  int32 total_count = 4;
}

// Update operation messages
message UpdateProductRequest {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string tags = 5;
}

message UpdateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

// Delete operation messages
message DeleteProductRequest {
  string id = 1;
}

message DeleteProductResponse {
  bool success = 1;
  string message = 2;
}

Building the Project to Generate C# Code

Now that we've defined our Protocol Buffer contract, we need to build the project to generate the corresponding C# code:

dotnet build

This command will compile your .proto files into C# classes, generate client and server code, and create strongly-typed request/response classes.

You should see output confirming the build was successful:

Restore complete (0.6s)
  ProductGrpc succeeded (9.5s) → bin\Debug\net9.0\ProductGrpc.dll

Build succeeded in 11.1s

What Gets Generated?

After building, the Protocol Buffer compiler generates several C# files (you won't see them directly, but they're available in your code):

• ProductModel: C# class representing your product data

• CreateProductRequest/Response: Request and response classes for create operations

• ProductService.ProductServiceBase: Base class for implementing your service

• ProductService.ProductServiceClient: Client class for calling the service

Congratulations! You've successfully created a comprehensive Protocol Buffer definition, defined a complete CRUD service contract, set up a strongly-typed message structure, and generated C# code from your proto file.

What's Next?

Now that we have our Protocol Buffer contract defined, we can start implementing the actual gRPC service methods. In the next section, we'll create the ProductService Class and implement each CRUD operation.

Remember: Protocol Buffers are language-agnostic, so this same .proto file could be used to generate client code in Python, Java, Go, or any other supported language.

How to Implement CRUD Operations Services with gRPC

Now that we have our database set up and Protocol Buffer contracts defined, it's time to implement the actual CRUD (Create, Read, Update, Delete) functionality. We'll create a gRPC service that brings together our database models and Protocol Buffer definitions.

Understanding the Implementation Architecture

Before we start coding, let's understand how the pieces fit together:

Protocol Buffer (.proto) → Generated C# Code → Our Service Implementation → Database

Key concepts in this code:

• Proto Service: Interface (defines what methods are available)

• Proto Messages: DTOs (define data structure)

• Service Implementation: Business logic (what happens)

• Database Context: Data persistence layer

Configuring Proto File Build

First, we need to ensure our product.proto file gets compiled into C# code during the build process.

Open your ProductGrpc.csproj file and locate the <ItemGroup> section that references proto files:

  <!-- ProductGrpc.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    <!-- Add this line to include our product.proto file -->
    <Protobuf Include="Protos\product.proto" GrpcServices="Server" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.64.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.6">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.6" />
  </ItemGroup>
</Project>

What this configuration does:

• Include="Protos\product.proto" tells .NET to process our proto file

• GrpcServices="Server" generates server-side code (service base classes)

Building the Project

Now let's build the project to generate the C# code from our proto file:

dotnet build

This command will compile your .proto files into C# classes, generate the ProductsServiceProto. ProductsServiceProtoBase class we'll inherit from, create all the request/response message classes, and validate that everything compiles correctly.

You should see output like:

Build succeeded.
    0 Warning(s)
    0 Error(s)

Creating the ProductService Class

Navigate to the Services folder and create a new file called ProductService.cs. This will contain our gRPC service implementation.

Your project structure should now look like this:

ProductGrpc/
├── Services/
│   ├── GreeterService.cs    # Default template service
│   └── ProductService.cs    # Our new product service
└── ...

Setting Up the Service Foundation

Start by creating the basic service class structure:

 // Services/ProductService.cs
using Grpc.Core;
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Models;

namespace ProductGrpc.Services
{
    public class ProductService :  ProductsServiceProto .ProductsServiceProtoBase
    {
        private readonly AppDbContext _dbContext;
        private readonly ILogger<ProductService> _logger;

        public ProductService(AppDbContext dbContext, ILogger<ProductService> logger)
        {
            _dbContext = dbContext;
            _logger = logger;
        }

        // CRUD methods will be implemented here
    }
}

Key components of this code:

• Inheritance: ProductsServiceProto .ProductsServiceProtoBase is generated from our proto file

• Dependency injection: We inject AppDbContext for database operations and ILogger for logging

• Constructor: Initializes our dependencies

Implementing Method Signatures

Now let's add all the method signatures that we defined in our proto file. These methods override the virtual methods from the base class:

 //Services/ProductService.cs
using Grpc.Core;
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Models;

namespace ProductGrpc.Services
{
    public class ProductService :  ProductsServiceProto .ProductsServiceProtoBase
    {
        private readonly AppDbContext _dbContext;
        private readonly ILogger<ProductService> _logger;

        public ProductService(AppDbContext dbContext, ILogger<ProductService> logger)
        {
            _dbContext = dbContext;
            _logger = logger;
        }

        public override async Task<CreateProductResponse> CreateProduct(
            CreateProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<GetProductResponse> GetProduct(
            GetProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<ListProductsResponse> ListProducts(
            ListProductsRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<UpdateProductResponse> UpdateProduct(
            UpdateProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<DeleteProductResponse> DeleteProduct(
            DeleteProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }
    }
}

Understanding Method Parameters

Each gRPC method receives two parameters:

1. Request parameter: Contains the data sent by the client (for example, CreateProductRequest)

2. ServerCallContext: Provides access to request metadata, cancellation tokens, and response headers

Method Signature Pattern:

public override async Task<ResponseType> MethodName(
    RequestType request, 
    ServerCallContext context)

Registering the Service

Before we implement the methods, we need to register our service with the application. Open Program.cs and add the service:

 // Program.cs
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Services; // Add this using statement

var builder = WebApplication.CreateBuilder(args);

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

// Register our database context
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite("Data Source=ProductGrpc.db"));

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGrpcService<ProductService>(); // Add this line

app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

Handling Compiler Warnings

You might see warnings like:

This async method lacks 'await' operators and will run synchronously.

This is expected since we haven't implemented the actual logic yet. These warnings will disappear once we add the implementation in the following sections.

Creating Helper Methods

Before implementing CRUD operations, let's add some helper methods for converting between our database models and Protocol Buffer messages:

:Services/ProductService.cs
// Add these helper methods to your ProductService class


 private static ProductModel MapToProductModel(Product product)
{
    return new ProductModel
    {
        Id = product.Id.ToString(),
        Name = product.Name,
        Description = product.Description,
        Price = (double)product.Price,
        CreatedAt = product.Created.ToString("yyyy-MM-ddTHH:mm:ssZ"),
        UpdatedAt = product.Updated.ToString("yyyy-MM-ddTHH:mm:ssZ"),
        Tag = product.Tags ?? string.Empty
    };
}

Excellent work! You've successfully:

• Configured proto file compilation

• Created the ProductService class structure

• Set up dependency injection

• Defined all CRUD method signatures

• Registered the service with the application

• Created helper methods for data mapping

What's Next?

Now that we have our service foundation ready, we'll implement each CRUD operation one by one:

1. CreateProduct: Add new products to the database

2. GetProduct: Retrieve a single product by ID

3. ListProducts: Get a paginated list of products

4. UpdateProduct: Modify existing products

5. DeleteProduct: Remove products from the database

In the next sections, we'll dive deep into each implementation, handling error cases, validation, and best practices.

💡 Pro Tip: The ServerCallContext parameter provides useful information like request cancellation tokens, client metadata, and response headers. We'll use these in our implementations for better error handling and logging.

Note: The override keyword is crucial – it tells C# that we're implementing the virtual methods defined in the generated base class from our proto file.

How to Implement gRPC CRUD Database Operations With SQLite

Now that we have our service foundation ready, let's implement each CRUD operation. Each method will handle database operations, error handling, and return appropriate responses using our Protocol Buffer messages.

Understanding the Implementation Pattern

Each CRUD operation follows a consistent pattern:

1. Input Validation: Validate request parameters

2. Database Operation: Perform the actual database work

3. Response Mapping: Convert database models to Protocol Buffer messages

4. Error Handling: Catch and handle exceptions gracefully

Creating the CreateProduct Service

The CreateProduct method handles adding new products to our database. This is the "C" in CRUD (Create).

//Services/ProductService.cs
public override async Task<CreateProductResponse> CreateProduct(
    CreateProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Input validation
        if (string.IsNullOrWhiteSpace(request.Name))
        {
            return new CreateProductResponse
            {
                Success = false,
                Message = "Product name is required"
            };
        }

        if (request.Price <= 0)
        {
            return new CreateProductResponse
            {
                Success = false,
                Message = "Product price must be greater than zero"
            };
        }

        // Create new product entity
        var productItem = new Product
        {
            Id = Guid.NewGuid(),
            Name = request.Name,
            Description = request.Description,
            Price = Convert.ToDecimal(request.Price),
            Created = DateTime.UtcNow,
            Updated = DateTime.UtcNow,
            Tags = request.Tags
        };

        // Add to database
        _dbContext.Products.Add(productItem);
        await _dbContext.SaveChangesAsync();

        _logger.LogInformation("Product created successfully with ID: {ProductId}", productItem.Id);

        // Return success response
        return new CreateProductResponse
        {
            Success = true,
            Message = "Product created successfully",
            Product = MapToProductModel(productItem)
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error creating product");

        return new CreateProductResponse
        {
            Success = false,
            Message = $"Error creating product: {ex.Message}"
        };
    }
}

These are the important implementation details:

• Unique ID generation: Guid.NewGuid() Creates a unique identifier

• Timestamp management: DateTime.UtcNow Ensures consistent timezone handling

• Type conversion: Convert.ToDecimal() converts double to decimal for database storage

• Input validation: Checks for required fields and valid values

• Logging: Records successful operations and errors for debugging

Creating the GetProduct Service

The GetProduct method retrieves a single product by its ID. This is the "R" in CRUD (Read).

//Services/ProductService.cs
public override async Task<GetProductResponse> GetProduct(
    GetProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Validate and parse the product ID
        if (!Guid.TryParse(request.Id, out var productId))
        {
            return new GetProductResponse
            {
                Success = false,
                Message = "Invalid product ID format. Please provide a valid GUID."
            };
        }

        // Find product in database
        var product = await _dbContext.Products.FindAsync(productId);

        if (product == null)
        {
            _logger.LogWarning("Product not found with ID: {ProductId}", productId);

            return new GetProductResponse
            {
                Success = false,
                Message = "Product not found"
            };
        }

        _logger.LogInformation("Product retrieved successfully with ID: {ProductId}", productId);

        // Return success response with product data
        return new GetProductResponse
        {
            Success = true,
            Message = "Product retrieved successfully",
            Product = MapToProductModel(product)
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error retrieving product with ID: {ProductId}", request.Id);

        return new GetProductResponse
        {
            Success = false,
            Message = $"Error retrieving product: {ex.Message}"
        };
    }
}

Important implementation details:

• ID validation: Guid.TryParse() safely validates the ID format

• Database query: FindAsync() efficiently finds records by primary key

• Null checking: Handles cases where the product doesn't exist

• Detailed logging: Tracks both successful retrievals and missing products

Creating the ListProducts Service

The ListProducts method retrieves multiple products with pagination support. This is also part of the "R" in CRUD (Read).

// Services/ProductService.cs
public override async Task<ListProductsResponse> ListProducts(
    ListProductsRequest request, 
    ServerCallContext context)
{
    try
    {
        // Set default pagination values
        var pageSize = request.PageSize <= 0 ? 10 : Math.Min(request.PageSize, 100); // Max 100 items per page
        var page = request.Page <= 0 ? 1 : request.Page;

        // Calculate skip amount for pagination
        var skip = (page - 1) * pageSize;

        // Get total count for pagination metadata
        var totalCount = await _dbContext.Products.CountAsync();

        // Retrieve paginated products
        var products = await _dbContext.Products
            .OrderBy(p => p.Created) // Consistent ordering
            .Skip(skip)
            .Take(pageSize)
            .ToListAsync();

        // Create response
        var response = new ListProductsResponse
        {
            Success = true,
            Message = products.Any() 
                ? $"Retrieved {products.Count} products (Page {page} of {Math.Ceiling((double)totalCount / pageSize)})"
                : "No products found",
            TotalCount = totalCount
        };

        // Add products to response
        response.Products.AddRange(products.Select(MapToProductModel));

        _logger.LogInformation("Listed {ProductCount} products for page {Page}", products.Count, page);

        return response;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error retrieving products list");

        return new ListProductsResponse
        {
            Success = false,
            Message = $"Error retrieving products: {ex.Message}",
            TotalCount = 0
        };
    }
}

Here are the key implementation details:

• Pagination logic: Calculates skip and take values for efficient data retrieval

• Default values: Sets sensible defaults for page size and page number

• Performance optimization: Uses Skip() and Take() for database-level pagination

• Consistent ordering: OrderBy() ensures predictable results across requests

• Metadata: Returns total count for client-side pagination UI

Creating the UpdateProduct Service

The UpdateProduct method modifies existing products. This is the "U" in CRUD (Update).

// Services/ProductService.cs
public override async Task<UpdateProductResponse> UpdateProduct(
    UpdateProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Validate product ID
        if (!Guid.TryParse(request.Id, out var productId))
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Invalid product ID format. Please provide a valid GUID."
            };
        }

        // Input validation
        if (string.IsNullOrWhiteSpace(request.Name))
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Product name is required"
            };
        }

        if (request.Price <= 0)
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Product price must be greater than zero"
            };
        }

        // Find existing product
        var existingProduct = await _dbContext.Products.FindAsync(productId);

        if (existingProduct == null)
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Product not found"
            };
        }

        // Update product properties
        existingProduct.Name = request.Name;
        existingProduct.Description = request.Description;
        existingProduct.Price = Convert.ToDecimal(request.Price);
        existingProduct.Tags = request.Tags;
        existingProduct.Updated = DateTime.UtcNow; // Track when updated

        // Save changes to database
        await _dbContext.SaveChangesAsync();

        _logger.LogInformation("Product updated successfully with ID: {ProductId}", productId);

        // Return success response with updated product
        return new UpdateProductResponse
        {
            Success = true,
            Message = "Product updated successfully",
            Product = MapToProductModel(existingProduct)
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error updating product with ID: {ProductId}", request.Id);

        return new UpdateProductResponse
        {
            Success = false,
            Message = $"Error updating product: {ex.Message}"
        };
    }
}

Key details:

• Existence check: Verifies the product exists before attempting updates

• Selective updates: Only updates the fields provided in the request

• Timestamp tracking: Updates the Updated field to track modification time

• Input validation: Ensures data integrity before saving

• Atomic operation: All changes are saved together or not at all

Creating the DeleteProduct Service

The DeleteProduct method removes products from the database. This is the "D" in CRUD (Delete).

 // Services/ProductService.cs
public override async Task<DeleteProductResponse> DeleteProduct(
    DeleteProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Validate product ID
        if (!Guid.TryParse(request.Id, out var productId))
        {
            return new DeleteProductResponse
            {
                Success = false,
                Message = "Invalid product ID format. Please provide a valid GUID."
            };
        }

        // Find the product to delete
        var product = await _dbContext.Products.FindAsync(productId);

        if (product == null)
        {
            return new DeleteProductResponse
            {
                Success = false,
                Message = "Product not found"
            };
        }

        // Remove product from database
        _dbContext.Products.Remove(product);
        await _dbContext.SaveChangesAsync();

        _logger.LogInformation("Product deleted successfully with ID: {ProductId}", productId);

        // Return success response
        return new DeleteProductResponse
        {
            Success = true,
            Message = "Product deleted successfully"
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error deleting product with ID: {ProductId}", request.Id);

        return new DeleteProductResponse
        {
            Success = false,
            Message = $"Error deleting product: {ex.Message}"
        };
    }
}

Key details:

• Soft vs hard delete: This implements hard delete (permanent removal)

• Existence verification: Checks if the product exists before deletion

• Clean removal: Uses Entity Framework's Remove() method

• Confirmation: Returns a success message confirming deletion

Complete ProductService Implementation

Here's your complete ProductService.cs file with all CRUD operations:

// Services/ProductService.cs
using Grpc.Core;
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Models;

namespace ProductGrpc.Services
{
    public class ProductService : Product.ProductServiceBase
    {
        private readonly AppDbContext _dbContext;
        private readonly ILogger<ProductService> _logger;

        public ProductService(AppDbContext dbContext, ILogger<ProductService> logger)
        {
            _dbContext = dbContext;
            _logger = logger;
        }

        // Helper method to map Product entity to ProductModel message
        private static ProductModel MapToProductModel(Product product)
        {
            return new ProductModel
            {
                Id = product.Id.ToString(),
                Name = product.Name,
                Description = product.Description,
                Price = (double)product.Price,
                CreatedAt = product.Created.ToString("yyyy-MM-ddTHH:mm:ssZ"),
                UpdatedAt = product.Updated.ToString("yyyy-MM-ddTHH:mm:ssZ"),
                Tags = product.Tags ?? string.Empty
            };
        }

        // All CRUD methods go here (as implemented above)
        // CreateProduct, GetProduct, ListProducts, UpdateProduct, DeleteProduct
    }
}

Excellent work! You've successfully implemented all CRUD operations:

• Create: Add new products with validation

• Read: Retrieve single products and paginated lists

• Update: Modify existing products with validation

• Delete: Remove products safely

What's Next?

Now that our gRPC service is fully implemented, we need to test it! In the next section, we'll learn how to test our gRPC endpoints using Postman.

How to Test gRPC Services with Postman

Testing gRPC services requires different tools and approaches compared to traditional REST APIs. While REST APIs use HTTP/1.1 with JSON payloads, gRPC uses HTTP/2 with binary Protocol Buffer messages. Fortunately, Postman provides excellent support for gRPC testing, making it easy to test our service without writing client code.

Why gRPC Testing is Different

Here are the important differences between gRPC and REST API testing summarized:

Why we need the proto file:

• gRPC requires the service contract (.proto file) to understand available methods

• Protocol Buffers need schema definition for serialization/deserialization

• Postman uses the proto file to generate the correct request/response structure

Setting Up Postman for gRPC Testing

Step 1: Launch Postman

Open Postman on your machine. You should see the main dashboard similar to this:

Step 2: Create a New gRPC Request

Click on "New" in the top-left corner or use the "+" button. Then select "gRPC Request" from the available options.

You should see a modal dialog with different request types:

Click on "gRPC Request" to create a new gRPC request.

Step 3: Configure the gRPC Request Interface

After creating a gRPC request, you'll see the gRPC request interface:

These are the notable components of the gRPC interface:

• Server URL: Where your gRPC service is running

• Service definition: Where you import your .proto file

• Method selection: Choose which RPC method to call

• Message body: Request payload based on proto definitions

Importing the Proto File

Step 4: Access Service Definition

Locate the "Service definition" section in the gRPC request interface. Then click on "Import .proto file" or a similar option.

Step 5: Import Your Proto File

1. Click "Select Files" or "Import" button

2. Navigate to your project directory

3. Go to the Protos folder

4. Select product.proto file

5. Click "Open" to import

File Path Structure:

YourProject/
├── Protos/
│   ├── greet.proto
│   └── product.proto    ← Select this file
└── ...

Step 6: Configure Import Settings

When importing, you'll see options like:

Import Configuration:

• Import as: Select "API"

• API name: Choose a descriptive name (for example, "ProductGrpc API")

• Import location: Select your workspace

You want to import as an API because it creates a reusable API definition, allows multiple team members to use the same proto definitions, and provides better organization for multiple services.

Step 7: Verify Successful Import

After successful import, you should see:

1. API Collection: Your named API appears in the left sidebar under "APIs."

2. Available Methods: All RPC methods from your proto file are listed

3. Request/Response Schemas: Postman understands your message structures

Understanding the gRPC Request Interface

Once connected, you'll see a method selection dropdown with the following:

• CreateProduct

• GetProduct

• ListProducts

• UpdateProduct

• DeleteProduct

Excellent! You've successfully created a gRPC request in Postman, imported your proto file, configured the server connection, and set up the API collection for reuse.

What's Next?

Now that Postman is configured with your proto file, you're ready to test each CRUD operation:

1. CreateProduct: Test adding new products

2. GetProduct: Test retrieving single products

3. ListProducts: Test pagination and listing

4. UpdateProduct: Test modifying existing products

5. DeleteProduct: Test removing products

In the next section, we'll walk through testing each operation with sample data and expected responses.

How to Test Product Creation

Now that we have Postman configured with our proto file, it's time to test our gRPC service! We'll start by testing the CreateProduct Method to add a new product to our database.

Request Structure

Before sending your first request in Postman, select the RPC method from the dropdown. The request body’s shape comes directly from the Protocol Buffer definitions in your .proto file. Postman renders those proto messages as JSON for easier editing, but the proto types still apply: each field must match the type defined in the schema (including nested messages, enums, and repeated fields).

Step 1: Select the CreateProduct Method

Open your gRPC request in Postman and click the method dropdown (should show available methods). Select "CreateProduct" from the list.

You should see all the methods we defined in our proto file:

• CreateProduct

• GetProduct

• ListProducts

• UpdateProduct

• DeleteProduct

Step 2: Request Schema

When you select CreateProduct, Postman automatically generates the request structure based on our CreateProductRequest message from the proto file:

Proto Definition Reminder:

message CreateProductRequest {
  string name = 1;
  string description = 2;
  double price = 3;
  string tags = 4;
}

Postman JSON Representation:

{
  "name": "",
  "description": "",
  "price": 0,
  "tags": ""
}

Step 3: Prepare Test Data

Let's create our first product with meaningful test data. In the request body, enter:

{
  "name": "MacBook Pro 16-inch",
  "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
  "price": 2499.99,
  "tags": "laptop, apple, professional"
}

So what are these fields?

• name: Product title (required, string)

• description: Detailed product information (string)

• price: Product cost (double/number, must be > 0)

• tags: Comma-separated keywords (string)

Step 4: Send the Request

Click the "Invoke" button (or "Send" depending on Postman version) and wait for the response (should be very fast for local testing). Then check the response status (should show success).

Step 5: Analyze the Response

If everything works correctly, you should receive a response like this:

{
  "success": true,
  "message": "Product created successfully",
  "product": {
    "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
    "name": "MacBook Pro 16-inch",
    "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
    "price": 2499.99,
    "created_at": "2024-01-15T16:11:38Z",
    "updated_at": "2024-01-15T16:11:38Z",
    "tags": "laptop, apple, professional"
  }
}

Response fields:

• success: Boolean indicating operation success

• message: Human-readable status message

• product: The created product with generated fields

  • id: Auto-generated GUID

  • created_at/updated_at: UTC timestamps

  • Other fields: Echo of the input data

Visual Confirmation in Postman

Here's how a successful request looks in Postman:

Congratulations! You've successfully made your first gRPC request using Postman! You’ve also created a product in the database, received a properly formatted response, and verified the auto-generated ID and timestamps.

What's Next?

Now that we've successfully tested product creation, let's test the other CRUD operations:

1. GetProduct: Retrieve the product we just created

2. ListProducts: See all products with pagination

3. UpdateProduct: Modify the existing product

4. DeleteProduct: Remove the product from the database

Each operation will help us verify that our complete gRPC service is working correctly.

How to Test All Product Operations

Now that we've successfully created a product, let's test all the remaining CRUD operations to ensure our complete gRPC service works correctly.

Get All Products (ListProducts)

The ListProducts method retrieves all products from our database with pagination support. Since we've created some products, we should be able to see them in the response.

Step 1: Select ListProducts Method

Click the method dropdown in your Postman gRPC request. Then select "ListProducts" from the available methods. Notice the request structure – it includes pagination parameters.

Step 2: Configure the Request

The ListProductsRequest supports pagination parameters:

{
  "page": 1,
  "pageSize": 10
}

Here’s what’s going on with these parameters:

• page: Which page of results to retrieve (default: 1)

• pageSize: Number of products per page (default: 10, max: 100)

Step 3: Send the Request

Click "Invoke" to send the request and wait for the response containing all your products.

Step 4: Response

You should receive a response like this:

{
  "success": true,
  "message": "Retrieved 2 products (Page 1 of 1)",
  "totalCount": 2,
  "products": [
    {
      "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
      "name": "MacBook Pro 16-inch",
      "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
      "price": 2499.99,
      "created_at": "2024-01-15T16:11:38Z",
      "updated_at": "2024-01-15T16:11:38Z",
      "tags": "laptop, apple, professional"
    },
    {
      "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
      "name": "iPhone 15 Pro",
      "description": "Latest iPhone with titanium design",
      "price": 999.99,
      "created_at": "2024-01-15T16:15:22Z",
      "updated_at": "2024-01-15T16:15:22Z",
      "tags": "smartphone, apple, premium"
    }
  ]
}

Response structure:

• success: Operation status

• message: Descriptive message with pagination info

• totalCount: Total number of products in the database

• products: Array of product objects

Testing Pagination

Let’s now test some different pagination scenarios:

Get the first 5 products:

{
  "page": 1,
  "pageSize": 5
}

Get the second page:

{
  "page": 2,
  "pageSize": 5
}

Get Product By ID (GetProduct)

The GetProduct method retrieves a single product using its unique ID. Unlike REST APIs, where the ID is part of the URL path, gRPC passes the ID in the message body.

Step 1: Select the GetProduct Method

Select "GetProduct" from the method dropdown. Notice that the request structure requires an ID field.

Step 2: Prepare the Request

Copy a product ID from your previous ListProducts response:

{
  "id": "920b98d2-4feb-4705-8303-ce6e28bd3694"
}

Important notes:

• ID Format: Must be a valid GUID string

• Case Sensitivity: GUIDs are case-insensitive

• Validation: Invalid GUIDs will return an error

Step 3: Send the Request

Paste a valid product ID from your ListProducts response. Click "Invoke" to send the request.

Step 4: Analyze the Response

Successful response:

{
  "success": true,
  "message": "Product retrieved successfully",
  "product": {
    "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
    "name": "MacBook Pro 16-inch",
    "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
    "price": 2499.99,
    "created_at": "2024-01-15T16:11:38Z",
    "updated_at": "2024-01-15T16:11:38Z",
    "tags": "laptop, apple, professional"
  }
}

Update Product (UpdateProduct)

The UpdateProduct method modifies an existing product. You need to provide the product ID and the fields you want to update.

Step 1: Select the UpdateProduct Method

Select "UpdateProduct" from the method dropdown. Review the request structure which includes ID and all updatable fields.

Step 2: Prepare the Update Request

{
  "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
  "name": "MacBook Pro 16-inch (Updated)",
  "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 1TB SSD - Updated Storage",
  "price": 2799.99,
  "tags": "laptop, apple, professional, updated"
}

Update guidelines:

• ID: Must match an existing product

• All Fields: Currently required (not partial updates)

• Price: Must be greater than 0

• Name: Cannot be empty

Step 3: Send the Update Request

Make sure the ID exists (use one from your ListProducts response). Then click "Invoke" to send the update.

Step 4: Verify the Update

Successful response:

{
  "success": true,
  "message": "Product updated successfully",
  "product": {
    "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
    "name": "MacBook Pro 16-inch (Updated)",
    "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 1TB SSD - Updated Storage",
    "price": 2799.99,
    "created_at": "2024-01-15T16:11:38Z",
    "updated_at": "2024-01-15T16:25:14Z",
    "tags": "laptop, apple, professional, updated"
  }
}

Notice the changes:

• updated_at: Timestamp changed to reflect the update

• Modified Fields: All updated fields reflect new values

• created_at: Remains unchanged (original creation time)

Delete Product By ID (DeleteProduct)

The DeleteProduct method permanently removes a product from the database using its ID.

Step 1: Select DeleteProduct Method

Select "DeleteProduct" from the method dropdown. Note the simple request structure – it only requires an ID.

Step 2: Prepare the Delete Request

{
  "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890"
}

⚠️ Warning: This operation permanently deletes the product. Make sure you're using the correct ID.

Step 3: Send the Delete Request

Double-check the product ID you want to delete. Click "Invoke" to send the delete request.

Step 4: Confirm Deletion

Successful response:

{
  "success": true,
  "message": "Product deleted successfully"
}

Verification steps:

1. Try GetProduct with the same ID – it should return "Product not found"

2. Run ListProducts – the product should no longer appear in the list

3. Check totalCount – should be reduced by 1

Conclusion

Congratulations! 🎉 You've successfully completed this comprehensive journey into building gRPC services with ASP.NET Core. Throughout this handbook, you've gained hands-on experience with one of the most powerful and efficient communication frameworks available for modern distributed applications.

What You've Accomplished

Let's recap the impressive skills and knowledge you've acquired:

Foundation building

• Set up a complete gRPC project from scratch using .NET CLI

• Configured SQLite database with Entity Framework Core

• Created robust data models with proper validation

• Implemented database migrations and seeding

Learning protocol buffers

• Designed comprehensive .proto files with service definitions

• Created strongly-typed message contracts for all CRUD operations

• Understood the advantages of binary serialization over JSON

• Implemented efficient data transfer objects (DTOs)

Service implementation

• Built a complete ProductService with all CRUD operations

• Implemented proper error handling and validation

• Added comprehensive logging for debugging and monitoring

• Created efficient pagination for large datasets

• Handled data mapping between entities and Protocol Buffer messages

Testing and validation

• Configured Postman for gRPC testing

• Tested all CRUD operations with real data

• Verified data integrity and proper response formatting

Key Technical Skills Gained

gRPC Expertise:

• Understanding of the HTTP/2 protocol advantages

• Protocol Buffer schema design and evolution

• Service-to-service communication patterns

• Performance optimization techniques

🔗 You can access the code in this GitHub Repository.

Thank You!

Thank you for following along with this comprehensive tutorial. Your dedication to learning these advanced concepts will serve you well in building the next generation of distributed applications.

Happy coding, and may your services be fast, reliable, and scalable!

If you want to learn more about .NET Core, you can subscribe to my YouTube channel here.

🔗 Connect with the author:

• GitHub: @CliffTech123

• Twitter: @Clifftech_Dev

• LinkedIn: Isaiah Clifford Opoku

Imagine building robust APIs with minimal code and zero boilerplate—no more wrestling with controllers, routing, or middleware. That’s what minimal APIs allow you to do. The idea with these APIs is to streamline the development process, making it incredibly easy and efficient.

In this article, we'll dive into the world of minimal APIs in .NET 8 and guide you through creating a fully functional bookstore API. You'll learn how to get all books, retrieve a book by its ID, add new books, and even delete books. Let’s get started.

Table of Contents

• Prerequisites

• Introduction to Minimal APIs

• How to Create a Minimal API

• HTTP Methods in Controller-based and Minimal APIs

• Minimal API Project Files

• How to Create the Models

• How to Create the Database Context

• How to Create a Contract

• How to Add Services

• How to Create Exceptions

• How to Create the API Endpoints

• How to Add Seed Data to the Database

• How to Perform a Migration

• How to Test the API Endpoints

• Conclusion

Prerequisites

Before we get going, make sure you have the following prerequisites installed on your machine:

• .NET 8 SDK

• Visual Studio Code or any other code editor of your choice

• C# Dev Kit for Visual Studio Code

Alternatively, you can use Visual Studio 2022, which comes with built-in support for .NET 8. But in this article, we'll be using Visual Studio Code. It’s lightweight, easy to use, and cross-platform.

We’ll use Swagger UI to test our API. Swagger UI is a powerful tool that allows you to interact with your API directly from your browser. It provides a user-friendly interface to test your API endpoints, making it easier to test and debug your API.

When you create a new project, it will automatically install the necessary packages and configure the project to use Swagger UI. .NET 8 includes Swagger UI by default, so whether you create your application in Visual Studio or with .NET, Swagger UI will be configured for you.

Run your application, and the Swagger UI will automatically open in your browser – but since we are using VS Code, we need to click on the port number on our terminal.

You can find the source code for this project on GitHub.

Introduction to Minimal APIs

Imagine working in a codebase with numerous endpoints, making it quite large and complex. Traditionally, building an API in ASP.NET Core involves using controllers, routing, middleware, and a significant amount of boilerplate code. But there are two approaches to building an API in ASP.NET Core: the traditional way and the minimal way.

The traditional way is familiar to most developers, involving controllers and extensive infrastructure code. The minimal way, introduced in .NET 6, allows you to create APIs with minimal code and zero boilerplate. This approach simplifies the development process, enabling you to focus on writing business logic rather than dealing with infrastructure code.

Minimal APIs are lightweight, fast, and perfect for building small to medium-sized APIs. They are ideal for prototyping, building microservices, or creating simple APIs that don't require much complexity. In this handbook, we'll explore the world of minimal APIs in .NET 6 and learn how to create a fully functional bookstore API from scratch.

How to Create a Minimal API

Creating a minimal API is straightforward when using the dotnet CLI, as the default template is already a minimal API. But if you use Visual Studio, you'll need to remove the boilerplate code that comes with the project template.

Let's start by using the dotnet CLI to create a minimal API project.

dotnet new webapi  -n BookStoreApi

The dotnet new webapi command creates a new minimal API project named BookStoreApi. This project contains the necessary files and folders to get you started.

Let's explore the project structure:

• Program.cs: The entry point of the application, where the host is configured.

• bookapi-minimal.sln: The solution file that contains the project.

• bookapi-minimal.http: A file that contains sample HTTP requests to test the API.

• bookapi-minimal.csproj: The project file that contains the project configuration.

• appsettings.json: The configuration file that stores application settings.

• appsettings.Development.json : The configuration file for the development environment.

When you open the program.cs file, you'll notice that the code is minimal. The Program.cs file contains the following code:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

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

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

If you don't fully understand the code yet, don't worry—we'll cover it in detail in the upcoming sections. The key takeaway is that minimal APIs require very little code, which is one of their main advantages.

The default code sets up a simple weather forecast API that you can use to test your setup. It generates a list of weather forecasts and returns them when you make a GET request to the /weatherforecast endpoint. Also, the code includes Swagger UI to help you test the API.

Pay special attention to the app.MapGet method, which maps a route to a handler function. In this case, it maps the /weatherforecast route to a function that returns a list of weather forecasts. We'll use similar methods to create our own endpoints in the next sections.

Before we start creating our project folder structure, let's understand the HTTP methods in both Controller-based and Minimal APIs.

HTTP Methods in Controller-based and Minimal APIs

In a Controller-based approach, which is the traditional way of creating web APIs, you need to create a controller class and define methods for each HTTP method. For example:

• To create a GET method, you use the [HttpGet] attribute.

• To create a POST method, you use the [HttpPost] attribute.

• To create a PUT method, you use the [HttpPut] attribute.

• To create a DELETE method, you use the [HttpDelete] attribute.

This is how endpoints are created in a Controller-based approach.

In contrast, Minimal APIs use methods like app.MapGet, app.MapPost, app.MapPut, and app.MapDelete to create endpoints. This is the main difference between the two approaches: Controller-based APIs use attributes to define endpoints, while Minimal APIs use methods.

Now that you understand how to handle HTTP requests in both Controller-based and Minimal APIs, let's create our project folder structure.

Before we create our project folder structure, let's first run what we have. As we learned earlier, when you create a project with either Visual Studio or .NET CLI, it comes with a default WeatherForecast project which we can run and see on the UI. Let's run it to ensure everything works before we go on to create our project folder.

Run this command:

dotnet run

You should see the following output:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5228
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: D:\Devolopemnt\Dotnet\bookapi-minimal

This means the application is running and listening on http://localhost:5228. As I mentioned above, since we are using the dotnet CLI and Visual Studio Code, the application will not automatically open the browser for us. We need to do this manually.

Open your browser and navigate to http://localhost:5228/swagger/index.html to see the default response from the API.

You should see something like this:

Now the next thing for us to do is find a way to structure our project and create the necessary files and folders to get us started.

Minimal API Project Files

To organize our project, we will create a structured folder hierarchy. This will help keep our code clean and maintainable. Here is the folder structure we will use:

• AppContext: Contains the database context and related configurations.

• Configurations: Holds Entity Framework Core configurations and seed data for the database.

• Contracts: Contains Data Transfer Objects (DTOs) used in our application.

• Endpoints: Where we define and configure our minimal API endpoints.

• Exceptions: Contains custom exception classes used in the project.

• Extensions: Holds extension methods that we will use throughout the project.

• Models: Contains business logic models.

• Services: Contains service classes that implement business logic.

• Interfaces: Holds interface definitions used to map our services.

In Visual Studio Code, you can create this folder structure as follows:

- AppContext
- Configurations
- Contracts
- Endpoints
- Exceptions
- Extensions
- Models
- Services
- Interfaces

After setting up, your project folder structure should look like this:

Now that our project Structure is set up we can go ahead and start writing our code. Let's start by creating our models.

How to Create the Models

In this section, we will create models for our application. Models are the building blocks of our application, representing the data that our application will work with. For our example, we will create a model for a book.

To get started, create a folder named Models in your project directory. Inside this folder, create a file named BookModel.cs and add the following code:

// Models/BookModel.cs


namespace bookapi_minimal.Models
{
    public class BookModel
    {
        public Guid Id { get; set; }
        public string Title { get; set; }
        public string Author { get; set; }
        public string Description { get; set; }
        public string Category { get; set; }
        public string Language { get; set; }
        public int TotalPages { get; set; }
    }
}

This BookModel class defines the properties that represent the details of a book, such as its title, author, description, category, language, and total pages. Each property is designed to hold specific information about the book, making it easy to manage and manipulate book data within our application.

Now that we have created our model, let's create our database context.

How to Create the Database Context

The database context is a class that represents a session with the database. It’s responsible for interacting with the database and executing database operations. In our application, we will use Entity Framework Core to interact with our database.

Install the Required Packages

Before creating our database context, we need to install the following packages:

• Microsoft.EntityFrameworkCore.Design

• Microsoft.EntityFrameworkCore

• Microsoft.EntityFrameworkCore.SqlServer

• Microsoft.EntityFrameworkCore.Tools

• FluentValidation.DependencyInjectionExtensions

You can install these packages using the following commands:

dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package FluentValidation.DependencyInjectionExtensions

Verify Package Installation

To verify that the packages are installed, open the bookapi-minimal.csproj file in your project's root directory. You should see the installed packages listed as follows:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <RootNamespace>bookapi_minimal</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
   <PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.9.2" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.6" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

This confirms that the packages have been successfully installed.

Now let's create our database context.

In the AppContext folder, create a new file named ApplicationContext.cs and add the following code:

// AppContext/ApplicationContext.cs

using bookapi_minimal.Models;
using Microsoft.EntityFrameworkCore;

namespace bookapi_minimal.AppContext
{

    public class ApplicationContext(DbContextOptions<ApplicationContext> options) : DbContext(options)
    {

        // Default schema for the database context
        private const string DefaultSchema = "bookapi";


       // DbSet to represent the collection of books in our database
        public DbSet<BookModel> Books { get; set; }

        // Constructor to configure the database context

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

            modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationContext).Assembly);

            modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationContext).Assembly);

        }

    }
}

Let's break down the code above:

• We define a class named ApplicationContext that inherits from DbContext. The DbContext class is part of Entity Framework Core and represents a session with the database.

• The constructor accepts an instance of DbContextOptions<ApplicationContext>. This constructor is used to configure the database context options.

• We define a property named Books type DbSet<BookModel>. This property represents the collection of books in our database.

• We override the OnModelCreating method to configure the database schema and apply any configurations defined in our application.

Now that we have created our database context, let's create our extension method and register our database context in the dependency injection container.

Create an Extension Method

Before we create the extension method, let's understand what an extension method is in the context of ASP.NET Core.

An extension method is a static method that adds new functionality to an existing type without modifying the original type. In ASP.NET Core, extension methods are commonly used to extend the functionality of the IServiceCollection interface, which is used to register services in the dependency injection container.

Services are components that provide functionality to an application, such as database access, logging, and configuration. By creating an extension method for the IServiceCollection interface, you can simplify the process of registering your services in the dependency injection container.

Instead of putting everything in the Program.cs file, we will create an extension method to register our services in the dependency injection container. This will help us keep our code clean and organized.

In the Extensions folder, create a new file named ServiceExtensions.cs and add the following code:

using System.Reflection;
using bookapi_minimal.AppContext;
using FluentValidation;
using Microsoft.EntityFrameworkCore;

namespace bookapi_minimal.Extensions
{
    public static class ServiceExtensions
    {
        public static void AddApplicationServices(this IHostApplicationBuilder builder)
        {
            if (builder == null) throw new ArgumentNullException(nameof(builder));
            if (builder.Configuration == null) throw new ArgumentNullException(nameof(builder.Configuration));

            // Adding the database context
            builder.Services.AddDbContext<ApplicationContext>(configure =>
            {
                configure.UseSqlServer(builder.Configuration.GetConnectionString("sqlConnection"));
            });

            // Adding validators from the current assembly
            builder.Services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());
        }
    }
}

Let's break down the code above:

• We define a static class named ServiceExtensions that contains an extension method named AddApplicationServices. This method extends the IHostApplicationBuilder interface, which is used to configure the application's request processing pipeline.

• The AddApplicationServices method accepts an instance of IHostApplicationBuilder as a parameter. This parameter is used to access the application's configuration and services.

• We add the ApplicationContext to the dependency injection container and configure it to use SQL Server as the database provider. We retrieve the connection string from the appsettings.json file using the GetConnectionString method.

• We add validators from the current assembly using the AddValidatorsFromAssembly method. This method scans the current assembly for classes that implement the IValidator interface and registers them in the dependency injection container.

Next, we need to add the connection string to the appsettings.json file. Add the following code to your appsettings.json file:

{ 
     "ConnectionStrings": {
    "sqlConnection": "Server=localhost\\SQLEXPRESS02;Database=BookAPIMinimalAPI;Integrated Security=true;TrustServerCertificate=true;"
  }
  }

Make sure to replace your_password it with your actual SQL Server password.

Your appsettings.json file should look like this:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "sqlConnection": "Server=localhost\\SQLEXPRESS02;Database=BookAPIMinimalAPI;Integrated Security=true;TrustServerCertificate=true;"
  },
  "AllowedHosts": "*"
}

Congratulations! You have successfully created the database context, extension method, and connection string for your application. In the next section, we will create a Contract.

How to Create a Contract

Contracts are Data Transfer Objects (DTOs) that define the structure of the data exchanged between the client and the server. In our application, we will create contracts to represent the data sent and received by our API endpoints.

Here are the contracts we are going to create:

• CreateBookRequest: This represents the data sent when creating a new book.

• UpdateBookRequest: tHI Represents the data sent when updating an existing book.

• BookResponse: Represents the data returned when retrieving a book.

• ErrorResponse: Represents the error response returned when an exception occurs.

• ApiResponse: Represents the response returned by the API.

In the Contracts folder, create a new file named CreateBookRequest and add the following code:

// Contracts/CreateBookRequest.cs

namespace bookapi_minimal.Contracts
{

    public record CreateBookRequest
    { 

        public string Title { get; init; }
        public string Author { get; init; }
        public string Description { get; init; }
        public string Category { get; init; }
        public string Language { get; init; }
        public int TotalPages { get; init; }
    }
}

In the Contracts folder, create a new file named UpdateBookRequest and add the following code:

// Contracts/UpdateBookRequest.cs

namespace bookapi_minimal.Contracts
{

    public record UpdateBookRequest
    {
       public string Title { get; set; }
        public string Author { get; set; }
        public string Description { get; set; }
        public string Category { get; set; }
        public string Language { get; set; }
        public int TotalPages { get; set; }

    }
}

In the Contracts folder, create a new file named BookResponse and add the following code:

// Contracts/BookResponse.cs
namespace bookapi_minimal.Contracts
{

    public record BookResponse
    {
        public Guid Id { get; set; }
        public string Title { get; set; }
        public string Author { get; set; }
        public string Description { get; set; }
        public string Category { get; set; }
        public string Language { get; set; }
        public int TotalPages { get; set; }
    }
}

In the Contracts folder, create a new file named ErrorResponse and add the following code:

// Contracts/ErrorResponse.cs
namespace bookapi_minimal.Contracts
{

        public record ErrorResponse
    {
        public string Title { get; set; }
        public int StatusCode { get; set; }
        public string Message { get; set; }

    }

}

In the Contracts folder, create a new file named ApiResponse and add the following code:

// Contracts/ApiResponse.cs
namespace bookapi_minimal.Contracts
{

    public class ApiResponse<T>
    {
        public T Data { get; set; }
        public string Message { get; set; }

        public ApiResponse(T data, string message)
        {
            Data = data;
            Message = message;
        }
    }
}

These contracts help us define the structure of the data exchanged between the client and the server, making it easier to work with the data in our application.

In the next section, we will create services to implement the business logic of our application.

How to Add Services

Services are components that provide functionality to an application. In our application, we will create services to implement the business logic of our application. We will create services to handle CRUD operations for books, validate book data, and handle exceptions.

In ASP.NET Core, services are registered in the dependency injection container and can be injected into other components, such as controllers and endpoints, But this is a minimal API so we will inject the services directly into the endpoints.

Let's create an interface for our services. In the Interfaces folder, create a new file named IBookService.cs and add the following code:

 // Interfaces/IBookService.cs



using bookapi_minimal.Contracts;

namespace bookapi_minimal.Interfaces
{
      public interface IBookService
    {
        Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest);
        Task<BookResponse> GetBookByIdAsync(Guid id);
        Task<IEnumerable<BookResponse>> GetBooksAsync();
        Task<BookResponse> UpdateBookAsync(Guid id,  UpdateBookRequest  updateBookRequest);
        Task<bool> DeleteBookAsync(Guid id);
    }
}

Let's break down the code above: We have defined an interface named IBookService that contains methods to handle CRUD operations for books. The interface defines the following methods:

• AddBookAsync: Adds a new book to the database.

• GetBookByIdAsync: Retrieves a book by its ID.

• GetBooksAsync: Retrieves all books from the database.

• UpdateBookAsync: Updates an existing book.

We are using the Contract we created earlier in the Contracts folder. The IBookService interface defines the structure of the methods that will be implemented by the service classes. This helps us separate the interface from the implementation, making it easier to maintain and test our code.

Now that we have created the interface, let's create the service class that implements the interface.

How to Implement the Book Service

This service will implement the IBookService interface and provide the business logic for our application. In the Services folder, create a new file named BookService.cs . Your initial file should look like this:

// Services/BookService.cs

namespace bookapi_minimal.Services
{
    public class BookService
    {

    }
}

The first thing we need to do is add the interface to the BookService class. Update the BookService class to implement the IBookService interface as follows:

// Services/BookService.cs



using bookapi_minimal.Interfaces;

namespace bookapi_minimal.Services
{
    public class BookService:IBookService
    {

    }
}

When you do this, your VS Code might show an error because we have not implemented the methods in the interface. Let's go ahead and implement the methods in the BookService class.

In VS Code you can use the Ctrl + . shortcut to implement the methods in the interface. Then you will see the following code generated for you:

using bookapi_minimal.Contracts;
using bookapi_minimal.Interfaces;

namespace bookapi_minimal.Services
{
     // Service class for managing books
   public class BookService : IBookService
   {
       // Method to add a new book to the database
       public Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest)
       {
           throw new NotImplementedException();
       }

      // Method to Delete a book from the database
       public Task<bool> DeleteBookAsync(Guid id)
       {
           throw new NotImplementedException();
       }

       // Method to Get a book from the database by its ID

       public Task<BookResponse> GetBookByIdAsync(Guid id)
       {
           throw new NotImplementedException();
       }

      // Method to Get all books from the database
       public Task<IEnumerable<BookResponse>> GetBooksAsync()
       {
           throw new NotImplementedException();
       }

       // Method to Update a book in the database
       public Task<BookResponse> UpdateBookAsync(Guid id, UpdateBookRequest updateBookRequest)
       {
           throw new NotImplementedException();
       }
   }
}

Now you can see that the methods in the interface have been implemented in the BookService class. We will implement the business logic for each method in the next section.

Before we do that, let's add the necessary dependencies to the BookService class. We need to inject the ApplicationContext and ILogger dependencies into the BookService class. ApplicationContext is used to interact with the database, while ILogger is used for logging.

To inject the dependencies, update the BookService class as follows:

// Services/BookService.cs

// ...
 private readonly ApplicationContext _context; // Database context
  private readonly ILogger<BookService> _logger; // Logger for logging information and errors

//..

Since we have added the dependencies, we need to update the BookService constructor to accept the dependencies. Update the BookService constructor as follows:

// Services/BookService.cs

// ...

  // Constructor to initialize the database context and logger
 public BookService(ApplicationContext context, ILogger<BookService> logger)
 {
            _context = context;
            _logger = logger;
}

// ...

Now that we have added the dependencies and updated the constructor, we can implement the business logic for each method in the BookService class.

Let's create logic for the CREATE, READ, UPDATE, and DELETE operations in the BookService class.

How to Implement the AddBookAsync Method

As I mentioned earlier, we’ll use the AddBookAsync method to add a new book to the database. In this method, we will create a new book entity, map the data from the CreateBookRequest object to the book entity, and save the book entity to the database. We will also return the book entity as an BookResponse object.

Update the AddBookAsync method in the BookService class as follows:

// Services/BookService.cs

// ...
 /// <summary>
        /// Add a new book
        /// </summary>
        /// <param name="createBookRequest">Book request to be added</param>
        /// <returns>Details of the created book</returns>
        public async Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest)
        {
            try
            {
                var book = new BookModel
                {
                    Title = createBookRequest.Title,
                    Author = createBookRequest.Author,
                    Description = createBookRequest.Description,
                    Category = createBookRequest.Category,
                    Language = createBookRequest.Language,
                    TotalPages = createBookRequest.TotalPages
                };

                // Add the book to the database
                _context.Books.Add(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book added successfully.");

                // Return the details of the created book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error adding book: {ex.Message}");
                throw;
            }
        }
// ...

In this code, we are creating a new book entity from the CreateBookRequest object, mapping the data from the CreateBookRequest object to the book entity, saving the book entity to the database, and returning the book entity as a BookResponse object.

We are also logging information and errors using the ILogger dependency. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the AddBookAsync method, let's implement the GetBookByIdAsync method.

How to Implement the GetBookByIdAsync Method

The GetBookByIdAsync method is used to retrieve a book by its ID from the database. In this method, we will query the database for the book with the specified ID, map the book entity to a BookResponse object, and return the BookResponse object.

Update the GetBookByIdAsync method in the BookService class as follows:

// Services/BookService.cs

//... 

    /// <summary>
        /// Get a book by its ID
        /// </summary>
        /// <param name="id">ID of the book</param>
        /// <returns>Details of the book</returns>
        public async Task<BookResponse>  GetBookByIdAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Return the details of the book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving book: {ex.Message}");
                throw;
            }
        }

//...

In this code, we are querying the database for the book with the specified ID, mapping the book entity to a BookResponse object, and returning the BookResponse object. We are also logging information and errors using the ILogger dependency.

If the book with the specified ID is not found, we log a warning message and return null. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the GetBookByIdAsync method, let's implement the GetBooksAsync method.

How to Implement the GetBooksAsync Method

The GetBooksAsync method is used to retrieve all books from the database. In this method, we will query the database for all books, map each book entity to a BookResponse object, and return a list of BookResponse objects.

Update the GetBooksAsync method in the BookService class as follows:

// Services/BookService.cs

//... 


  /// <summary>
        /// Get all books
        /// </summary>
        /// <returns>List of all books</returns>
        public async Task<IEnumerable<BookResponse>> GetBooksAsync()
        {
            try
            {
                // Get all books from the database
                var books = await _context.Books.ToListAsync();

                // Return the details of all books
                return books.Select(book => new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                });
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving books: {ex.Message}");
                throw;
            }
        }
//...

Here, we are querying the database for all books, mapping each book entity to an BookResponse object, and returning a list of BookResponse objects. We are also logging information and errors using the ILogger dependency. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the GetBooksAsync method, let's implement the UpdateBookAsync method.

How to Implement the UpdateBookAsync Method

The UpdateBookAsync method is used to update an existing book in the database. In this method, we will query the database for the book with the specified ID, update the book entity with the data from the UpdateBookRequest object, save the updated book entity to the database, and return the updated book entity as a BookResponse object.

Update the UpdateBookAsync method in the BookService class as follows:

// Services/BookService.cs
 //...
 /// <summary>
        /// Update an existing book
        /// </summary>
        /// <param name="id">ID of the book to be updated</param>
        /// <param name="book">Updated book model</param>
        /// <returns>Details of the updated book</returns>
        public async Task<BookResponse> UpdateBookAsync(Guid id, UpdateBookRequest book)
        {
            try
            {
                // Find the existing book by its ID
                var existingBook = await _context.Books.FindAsync(id);
                if (existingBook == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Update the book details
                existingBook.Title = book.Title;
                existingBook.Author = book.Author;
                existingBook.Description = book.Description;
                existingBook.Category = book.Category;
                existingBook.Language = book.Language;
                existingBook.TotalPages = book.TotalPages;

                // Save the changes to the database
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book updated successfully.");

                // Return the details of the updated book
                return new BookResponse
                {
                    Id = existingBook.Id,
                    Title = existingBook.Title,
                    Author = existingBook.Author,
                    Description = existingBook.Description,
                    Category = existingBook.Category,
                    Language = existingBook.Language,
                    TotalPages = existingBook.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error updating book: {ex.Message}");
                throw;
            }
        }
//...

Here, we are querying the database for the book with the specified ID, updating the book entity with the data from the UpdateBookRequest object, saving the updated book entity to the database, and returning the updated book entity as a BookResponse object. We are also logging information and errors using the ILogger dependency.

If the book with the specified ID is not found, we log a warning message and return null. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the UpdateBookAsync method, let's implement the DeleteBookAsync method.

How to Implement the DeleteBookAsync Method

The DeleteBookAsync method is used to delete an existing book from the database. In this method, we will query the database for the book with the specified ID, remove the book entity from the database, and return a boolean value indicating whether the book was successfully deleted.

Update the DeleteBookAsync method in the BookService class as follows:

// Services/BookService.cs

 //...


/// <summary>
        /// Delete a book by its ID
        /// </summary>
        /// <param name="id">ID of the book to be deleted</param>
        /// <returns>True if the book was deleted, false otherwise</returns>
        public async Task<bool> DeleteBookAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return false;
                }

                // Remove the book from the database
                _context.Books.Remove(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation($"Book with ID {id} deleted successfully.");
                return true;
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error deleting book: {ex.Message}");
                throw;
            }
        }
//...

In this code, we are querying the database for the book with the specified ID, removing the book entity from the database, and returning a boolean value indicating whether the book was successfully deleted. We are also logging information and errors using the ILogger dependency.

If the book with the specified ID is not found, we log a warning message and return false. If an exception occurs during the process, we log the error message and rethrow the exception.

Now you have successfully implemented the business logic for the AddBookAsync, GetBookByIdAsync, GetBooksAsync, UpdateBookAsync, and DeleteBookAsync methods in the BookService class. These methods handle the CRUD operations for books, validate book data, and handle exceptions. By now, your BookService class should look like this:

using bookapi_minimal.AppContext;
using bookapi_minimal.Contracts;
using bookapi_minimal.Interfaces;
using bookapi_minimal.Models;
using Microsoft.EntityFrameworkCore;

namespace bookapi_minimal.Services
{
    public class BookService : IBookService
    {
          private readonly ApplicationContext _context; // Database context
        private readonly ILogger<BookService> _logger; // Logger for logging information and error
          // Constructor to initialize the database context and logger
        public BookService(ApplicationContext context, ILogger<BookService> logger)
        {
            _context = context;
            _logger = logger;
        }

           /// Add a new book
        /// </summary>
        /// <param name="createBookRequest">Book request to be added</param>
        /// <returns>Details of the created book</returns>
        public async Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest)
        {
            try
            {
                var book = new BookModel
                {
                    Title = createBookRequest.Title,
                    Author = createBookRequest.Author,
                    Description = createBookRequest.Description,
                    Category = createBookRequest.Category,
                    Language = createBookRequest.Language,
                    TotalPages = createBookRequest.TotalPages
                };

                // Add the book to the database
                _context.Books.Add(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book added successfully.");

                // Return the details of the created book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error adding book: {ex.Message}");
                throw;
            }
        }

          /// <summary>
        /// Get a book by its ID
        /// </summary>
        /// <param name="id">ID of the book</param>
        /// <returns>Details of the book</returns>
        public async Task<BookResponse>  GetBookByIdAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Return the details of the book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving book: {ex.Message}");
                throw;
            }
        }



  /// <summary>
        /// Get all books
        /// </summary>
        /// <returns>List of all books</returns>
        public async Task<IEnumerable<BookResponse>> GetBooksAsync()
        {
            try
            {
                // Get all books from the database
                var books = await _context.Books.ToListAsync();

                // Return the details of all books
                return books.Select(book => new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                });
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving books: {ex.Message}");
                throw;
            }
        }


         /// <summary>
        /// Update an existing book
        /// </summary>
        /// <param name="id">ID of the book to be updated</param>
        /// <param name="book">Updated book model</param>
        /// <returns>Details of the updated book</returns>
        public async Task<BookResponse> UpdateBookAsync(Guid id, UpdateBookRequest book)
        {
            try
            {
                // Find the existing book by its ID
                var existingBook = await _context.Books.FindAsync(id);
                if (existingBook == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Update the book details
                existingBook.Title = book.Title;
                existingBook.Author = book.Author;
                existingBook.Description = book.Description;
                existingBook.Category = book.Category;
                existingBook.Language = book.Language;
                existingBook.TotalPages = book.TotalPages;

                // Save the changes to the database
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book updated successfully.");

                // Return the details of the updated book
                return new BookResponse
                {
                    Id = existingBook.Id,
                    Title = existingBook.Title,
                    Author = existingBook.Author,
                    Description = existingBook.Description,
                    Category = existingBook.Category,
                    Language = existingBook.Language,
                    TotalPages = existingBook.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error updating book: {ex.Message}");
                throw;
            }
        }



        /// <summary>
        /// Delete a book by its ID
        /// </summary>
        /// <param name="id">ID of the book to be deleted</param>
        /// <returns>True if the book was deleted, false otherwise</returns>
        public async Task<bool> DeleteBookAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return false;
                }

                // Remove the book from the database
                _context.Books.Remove(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation($"Book with ID {id} deleted successfully.");
                return true;
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error deleting book: {ex.Message}");
                throw;
            }
        }

    }
}

Congratulations! You have successfully implemented the business logic for the AddBookAsync, GetBookByIdAsync, GetBooksAsync, UpdateBookAsync, and DeleteBookAsync methods in the BookService class.

There's one thing we need to do: we need to register the service in our extension method. Let's go ahead and do that.

In your ServiceExtensions.cs file, add the following code:

// Extensions/ServiceExtensions.cs

//..

 builder.Services.AddScoped<IBookService, BookService>();
//...

This will register the BookService class as a scoped service. This means that the service will be created once per request and disposed of after the request is complete.

Now that we have the service working, let's go ahead and create the exception classes.

How to Create Exceptions

Properly handling exceptions is crucial for ensuring the stability and reliability of an application. In the context of ASP.NET Core, there are two main types of exceptions:

• System Exceptions: These are exceptions thrown by the .NET runtime or the underlying system.

• Application Exceptions: These are exceptions thrown by the application code to handle specific errors or conditions.

In ASP.NET Core with .NET 8, a new feature called global exception handling was introduced. This feature allows you to handle exceptions globally in your application, making it easier to manage errors and provide a consistent user experience.

In our application, we will create custom exception classes to handle specific errors and conditions. We’ll also leverage the global exception handling feature to manage exceptions globally, ensuring a uniform approach to error handling across the entire application.

We are going to create the following exception classes:

• NoBookFoundException: Thrown when a book with the specified ID is not found.

• BookDoesNotExistException: Thrown when a book with the specified ID does not exist.

• GlobalExceptionHandler: Handles exceptions globally in the application.

In the Exceptions folder, create a new file named NoBookFoundException.cs and add the following code:

// Exceptions/NoBookFoundException.cs

namespace bookapi_minimal.Exceptions
{

    public class NoBookFoundException : Exception
    {

        public NoBookFoundException() : base("No books found")
        {}
    }
}

In this code, we are creating a custom exception class named NoBookFoundException that inherits from the Exception class. The NoBookFoundException class is used to handle the scenario where no books are found in the database. We are also providing a custom error message for the exception.

In the Exceptions folder, create a new file named BookDoesNotExistException.cs and add the following code:

namespace bookapi_minimal.Exceptions
{
     public class BookDoesNotExistException : Exception
    {
        private int id { get; set; }

        public BookDoesNotExistException(int id) : base($"Book with id {id} does not exist")
        {
            this.id = id;
        } 

    }
}

In this code, we are creating a custom exception class named BookDoesNotExistException that inherits from the Exception class. The BookDoesNotExistException class is used to handle the scenario where a book with the specified ID does not exist in the database. We are also providing a custom error message for the exception.

In the Exceptions folder, create a new file named GlobalExceptionHandler.cs and add the following code:

// Exceptions/GlobalExceptionHandler.cs

using System.Net;
using bookapi_minimal.Contracts;
using Microsoft.AspNetCore.Diagnostics;

namespace bookapi_minimal.Exceptions
{

   // Global exception handler class implementing IExceptionHandler
    public class GlobalExceptionHandler : IExceptionHandler
    {
        private readonly ILogger<GlobalExceptionHandler> _logger;

        // Constructor to initialize the logger
        public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
        {
            _logger = logger;
        }

        // Method to handle exceptions asynchronously
        public async ValueTask<bool> TryHandleAsync(
            HttpContext httpContext,
            Exception exception,
            CancellationToken cancellationToken)
        {
            // Log the exception details
            _logger.LogError(exception, "An error occurred while processing your request");

            var errorResponse = new ErrorResponse
            {
                Message = exception.Message,
                Title = exception.GetType().Name
            };

            // Determine the status code based on the type of exception
            switch (exception)
            {
                case BadHttpRequestException:
                    errorResponse.StatusCode = (int)HttpStatusCode.BadRequest;
                    break;

                case NoBookFoundException:
                case BookDoesNotExistException:
                    errorResponse.StatusCode = (int)HttpStatusCode.NotFound;
                    break;

                default:
                    errorResponse.StatusCode = (int)HttpStatusCode.InternalServerError;
                    break;
            }

            // Set the response status code
            httpContext.Response.StatusCode = errorResponse.StatusCode;

            // Write the error response as JSON
            await httpContext.Response.WriteAsJsonAsync(errorResponse, cancellationToken);

            // Return true to indicate that the exception was handled
            return true;
        }
    }
}

Let's break down the code above:

• We define a class named GlobalExceptionHandler that implements the IExceptionHandler interface. The IExceptionHandler interface is used to handle exceptions globally in the application.

• The GlobalExceptionHandler class contains a constructor that initializes the ILogger<GlobalExceptionHandler> dependency. The ILogger is used for logging information and errors.

• The TryHandleAsync method is used to handle exceptions asynchronously. This method accepts the HttpContext, Exception, and CancellationToken as parameters.

• We log the exception details using the ILogger dependency.

• We create an ErrorResponse object to represent the error response returned by the API. The ErrorResponse object contains the error message, title, and status code.

• We determine the status code based on the type of exception. If the exception is a BadHttpRequestException, we set the status code to BadRequest. If the exception is a NoBookFoundException or BookDoesNotExistException, we set the status code to NotFound. Otherwise, we set the status code to InternalServerError.

• We set the response status code using the httpContext.Response.StatusCode property.

• We write the error response as JSON using the httpContext.Response.WriteAsJsonAsync method.

• We return true to indicate that the exception was handled successfully.

Now that we have created the exception classes, let's register the GlobalExceptionHandler in the dependency injection container. Since we created an Extension method for registering services in the dependency injection container, we will add the GlobalExceptionHandler to the ServiceExtensions class.

Update the ServiceExtensions class in the Extensions folder as follows:

// Extensions/ServiceExtensions.cs
//...
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

builder.Services.AddProblemDetails();

//...

The AddExceptionHandler method registers the GlobalExceptionHandler in the dependency injection container. The AddProblemDetails method registers the ProblemDetails class in the dependency injection container.

Now that we have registered the GlobalExceptionHandler in the dependency injection container, we can use it to handle exceptions globally in our application. In the next section, we will create the API endpoints to interact with the book data.

How to Create the API Endpoints

In the context of minimal APIs in ASP.NET Core, there are many ways to set up your endpoints.

You can define them directly in your Program.cs file. But as your project grows and you need to add more endpoints or functionality, it’s helpful to organize your code better. One way to achieve this is by creating a separate class to handle all the endpoints.

As we’ve discussed above, minimal APIs don’t use controllers or views like traditional ASP.NET Core applications. Instead, they use methods such as MapGet, MapPost, MapPut, and MapDelete to define HTTP methods and routes for API endpoints.

To get started, navigate to the Endpoints folder and create a new file named BookEndpoints.cs. Add the following code to the file:

// Endpoints/BookEndpoints.cs



namespace bookapi_minimal.Endpoints
{
     public static class BookEndPoint
    {
        public static IEndpointRouteBuilder MapBookEndPoint(this IEndpointRouteBuilder app)
        {


            return app;
        }
    }
}

The BookEndpoints class contains a MapBookEndPoint method that returns an IEndpointRouteBuilder object. The IEndpointRouteBuilder object is used to define the HTTP methods and routes for the API endpoints. In the next sections, we will define the API endpoints for creating, reading, updating, and deleting books.

How to Create the AddBookAsync Books Endpoint

In this section, we will create the AddBookAsync endpoint. This endpoint will accept a Book object as a JSON payload and add it to the database. We will use the MapPost method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs


//...
   // Endpoint to add a new book
      app.MapPost("/books", async (CreateBookRequest createBookRequest, IBookService bookService) =>
        {
        var result = await bookService.AddBookAsync(createBookRequest);
        return Results.Created($"/books/{result.Id}", result); 
        });


//...

• Route Definition: The MapPost method defines the route for the endpoint as /books.

• Request Model: The endpoint accepts an CreateBookRequest object as a JSON payload. The CreateBookRequest object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns a Created result. The Created result contains the location of the newly created book and the Book object.

How to Create the GetBookAsync Book Endpoint

In this section, we will create the GetBookAsync endpoint. This endpoint will accept a book ID as a query parameter and return the book with the specified ID. We will use the MapGet method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs

// ...
    // Endpoint to get all books
    app.MapGet("/books", async (IBookService bookService) =>
     {
    var result = await bookService.GetBooksAsync();
    return Results.Ok(result);
});


//...

• Route Definition: The MapGet method defines the route for the endpoint as /books.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns an Ok result. The Ok result contains the Book object.

How to Create the GetBookByIdAsync Book Endpoint

In this section, we will create the GetBookByIdAsync endpoint. This endpoint will accept a book ID as a route parameter and return the book with the specified ID. We will use the MapGet method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs
//...
// Endpoint to get a book by ID

  app.MapGet("/books/{id:guid}", async (Guid id, IBookService bookService) =>
  {
    var result = await bookService.GetBookByIdAsync(id);
    return result != null ? Results.Ok(result) : Results.NotFound();
});

//...

• Route Definition: The MapGet method defines the route for the endpoint as /books/{id:guid}. The {id:guid} parameter specifies that the id parameter should be a GUID.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns an Ok result if the book is found. The NotFound result is returned if the book is not found.

How to Create the UpdateBookAsync Book Endpoint

In this section, we will create the UpdateBookAsync endpoint. This endpoint will accept a book ID as a route parameter and an Book object as a JSON payload and update the book with the specified ID. We will use the MapPut method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs

//...
   // Endpoint to update a book by ID
    app.MapPut("/books/{id:guid}", async (Guid id, UpdateBookRequest updateBookRequest, IBookService bookService) =>
 {
var result = await bookService.UpdateBookAsync(id, updateBookRequest);
return result != null ? Results.Ok(result) : Results.NotFound();
});

//...

• Route Definition: The MapPut method defines the route for the endpoint as /books/{id:guid}. The {id:guid} parameter specifies that the id parameter should be a GUID.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns an Ok result if the book is found. The NotFound result is returned if the book is not found.

How to Create the DeleteBookAsync Book Endpoint

In this section, we will create the DeleteBookAsync endpoint. This endpoint will accept a book ID as a route parameter and delete the book with the specified ID. We will use the MapDelete method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs

//...
   // Endpoint to delete a book by ID
 app.MapDelete("/books/{id:guid}", async (Guid id, IBookService bookService) =>
{
var result = await bookService.DeleteBookAsync(id);
   return result ? Results.NoContent() : Results.NotFound();
});


//...

• Route Definition: The MapDelete method defines the route for the endpoint as /books/{id:guid}. The {id:guid} parameter specifies that the id parameter should be a GUID.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns a NoContent result if the book is deleted successfully. The NotFound result is returned if the book is not found.

Now we have defined all the methods for the book endpoints. So your endpoint class should look like this:

// Endpoints/BookEndpoints.cs
using bookapi_minimal.Contracts;
using bookapi_minimal.Interfaces;

namespace bookapi_minimal.Endpoints
{
     public static class BookEndPoint
    {
        public static IEndpointRouteBuilder MapBookEndPoint(this IEndpointRouteBuilder app)
        {
            // Define the endpoints

            // Endpoint to add a new book
            app.MapPost("/books", async (CreateBookRequest createBookRequest, IBookService bookService) =>
            {
                var result = await bookService.AddBookAsync(createBookRequest);
                return Results.Created($"/books/{result.Id}", result); 
            });


               // Endpoint to get all books
            app.MapGet("/books", async (IBookService bookService) =>
            {
                var result = await bookService.GetBooksAsync();
                return Results.Ok(result);
            });

            // Endpoint to get a book by ID
            app.MapGet("/books/{id:guid}", async (Guid id, IBookService bookService) =>
            {
                var result = await bookService.GetBookByIdAsync(id);
                return result != null ? Results.Ok(result) : Results.NotFound();
            });


            // Endpoint to update a book by ID
            app.MapPut("/books/{id:guid}", async (Guid id, UpdateBookRequest updateBookRequest, IBookService bookService) =>
            {
                var result = await bookService.UpdateBookAsync(id, updateBookRequest);
                return result != null ? Results.Ok(result) : Results.NotFound();
            });

            // Endpoint to delete a book by ID
            app.MapDelete("/books/{id:guid}", async (Guid id, IBookService bookService) =>
            {
                var result = await bookService.DeleteBookAsync(id);
                return result ? Results.NoContent() : Results.NotFound();
            });

            return app;
        }
    }
}

Congratulations! You have created all the endpoints for the book API. The endpoints handle the CRUD operations for books and return the appropriate responses based on the request and data.

How to Register the Endpoints

After defining the API endpoints for the book API, the next step is to register these endpoints in the Program.cs file. We will use the MapBookEndpoints method to register the book endpoints.

We should also clean up our Program.cs class to ensure it remains organized and maintainable.

// Program.cs

using System.Reflection;
using bookapi_minimal.Endpoints;
using bookapi_minimal.Services;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);


builder.AddApplicationServices();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c=>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Mimal API", Version = "v1", Description = "Showing how you can build minimal " +
        "api with .net" });


    // Set the comments path for the Swagger JSON and UI.
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);

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

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

app.UseHttpsRedirection();
app.UseExceptionHandler();


app.MapGroup("/api/v1/")
   .WithTags(" Book endpoints")
   .MapBookEndPoint();

app.Run();

Let's break down the key components of the Program.cs file:

• AddApplicationServices: This method registers the necessary services for the API. It is an extension method we created earlier to add services to the dependency injection container.

• AddSwaggerGen: This method registers the Swagger generator, which is used to create the Swagger documentation for the API. We specify the title, version, and description of the API in the Swagger document.

• MapGroup: This method groups the endpoints. It takes a path as a parameter and returns an IEndpointRouteBuilder object. We use the WithTags method to add tags to the endpoints and the MapBookEndpoints method to register the book endpoints.

• Run: This method starts the application.

To enable Swagger documentation, you need to add the GenerateDocumentationFile property to your .csproj file. In this example, the file is named bookapi-minimal.csproj, but the name may vary based on your project.

Add the following line to your .csproj file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

By the end, bookapi-minimal.csproj should look like this:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <RootNamespace>bookapi_minimal</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
   <PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.9.2" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.6" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

Now that we have registered the book endpoints in the Program.cs file, we can run the application and test the API endpoints using Swagger.

When you run the application, you should see the Swagger documentation at the following URL: https://localhost:5001/swagger/index.html. The Swagger documentation provides information about the API endpoints, request and response models, and allows you to test the endpoints directly from the browser. You should see something like this:

Congratulations! You have implemented the business logic for the book service, created custom exceptions, defined API endpoints, and registered the endpoints in the Program.cs file. You have also enabled Swagger documentation to test the API endpoints.

How to Add Seed Data to the Database

One more important step is to seed the database with initial data when the application starts. This seed data will populate the database, allowing you to test your API endpoints without manually adding data.

Let's add some seed data before performing migrations and testing our API endpoints.

To achieve this, we will create a new class in our Configuration folder called BookTypeConfigurations and add the following code:

using bookapi_minimal.Models;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

namespace bookapi_minimal.Configurations
{
    public class BookTypeConfigurations : IEntityTypeConfiguration<BookModel>
    {
        public void Configure(EntityTypeBuilder<BookModel> builder)
        {
            // Configure the table name
            builder.ToTable("Books");

            // Configure the primary key
            builder.HasKey(x => x.Id);

            // Configure properties
            builder.Property(x => x.Id).ValueGeneratedOnAdd();
            builder.Property(x => x.Title).IsRequired().HasMaxLength(100);
            builder.Property(x => x.Author).IsRequired().HasMaxLength(100);
            builder.Property(x => x.Description).IsRequired().HasMaxLength(500);
            builder.Property(x => x.Category).IsRequired().HasMaxLength(100);
            builder.Property(x => x.Language).IsRequired().HasMaxLength(50);
            builder.Property(x => x.TotalPages).IsRequired();

            // Seed data
            builder.HasData(
                new BookModel
                {
                    Id = Guid.NewGuid(),
                    Title = "The Alchemist",
                    Author = "Paulo Coelho",
                    Description = "The Alchemist follows the journey of an Andalusian shepherd",
                    Category = "Fiction",
                    Language = "English",
                    TotalPages = 208
                },
                new BookModel
                {
                    Id = Guid.NewGuid(),
                    Title = "To Kill a Mockingbird",
                    Author = "Harper Lee",
                    Description = "A novel about the serious issues of rape and racial inequality.",
                    Category = "Fiction",
                    Language = "English",
                    TotalPages = 281
                },
                new BookModel
                {
                    Id = Guid.NewGuid(),
                    Title = "1984",
                    Author = "George Orwell",
                    Description = "A dystopian social science fiction novel and cautionary tale about the dangers of totalitarianism. ",
                  Category = "Fiction",
                  Language = "English",
                  TotalPages = 328
                } 
            );
        }
    }
}

Let's break down the code above:

In Entity Framework Core, you can use the IEntityTypeConfiguration interface to configure the entity type and seed data for the database. The BookTypeConfigurations class implements the IEntityTypeConfiguration<BookModel> interface and provides the configuration for the BookModel entity.

• Configure Method: This method is used to configure the BookModel entity type. It defines the table name, primary key, and properties for the BookModel entity.

  • Table Name: The ToTable method specifies the name of the table to be created in the database. In this case, the table name is set to "Books".

  • Primary Key: The HasKey method specifies the primary key for the BookModel entity. The primary key is set to the Id property.

  • Properties: The Property method configures the properties of the BookModel entity. It specifies the data type, length, and constraints for each property.

• Seed Data: The HasData method seeds the database with initial data. It creates three BookModel objects with sample data for testing the API endpoints.

Now that we have created the BookTypeConfigurations class, we need to register this configuration in the ApplicationContext class. This ensures that the configuration is applied when the database is created or migrated.

We’re finally almost ready to test our API. But before we do that, we need to perform migrations to create the database and apply the seed data.

Remember that we added our database connection string in the appsettings.json file? Now let's perform a migration and later update our database for the migration to take effect.

How to Perform a Migration

Migrations allow you to update the database schema based on changes made to your model classes. In Entity Framework Core, you can use the dotnet ef migrations add command to create a new migration reflecting these changes.

To perform a migration, run the following command in the terminal:

dotnet ef migrations add InitialCreate

If the command is successful, you should see an output similar to this:

Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

You will now see a new folder called Migrations in your project. This folder contains the migration files that were created based on the changes made to your model classes. These migration files include the SQL commands required to update the database schema.

How to Update the Database

After creating the migration, you need to apply the migration to update the database schema. You can use the dotnet ef database update command to apply the migration and update the database. Make sure the SQL Server is running.

Run the following command in the terminal:

dotnet ef database update

This will update the database schema based on the changes made to your model classes. Make sure there are no errors on your database connection string.

How to Test the API Endpoints

Now we can test our endpoints using Swagger. To do this, run the application by executing the following command in the terminal:

dotnet run

This will run our application. You can open your browser and navigate to https://localhost:5001/swagger/index.html to access the Swagger documentation. You should see a list of API endpoints, request and response models, and the ability to test the endpoints directly from the browser.

If your port number is different from 5001, don't worry – it will still work. The port might change depending on the type of machine you're using, but it will still achieve the same result.

How to Test the Get All Books Endpoint

To test the Get All Books endpoint, follow these steps:

1. In the Swagger documentation, click on the GET /api/v1/books endpoint.

2. Click the Try it out button.

3. Click the Execute button.

This will send a request to the API to retrieve all the books in the database.

You should see the response from the API, which will include the list of books that were seeded in the database.

The image below shows the response from the API:

How to Test the Get Book by ID Endpoint

To test the Get Book by ID endpoint, follow these steps:

1. In the Swagger documentation, click on the GET /api/v1/books/{id} endpoint.

2. Enter the ID of a book in the id field. You can use one of the book IDs that was seeded in the database.

3. Click the Try it out button.

This will send a request to the API to retrieve the book with the specified ID. You should see the response from the API, which will include the book with the specified ID.

The image below shows the response from the API:

How to Test the Add Book Endpoint

To test the Add Book endpoint, follow these steps:

1. In the Swagger documentation, click on the POST /api/v1/books endpoint.

2. Click the Try it out button.

3. Enter the book details in the request body.

4. Click the Execute button.

This will send a request to the API to add a new book to the database.

You should see the response from the API, which will include the newly created book.

The image below shows the response from the API:

How to Test the Update Book Endpoint

To test the Update Book endpoint, follow these steps:

1. In the Swagger documentation, click on the PUT /api/v1/books/{id} endpoint.

2. Enter the ID of a book in the id field. You can use the id of one of the books that we just added.

3. Click the Try it out button.

This will send a request to the API to update the book with the specified ID.

You should see the response from the API, which will include the updated book.

The image below shows the response from the API:

How to Test the Delete Book Endpoint

To test the Delete Book endpoint, follow these steps:

1. In the Swagger documentation, click on the DELETE /api/v1/books/{id} endpoint.

2. Enter the ID of a book in the id field. You can use any of the ids from the books that we just added or the seeded data.

3. Click the Try it out button.

This will send a request to the API to delete the book with the specified ID.

The image below shows the response from the API:

Congratulations! You have implemented all the CRUD operations for books and tested the API endpoints using Swagger, verifying that they work as expected. You can now build on this foundation to add more features and functionality to your API.

Conclusion

This handbook explored how to create a minimal API in ASP.NET Core with .NET 8. We built a comprehensive book API that supports CRUD operations, implemented custom exceptions, defined and registered API endpoints, and enabled Swagger documentation for easy testing.

Following this tutorial, you have gained a solid foundation for building minimal APIs with ASP.NET Core. You can now apply this knowledge and create robust APIs for various domains and industries.

I hope you found this tutorial both helpful and informative. Thank you for reading!

Feel free to connect with me on social media:

• Twitter

• LinkedIn

• GitHub

In this article, I will show you how to test the performance of your code, benchmark your code, and identify areas of improvement within your code base.

Table of Contents

• What is Benchmarking?

• Why Using a Stopwatch is Not Reliable

• How to Use BenchMarkDotnet

• What Else Can You Test with BenchmarkDotnet?

What is Benchmarking?

Benchmarking measures the performance of your code, application, system, or hardware under specific conditions.

The goal is to gather precise data about how the system behaves for metrics like processing speed, memory usage, resource consumption, or throughput and to identify areas where performance can be optimized.

Why Using a Stopwatch is Not Reliable

Using the Stopwatch class for benchmarking in C# comes with many problems. Although it provides a simple way to measure elapsed time on a method or process, it lacks the precision, control, and consistency needed for accurate benchmarking.

Before I get into the negatives of this utility, let’s look at how you could use it for very simple tasks.

using System.Diagnostics;

// Create a new Stopwatch instance
var sw = new Stopwatch();

// Start the stop watch clock
sw.Start();

// run your code
var sum = 0;
for (int i = 0; i < 100; i++)
{
    sum += i * i;
    Console.WriteLine($"{sw.ElapsedMilliseconds}");
}
// Stop the clock !
sw.Stop();

// Output total time elapsed on the Stopwatch.
Console.WriteLine($"Elapsed time: {sw.ElapsedMilliseconds} ms");

This would print out how many milliseconds have elapsed on each iteration as well as the end elapsed milliseconds. As this is a short program, you can convert to nanoseconds by using ticks like so:

long ticks = stopwatch.ElapsedTicks;
double nanoseconds = (ticks * 1e9) / Stopwatch.Frequency;

Using a stopwatch can be useful if you want to quickly compare two methods or identify obvious performance bottlenecks during development. It’s a lightweight way to get an initial sense of which sections of code might need optimization.

Cons of Stopwatch

• Lack of precision by default, being only accurate to around 100 nanoseconds, which may not be useful for smaller quick micro operations.

• JIT (Just in Time) compilation - When code runs for the first time, a JIT compiler compiles the code before running, causing a delay and skewing the timing of completion. Subsequent runs of the code will be slightly faster, however, Stopwatch does not account for this. Keeping this in mind, it is worth running the code a few times to try and alleviate this problem.

• Garbage Collection (GC) - If garbage collection happens during a Stopwatch measurement, the time recorded will include GC pause time, which does not reflect the actual execution time of your code.

These are just some of the basic, and most common flaws of using a Stopwatch to test the performance of your code but there are others.

So what is the best approach?

BenchmarkDotNet is a popular and robust library for benchmarking in .NET, which can be installed using nuget.

It overcomes many of the above challenges, in the following ways:

• Code Warm Ups - Automatically warms up the code (by running the code a few times) to avoid JIT-related inaccuracies.

• Multiple code iterations - Runs the code multiple times to analyze and calculates statistical summaries, around execution time, heap memory allocation and more. The number of times the code is ran can be configured.

• Isolated Environments - Manages garbage collection and isolates the execution environment to reduce external interference.

How to Use BenchMarkDotnet

Firstly, we need to install the Nuget package. To do this, run the following command in your command line/terminal:

dotnet add package BenchmarkDotnet

We then need some methods to benchmark, so create a .Net 8 C# console app with the following two class files:

// Program.cs
using BenchmarkDotNet.Running;

BenchmarkRunner.Run<Benchmarks>();

//Benchmarks.cs
using BenchmarkDotNet.Attributes;

public class Benchmarks
{
    private readonly int[] _numbers = Enumerable.Range(1, 1000).ToArray();

    [Benchmark]
    public int ForLoopSum()
    {
        int sum = 0;
        for (int i = 0; i < _numbers.Length; i++)
        {
            sum += _numbers[i];
        }

        return sum;
    }

    [Benchmark]
    public int ForeachLoopSum()
    {
        var sum = 0;
        foreach (int number in _numbers)
        {
            sum += number;
        }

        return sum;
    }

    [Benchmark]
    public int LinqSelect()
    {
        return _numbers.Sum();
    }
}

Above, we have 3 different methods to add up an array of integers, each doing so in a slightly different fashion. This is a perfect example to show how benchmarking can aid us to choose the best solution in our code base.

How to Run the Benchmarks

To run the benchmarks, you can run the following commands in your terminal/command line.

dotnet build
# then run 
dotnet run -c Release

BenchmarkDotnet will then run the methods marked with the [Benchmark] attribute multiple times, and will output the results in an easy to read table, like so:

| Method         | Mean     | Error   | StdDev  |
|--------------- |---------:|--------:|--------:|
| ForLoopSum     | 434.2 ns | 0.40 ns | 0.31 ns |
| ForeachLoopSum | 321.9 ns | 1.22 ns | 1.14 ns |
| LinqSelect     | 189.4 ns | 0.84 ns | 0.70 ns |

What does this mean?

Method - Name of the method under test

Mean - Shows the mean (average) time it took in nanoseconds.

Error - Represents the margin of error, telling you how much the "Mean" result might vary due to random factors in the system. The lower the number the better, here you can see a very small margin of error meaning the results are stable, whilst large numbers would mean more uncertainty/ unreliable results.

StdDev - (Standard Deviation) shows how consistent the benchmark results are. A low deviation score indicates the time taken was very similar across multiple runs, increasing reliability. If the standard deviation is high, it would mean the method’s execution time varied a lot between runs.

How to Measure Memory Allocation

Knowing how fast your methods run is a great statistic to understand and know. However, your performance and optimization isn’t just about the time of execution, sometimes you should ensure that there are no memory leaks or large sums of memory utilized, especially with large execution process.

We can use the [MemoryDiagnoser] to the Benchmarks class, which informs the benchmarking library to include memory statistics to the methods under test.

When we run our benchmarks, we get the following output:

| Method         | Mean     | Error   | StdDev  | Allocated |
|--------------- |---------:|--------:|--------:|----------:|
| ForLoopSum     | 436.8 ns | 5.32 ns | 4.98 ns |         - |
| ForeachLoopSum | 324.6 ns | 2.20 ns | 2.06 ns |         - |
| LinqSelect     | 192.7 ns | 2.40 ns | 2.24 ns |         - |

But wait, the Allocated column has but a dash ? Where are the results?

Simple operations, like summing values in an array generally don’t allocate memory, as they often only use stack memory, which BenchmarkDotNet doesn’t track in the same way.

But using the following tests, we can see how memory allocation can be analyzed:

public class MemoryBenchmark
{
    [Benchmark]
    public string StringConcatenation()
    {
        string result = "";
        for (int i = 0; i < 1000; i++)
        {
            result += "text";
        }
        return result;
    }

    [Benchmark]
    public string StringBuilderConcatenation()
    {
        var builder = new System.Text.StringBuilder();
        for (int i = 0; i < 1000; i++)
        {
            builder.Append("text");
        }
        return builder.ToString();
    }
}

Output:

| Method                     | Mean       | Error     | StdDev    | Gen0     | Allocated  |
|--------------------------- |-----------:|----------:|----------:|---------:|-----------:|
| StringConcatenation        | 218.930 us | 0.7230 us | 0.6409 us | 641.8457 | 3933.56 KB |
| StringBuilderConcatenation |   1.645 us | 0.0034 us | 0.0030 us |   2.6875 |   16.47 KB |

Here we have 2 new columns:
Gen0 Column:
The Gen0 column indicates how many Gen 0 garbage collections occurred during each method’s execution.

.Net uses a generational garbage collection system, where memory is divided into three "generations" (Gen0, Gen1, and Gen2).

• Gen0 (Generation 0): Holds short-lived objects, such as temporary variables and small, quickly discarded objects. Gen0 collections are the fastest type of GC but still introduce some overhead. Examples of Gen0 would be local variables in methods, temporary objects, or method call arguments that aren’t used later on.

• Gen1 and Gen2: This is for longer-lived objects that survive Gen0 collections, like static objects that are kept alive for the lifetime of the application (that is, singletons), caching objects or large collections used across many operations.

Objects in Gen0 are collected quickly but often, and objects in Gen2 are collected infrequently but with more effort because they are larger or more persistent. A lot of Gen0 collections can be an indicator of inefficient memory usage, while Gen2 or 3 collections may indicate that your app is keeping too many long-lived objects in memory.

Allocated Column:
The Allocated column shows the total memory allocated by each method during its execution. This is typically reported in kilobytes (KB).

This information helps you see how memory-intensive each method is, which can impact performance, especially if the method is called frequently.

For example, StringBuilderConcatenation is much more memory-efficient than StringConcatenation, which makes it preferable in cases where memory usage is a concern or where this operation is performed frequently.

What Else Can You Test with BenchmarkDotnet?

Throughput

• Analyzes how many iterations of a method can be executed per second.

• Indicates the efficiency and scalability of the code.

JIT (Just-In-Time) Optimization Impact

• Evaluates the effects of JIT optimizations on performance.

• Can test cold starts (first-run performance) versus steady-state performance (subsequent runs).

Platform and Framework Differences

You could run benchmarks of the same code across different .NET runtimes (for example, .NET 6, .NET 8, .NET Framework) to compare whether it’s worth upgrading your application to newer systems or not.

Simply update the TargetFramework node in the .csproj file of your application to target the frameworks you wish to test.

Add the following attributes to your benchmark class (based on the target runtime).

[SimpleJob(runtimeMoniker: RuntimeMoniker.Net60)]
[SimpleJob(runtimeMoniker: RuntimeMoniker.Net80)]

when you run your application you will get an output as below highlighting the differenes in methods across both .net 6 and .net 8

Impact of Input Parameters

• Supports parameterized benchmarks to test how different inputs affect performance.

• Helps identify optimal input ranges or problematic edge cases.

You can do something like this

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

public class SortBenchmark
{
    [Params(10, 100, 1000)]  // Size of the array
    public int N;

    [Params(10, 100, 1000)]  // Maximum value of the array elements
    public int MaxValue;

    private int[] data;

    // Setup method to create an array before each benchmark
    [GlobalSetup]
    public void Setup()
    {
        data = new int[N];
        var rand = new Random();
        for (int i = 0; i < N; i++)
        {
            data[i] = rand.Next(MaxValue);
        }
    }

    [Benchmark]
    public void SortArray()
    {
        Array.Sort(data);  // Sort the array
    }
}

class Program
{
    static void Main(string[] args)
    {
        // Run the benchmark
        BenchmarkRunner.Run<SortBenchmark>();
    }
}

Giving the output of:

Third-Party Library Performance

Using the techniques mentioned above, you can compare the performance of different third-party libraries for the same task to make informed decisions on library usage.

Conclusion

There you have it, how to benchmark your C# application. Using a combination of these methods, tools and techniques, the possibilities of benchmarking are incredible.

You can use benchmarking to improve your application’s code base, help make decisions on upgrade paths, and method choices.

I hope you find this article helpful, and as always, if you wish to discuss it you can follow me on Twitter.

SemVer is perhaps the the most widely used versioning scheme today. For example, both Nuget and npm recommend and support it, and VS Code uses it as well.

In most GitHub repos that use the GitHub Releases feature to publish releases, you would see a SemVer version number in the latest release badge on the home page, as can be seen in the screenshot below:

I frequently need to set a SemVer version number when building ASP.NET Core API projects, and then read or report this at runtime.

For example, if I build a minimal API with its version set to 1.0.2-beta, this would be reported by a /version endpoint exposed by the API, as shown in the screenshot below from Hoppscotch (this is a Postman-like tool with the convenience that it runs the browser):

Checking that the version reported from deployed services, such as web apps and APIs, is correct is a crucial part of my CD pipeline and is one of the smoke tests I use to determine if a deployment succeeded.

One slight complication when setting a SemVer version number on .NET assemblies is that .NET originally used four part version numbers like 1.0.3.212 and assemblies still have these (assembly is the .NET term for units of code compiled to .NET bytecode, the most typical of these being dll’s and exe’s).

The other is that .NET has not one but many, slightly different, version numbers that are present in the same assembly.

In this article, I’ll show you how to sidestep these quirks and stamp a SemVer version number on a .NET assembly during build, then read it back at runtime.

Table of Contents

• Structure of a SemVer Version Number

• The Many Version Numbers of a .NET Assembly

• How to Set a SemVer Version Number

• How to Read an Assembly’s SemVer Version at Runtime

• Conclusion

Structure of a SemVer Version Number

Consider a SemVer version number like 1.0.2 or 1.0.2-beta. It has the form <major>.<minor>.<patch>-<prerelease>

This is what the various components mean:

The <major> component of the version number would be incremented only if the new release would break an existing (most recent) release.

In case of a UI app, clients may be taken to mean human clients. So if the new release would break users’ existing assets such as workflow definitions, this would call for incrementing the major version number. In this event, if the previous release was 1.0.2, the new release should be 2.0.0 (all lower components of the version number would reset).

In case of a library, such as a library package on Nuget or NPM, the clients would be other code. So if the new release would break existing client code, i.e. it would not be backwards compatible with its own previous version, then again it is the <major> component would be incremented.

<minor> is incremented if new features have been added but the new version is still backwards compatible. So from 1.0.2 you would go to 1.1.0.

<patch> is incremented when a new release needs to be made even though there is no breaking change and no new functionality has been added. This could happen, for example, if there was a bugfix that had to be released.

-<prerelease> suffix is optional. It is typically suffixed to a three part version number when software needs to be made available during prerelease testing phases such as alpha and beta. For example, before generally releasing version 1.0.2 of your software, you can make it available to your beta testers as 1.0.2-beta.

The <prerelease> component can pretty much be any string of your choosing and the only requirement is that it is either an alphanumeric identifier such as beta or 12 or alpha2 (no characters other than numbers or letters of the alphabet) or multiple alphanumeric identifiers separated by a dot(.) e.g. development.version.

The Many Version Numbers of a .NET Assembly

As Andrew Lock’s article on .NET versioning explains, a .NET assembly has not one but several different version numbers:

• AssemblyVersion: This is a four part version number, for example, 1.0.2.0. It is used by the runtime when loading linked assemblies.

• FileVersion: This is the version number reported for a .dll file in Windows File Explorer when you right click the assembly and select Properties.

• InformationalVersion: Yet another version number and, like FileVersion, can be seen in Properties dialog if you right-click the assembly in Windows and select Properties. This can contain strings and not only integers and dots that AssemblyVersion and FileVersion are constrained to.

• PackageVersion: If the project is a Nuget package, this would be the version number of the package that the assembly is part of.

All of these version numbers are emitted into the assembly during compilation as metadata. You can see them if you inspect the assembly with JetBrains dotPeek (free) or Red gate Reflector (not free) or similar.

FileVersion and InformationalVersion can also be seen in the Details tab of the Properties dialog that appears when you right-click the assembly file in Windows File Explorer and select Properties:

In the screenshot above, “Product version” is the caption for InformationalVersion whereas “File version” is the caption for FIleVersion.

Of the four types of version numbers described above, only the first three apply to any assembly (i.e. whether or not the assembly is part of a Nuget package).

Of those three, AssemblyVersion alsways adds a 0 in the fourth place if you try to set a SemVer version which only has three numbers (plus an optional prerelease suffix). For example if you try to set a SemVer version of 1.0.2-beta during build and then read the AssemblyVersion value at run time in the assembly, it would be 1.0.2.0.

FileVersion does the same, as shown in the screenshot above.

InformationalVersion is the only version number which would get set exactly to the server version you set during build, as the screenshot above shows.

Therefore, InformationalVersion is what we need to set with a SemVer version during build, and read back at run time.

How to Set a SemVer Version Number

There are two things you need to do to set a SemVer version number on an assembly during build.

First, in a <PropertyGroup> element in the project’s csproj file, add element <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>:

<PropertyGroup>
 ...
 <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion> 
</PropertyGroup>

As described in this issue, this ensures that InformationalVersion is set exactly to the SemVer version number we specified and does not get a +<hash code> tacked on at the end.

Second, pass the version number as value of Version property passed to dotnet build command e.g.:

dotnet build --configuration Release -p Version=1.0.2-beta

This would set InformationalVersion in the compiled assembly (.exe or .dll file) to 1.0.2-beta.

Incidentally, it would also set AssemblyVersion and FileVersion (an extra 0 would be added to the end of 1.0.2) but we are not interested in those.

Note that instead pf passing Version argument on the command line, you can set MS Build property <Version>1.0.2-beta</Version> in a <PropertyGroup> element in the csproj file. However passing a value of Version parameter to dotnet build is simpler because the csproj file does not need to be modified everytime the version number is incremented. This is helpful in CD pipelines. If you do set <Version> in csproj file, this will be overridden by whatever you provide on the dotnet build command line as the value of the Version property.

How to Read an Assembly’s SemVer Version at Runtime

Code that reads InfromationalVersion at run time is as follows:

string? version = Assembly.GetEntryAssembly()?.
  GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.
  InformationalVersion;

In my minimal APIs, to add a /version endpoint as I showed in the Introduction section above, I place the above snippet in Program.cs, then add the following snippet immediately after. Note that the whole thing should appear before builder.Build() is called:

//this object of an anonymous type will 
//be serialised as JSON in response body
//when returned by a handler
var objVersion = new { Version = version ?? "" };

//OTHER CODE
//var app = builder.Build()

After builder.Build() is called, I create the handler for the /version endpoint:

app.MapGet("/version", () => objVersion);

Now when I run the API project and call the /version endpoint, I get the version number back in a JSON object in HTTP response body:

{
  "version": "1.0.2-beta"
}

This is what the Hoppscotch screenshot in the Introduction showed.

Conclusion

This article showed you how to set a SemVer version number in your .NET assemblies.

It also showed you how to read the version number at runtime.

One critical feature of modern web applications is their ability to store and retrieve data on the client side. This is where local storage comes into play.

In this article, we'll explore how to leverage the power of the Blazored LocalStorage NuGet package to seamlessly integrate local storage capabilities into your Blazor applications.

Table of Contents

• Prerequisites
• Understanding Local Storage
• Introducing Blazored.LocalStorage
• Advantages of Using Blazored.LocalStorage in Blazor Applications
• How to Install Blazored.LocalStorage
• Install Using Nuget Package Manager
• Install Using the .NET CLI
• How to Use Blazored.LocalStorage
• Advanced Features and Techniques
• Conclusion

Prerequisites

Make sure you have the necessary tools installed on your computer before continuing with this guide:

• To build and update Blazor projects, you'll need Visual Studio, a feature-rich Integrated Development Environment (IDE) which you can download from the official Microsoft website here.
• The .NET SDK (Software Development Kit) has everything you need to create and execute .NET apps, and it's required for Blazor projects. Make sure your computer has the .NET SDK installed.
• Basic knowledge of C# and Blazor.

With these installed, will be ready to follow along.

Understanding Local Storage

Local storage is a key-value pair storage mechanism supported by modern web browsers. It provides a simple way to store data persistently on the user's device. Unlike session storage, which is cleared when the browser session ends, local storage remains intact even after closing the browser window.

Blazored.LocalStorage is a powerful library that simplifies working with the browser's local storage API (Application Programming Interface) within Blazor applications. It provides a convenient API for storing, retrieving, and managing data in local storage.

By abstracting away the complexities of directly interacting with the localStorage API, this package provides an intuitive and type-safe interface. It lets you focus on building feature-rich Blazor applications without worrying about the underlying storage mechanisms.

Introducing Blazored.LocalStorage

Blazored.LocalStorage is an open-source library designed to provide easy and accessible local storage management in Blazor applications. This library is compatible with both Blazor WebAssembly and Blazor Server projects. This makes it a versatile choice for Blazor developers looking to enhance their applications with persistent, client-side storage capabilities.

At its core, Blazored.LocalStorage facilitates the storage and retrieval of data in the browser's local storage, allowing data to persist across browser sessions.

This is particularly useful for storing user preferences, application state, and other data that needs to persist between page reloads without the need for a database or backend storage solution.

Advantages of Using Blazored.LocalStorage in Blazor Applications

The inclusion of Blazored.LocalStorage in Blazor applications comes with a host of benefits, including:

• Simplified State Management: By leveraging local storage, applications can maintain state more effectively across user sessions, enhancing the user experience.
• Performance Improvements: Storing data locally reduces the need for frequent server requests, leading to faster application performance and reduced server load.
• Enhanced User Experience: Preferences and application states can be preserved, meaning users do not need to reconfigure settings or lose their place in the application upon returning.
• Easy Integration: The API provided by Blazored.LocalStorage is designed to be intuitive and straightforward, ensuring that developers can integrate local storage capabilities into their applications with minimal effort.
• Cross-Session Persistence: Unlike session storage or in-memory data storage, local storage ensures that data persists across browser sessions and tab closures, providing a more consistent user experience.

How to Install Blazored.LocalStorage

Integrating Blazored.LocalStorage into your Blazor project is straightforward, with support for installation via the NuGet Package Manager or the .NET CLI (Command Line Interpreter).

Install Using the NuGet Package Manager

Using Visual Studio, you can easily add Blazored.LocalStorage by following these steps:

• Open your Blazor project in Visual Studio.
• Navigate to the “Solution Explorer”, right-click on "Dependencies", and select “Manage NuGet Packages”.

• In the NuGet Package Manager, click on the “Browse” tab and search for “Blazored.LocalStorage”.

• Find the package in the list, select it, and click “Install”.

Visual Studio will handle the rest, adding the package to your project along with any dependencies.

Install Using the .NET CLI

For those who prefer using the command line or are working within a development environment other than Visual Studio, the .NET CLI provides a simple method to add Blazored.LocalStorage:

dotnet add package Blazored.LocalStorage

Run the command above in your terminal or command prompt from the root directory of your Blazor project. The CLI will download and install Blazored.LocalStorage along with any necessary dependencies.

How to Use Blazored.LocalStorage

Let's dive into some basic examples of using Blazored.LocalStorage in a Blazor application.

How to Register Blazored.LocalStorage in your Blazor Application

We will registerBlazored.LocalStorage into the root of the application, so that it will be available to use everywhere in the application.

In the program.cs file, which is our root file, we will register the Blazored.LocalStorage service by doing the following:

builder.Services.AddBlazoredLocalStorage();

The code snippet above registers the Blazored.LocalStorage into the application. For this to work, make sure you add the code below to the top of the program.cs file:

using Blazored.LocalStorage;

The code snippet above makes sure that the Blazored.LocalStorage is being imported to be used in the file. If you've added everything correctly, your program.cs file should look like this:

using BlazorApp9.Components;
using Blazored.LocalStorage;

namespace BlazorApp9;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddRazorComponents()
            .AddInteractiveServerComponents();

        builder.Services.AddBlazoredLocalStorage();

        var app = builder.Build();

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

        app.UseHttpsRedirection();

        app.UseStaticFiles();
        app.UseAntiforgery();

        app.MapRazorComponents<App>()
            .AddInteractiveServerRenderMode();

        app.Run();
    }
}

The above is the full code that should be in your program.cs file. With this, you can now use Blazored.LocalStorage anywhere in the application to store and receive data.

How to Store and Retrieve Data in Blazored.LocalStorage

Let's consider a simple scenario where we want to store and retrieve a piece of data using local storage. We'll create a Blazor page with two buttons: one to store data and another to retrieve it.

@page "/"

@inject Blazored.LocalStorage.ILocalStorageService localStorage
@rendermode RenderMode.InteractiveServer

<h3>Local Storage Example</h3>

<input @bind-value="@inputData" />

<button @onclick="StoreData">Store Data</button>
<button @onclick="RetrieveData">Retrieve Data</button>

<p>The retrieved data from the LocalStorage: @storedData </p>

@code {
    private const string dataKey = "localStorageKey";

    private string? storedData;
    private string? inputData;

    private async Task StoreData()
    {
        if(!string.IsNullOrWhiteSpace(inputData))
        {
            await localStorage.SetItemAsync(dataKey, inputData);
            inputData = "";
        }
    }

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await RetrieveData();
        }
    }

    private async Task RetrieveData()
    {
        storedData = await localStorage.GetItemAsync<string>(dataKey);
    }
}

In the code snippet above, the @inject Blazored.LocalStorage.ILocalStorageService localStorage injects the local storage service to interact with the browser's local storage. The @rendermode RenderMode.InteractiveServer specifies that the page should be rendered as an interactive server-side component. Without the interactive server, the page will not be interactive.

The input field binds to inputData using the @bind-value attribute, allowing users to enter data they wish to store. The dataKey is a constant variable used to store and retrieve data from local storage. The storedData and inputData variables are used to hold the data to be stored and retrieved.

The StoreData method checks to see if inputData is not empty. If not, it stores it in local storage using dataKey, and clears the input field.

OnAfterRenderAsync is triggered after the component's first render. It retrieves data from local storage to ensure that data persists even after the page is reloaded.

RetrieveData retrieves data from local storage and assigns it to storedData for display.

The video above explains how to store and retrieve data stored in localstorage on the client-side.

Advanced Features and Techniques

In this section, we'll talk about how you can set an expiration date on your data, and how the stored data can be encrypted and decrypted for security.

How to Manage the Expiration of Stored Data

To manage the expiration of your stored data, you will create a helper class that stores data along with an expiration timestamp. Create a file called StorageItem.cs which will contain the code below:

public class StorageItem<T>
{
    public required T Data { get; set; }
    public DateTime Expiry { get; set; }
}

The code snippet above is a StorageItem<T> class, which is a generic class that can hold data of any type T and an expiry date DateTime. The Data property is required to be set when an instance of StorageItem is created or initialized, ensuring that it always has a valid value. The Expiry property represents the expiration date of the stored data.

Next, you'll create a file which will be a class that contains methods to set and get from the LocalStorage, with an expiration time. Create a file called LocalStorageHelper.cs:

using Blazored.LocalStorage;

namespace BlazorApp9.Components.Helpers;

public static class LocalStorageHelper
{
    public static async Task SetItemAsyncWithExpiry<T>(ILocalStorageService localStorageService, string key, TimeSpan expiry, T data)
    {
        StorageItem<T> storageItem = new StorageItem<T>
        {
            Data = data,
            Expiry = DateTime.UtcNow.Add(expiry)
        };

        await localStorageService.SetItemAsync(key, storageItem);
    }

    public static async Task<T?> GetItemAsyncWithExpiry<T>(ILocalStorageService localStorageService, string key)
    {
         var storageItem = await localStorageService.GetItemAsync<StorageItem<T>>(key);

        if(storageItem is null) {
            return default;
        }

        if (storageItem.Expiry < DateTime.UtcNow)
        {
            await localStorageService.RemoveItemAsync(key);
            return default;
        }
        return storageItem.Data;
    }
}

In the code above, you can see the necessary using directive for the Blazored.LocalStorage library. It provides easy access to the browser's local storage from Blazor applications.

This is followed by the declaration of the namespace BlazorApp9.Components.Helpers. This organizes the code and indicates that this helper is part of a specific component's helpers within the Blazor application.

Next, the LocalStorageHelper class is defined as a static class. A static class is one that cannot be instantiated and can only contain static members (using non static methods or properties will not be accepted).

Within the LocalStorageHelper class, two static asynchronous methods are defined: SetItemAsyncWithExpiry and GetItemAsyncWithExpiry.

The SetItemAsyncWithExpiry method is responsible for storing an item in the local storage with an associated expiry time. It accepts an ILocalStorageService instance for interacting with local storage, a key string to identify the stored item, a TimeSpan value representing the expiry duration, and the actual data to be stored.

Inside the method, a StorageItem<T> object is created, where T is the type of data being stored. This object includes the data and the expiry time, which is calculated by adding the specified TimeSpan to the current UTC time.

This StorageItem object is then serialized and saved in local storage under the given key using the SetItemAsync method of ILocalStorageService.

The GetItemAsyncWithExpiry method is responsible for retrieving an item from local storage and checking if it has expired. It also accepts an ILocalStorageService instance and a key string.

This method attempts to retrieve the stored StorageItem<T> object using the key. If the retrieved item is null, it returns the default value for the type T (typically null for reference types and zero or equivalent for value types).

If the item is found but its expiry time is earlier than the current UTC time, it means the item has expired. In this case, the item is removed from the local storage using the RemoveItemAsync method of ILocalStorageService, and the method returns the default value for T. If the item is valid and has not expired, the method returns the stored data.

How to Implement Encryption and Decryption

In this section, we will explore a utility file that provides encryption and decryption functionalities for a Blazor application.

The EncryptionHelper.cs class includes methods for encrypting and decrypting strings, as well as methods for serializing objects to JSON (Javascript Object Notation) and then encrypting them. This ensures that sensitive data can be securely stored and transmitted.

Let’s dive into the code to understand how these methods work and how you can use them. Add the following code for this file:

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

namespace BlazorApp9.Components.Helpers;

public static class EncryptionHelper
{
    private static readonly string EncryptionKey = "your-encryption-key";

    private static byte[] GetKeyBytes(string key)
    {

        byte[] keyBytes = Encoding.UTF8.GetBytes(key);
        Array.Resize(ref keyBytes, 32);
        return keyBytes;
    }

    public static string Encrypt(string plainText)
    {
        byte[] iv = new byte[16];
        byte[] array;

        using (Aes aes = Aes.Create())
        {
            aes.Key = GetKeyBytes(EncryptionKey);
            aes.IV = iv;

            ICryptoTransform encryptor = aes.CreateEncryptor(aes.Key, aes.IV);

            using (MemoryStream memoryStream = new MemoryStream())
            {
                using (CryptoStream cryptoStream = new CryptoStream((Stream)memoryStream, encryptor, CryptoStreamMode.Write))
                {
                    using (StreamWriter streamWriter = new StreamWriter((Stream)cryptoStream))
                    {
                        streamWriter.Write(plainText);
                    }

                    array = memoryStream.ToArray();
                }
            }
        }

        return Convert.ToBase64String(array);
    }

    public static string Decrypt(string cipherText)
    {
        byte[] iv = new byte[16];
        byte[] buffer = Convert.FromBase64String(cipherText);

        using (Aes aes = Aes.Create())
        {
            aes.Key = GetKeyBytes(EncryptionKey);
            aes.IV = iv;

            ICryptoTransform decryptor = aes.CreateDecryptor(aes.Key, aes.IV);

            using (MemoryStream memoryStream = new MemoryStream(buffer))
            {
                using (CryptoStream cryptoStream = new CryptoStream((Stream)memoryStream, decryptor, CryptoStreamMode.Read))
                {
                    using (StreamReader streamReader = new StreamReader((Stream)cryptoStream))
                    {
                        return streamReader.ReadToEnd();
                    }
                }
            }
        }
    }

    public static string SerializeAndEncrypt<T>(T data)
    {
        var jsonString = JsonSerializer.Serialize(data);
        return Encrypt(jsonString);
    }

    public static T DecryptAndDeserialize<T>(string cipherText)
    {
        var json = Decrypt(cipherText);
        return JsonSerializer.Deserialize<T>(json);
    }
}

The EncryptionHelper class is a static helper class designed for encrypting and decrypting data. This is particularly useful for securing sensitive information in a Blazor application.

The class above defines a static readonly field EncryptionKey which holds the encryption key. This key is crucial for both the encryption and decryption processes. It's important to use a strong and securely stored key.

The GetKeyBytes method converts the string key into a byte array and ensures its length is 32 bytes. This is because the AES encryption algorithm requires a 256-bit key, which is 32 bytes long.

The Encrypt method encrypts a plaintext string using AES encryption. It first creates an initialization vector (IV) of 16 bytes, which is required by the AES algorithm. The method then sets up an AES object with the encryption key and IV, and uses a CryptoStream to write the encrypted data to a memory stream. This encrypted data is then converted to a base64 string for easy storage and transmission.

The Decrypt method performs the reverse operation. It converts a base64 string back to a byte array, sets up the AES object with the same key and IV, and uses a CryptoStream to read the decrypted data from the memory stream. The result is the original plaintext string.

The EncryptionHelper class provides two methods for handling complex data structures: SerializeAndEncrypt and DecryptAndDeserialize. The SerializeAndEncrypt method first serializes an object to a JSON string using JsonSerializer.Serialize, and then encrypts this JSON string using the Encrypt method. This allows complex objects to be securely stored in an encrypted format.

The DecryptAndDeserialize method decrypts an encrypted JSON string back into its original form and then deserializes it into an object of type T using JsonSerializer.Deserialize. This combination of decryption and deserialization ensures that complex data can be securely retrieved and used within the application.

How to Connect the Expiration and Encryption to the User Interface

Now we'll walk through a Blazor component (Home.razor) that allows users to store and retrieve encrypted data in the browser's local storage. This ensures that sensitive information is protected and automatically expires when no longer needed.

This approach combines the ease of local storage with the security of encryption, providing a robust solution for managing user data in web applications. Let's dive into the code to see how it works.

 @page "/"
@using BlazorApp9.Components.Helpers

@inject Blazored.LocalStorage.ILocalStorageService localStorage
@rendermode RenderMode.InteractiveServer

<h3>Local Storage Example</h3>

<input @bind-value="@inputData" />

<button @onclick="StoreData">Store Data</button>
<button @onclick="RetrieveData">Retrieve Data</button>

<p>The retrieved data from the LocalStorage: @storedData </p>

@code {
    private const string dataKey = "localStorageKey";

    private string? storedData;
    private string? inputData;

    bool isDataLoaded = false;

    private async Task StoreData()
    {
        if (!string.IsNullOrWhiteSpace(inputData))
        {
            string encryptData = EncryptionHelper.SerializeAndEncrypt(inputData);
            await LocalStorageHelper.SetItemAsyncWithExpiry(localStorage, dataKey, TimeSpan.FromMinutes(30), encryptData);
            inputData = "";
        }
    }

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && !isDataLoaded)
        {
            await RetrieveData();
            isDataLoaded = true;
            StateHasChanged();
        }
    }

    private async Task RetrieveData()
    {
        string encryptData = await LocalStorageHelper.GetItemAsyncWithExpiry<string>(localStorage, dataKey);
        storedData = encryptData != null ? EncryptionHelper.DecryptAndDeserialize<string>(encryptData) : "Data not found or expired.";
    }
}

In the code above, the StoreData method checks if inputData is valid, encrypts it using EncryptionHelper.SerializeAndEncrypt, and stores it in local storage with a thirty-minute expiry using LocalStorageHelper.SetItemAsyncWithExpiry. The input field is then cleared.

The OnAfterRenderAsync method retrieves data from local storage after the component's initial render. This ensures previously stored data is loaded when the page first displays. It runs once, setting isDataLoaded to true and calling StateHasChanged to update the user interface (UI).

The RetrieveData method fetches data from local storage using LocalStorageHelper.GetItemAsyncWithExpiry. If the data is found and valid, it decrypts and deserializes it using EncryptionHelper.DecryptAndDeserialize. If not, it sets storedData to "Data not found or expired."

The video above demonstrates how you can implement the concepts discussed in this guide in a web application.

Conclusion

Blazored.LocalStorage offers a powerful and easy-to-use solution for managing user information in Blazor applications. Its integration brings numerous benefits, including enhanced state management, improved performance, and a better user experience.

After reading through this article and trying out the code for yourself, you should be able to incorporate local storage capabilities into any Blazor project. This will help you unlock the full potential of client-side storage in your web applications.

In this article, we'll explore:

• What LINQ is.
• How to use it.
• Examples of some common LINQ methods.

Table of Contents

• Language Level Query Syntax
• Method Syntax
• Common LINQ API Methods
  • OrderBy Method
  • First Method
  • Single/SingleOrDefault Method
  • Select Method
• How to Combine Methods
• Deferred Execution
• How to Chain IQueryable API Methods
• Conclusion

We'll be utilizing an Animal class in this article:

public class Animal
{
    public string Name { get; set; }
    public int Age {get;set;}
    public string Sound { get; set; }
}

Language Level Query Syntax

You may see something that resembles a SQL query in some code snippets. For example:

var animals = new List<Animal>
{
    new Animal { Name = "Dog", Age = 2, Sound = "Bark" },
    new Animal { Name = "Cat", Age = 2, Sound = "Meow" },
    new Animal { Name = "Fox", Age = 5, Sound = "Bark" }
};


var barkingAnimals =
    from animal in animals
    where animal.Sound == "Bark"
    select animal;

You can build queries similar to SQL for complex tasks, but this can be excessive. You can simplify these queries using the LINQ API methods syntax.

Method Syntax

The LINQ API methods utilizes a predicate (in the form of a lambda extension) to determine the criteria.

We can write the above query using the method syntax like so:

var barkingAnimals = animals.Where(x=> x.Sound == "Bark").ToList();

It's a lot easier to write and much more concise for such a simple query.

It reads a lot better too: barking Animals equals all the animals where the sound property equals Bark.

LINQ querying methods all return an IQueryable object. This informs the compiler that the variable is not the result of the query, but the definition of the query. [see deferred execution later in this article.]

In order to use the results of the query we can either:

• Iterate over the "queryable" object (for example: using a ForEach loop)
• Convert to an IEnunerable type. For example: a List/Array.

Common LINQ API Methods

OrderBy Method

OrderBy is a useful LINQ API method that lets you order any IEnumerable object.

We can use it like so:

var orderedByAge = people.OrderBy(x=>x.Age);

// or

var orderedByAgeDescending = people.OrderByDescending(x=>x.Age);

The above shows examples of ordering by Age in both ascending and descending order.

First Method

var first = animals.First(x=> x.Sound == "Bark");

This will return the first object from the list that matches the criteria.

Single and SingleOrDefault Method

This is used when you know/expect that there will be only one object that matches your criteria.

Example:

var cat = animals.Single(x=>x.Name == "Cat");

Data can change over time, leading to unexpected results. Writing defensive code is important. If multiple objects named "Cat" are found, an uncaught error will occur. To prevent this, use the SingleOrDefault method, which returns a default value (null for strings) on error. Then check if the cat variable is not null.

var cat = animals.SingleOrDefault(x=> x.Name=="Cat");

if(cat != null){
  Console.WriteLine("A single cat was found");
}

Select Method

Let's say that you wish to return only the types of animal, from the Animal object. This can be accomplished with the Select method. This will create a new object for each element in the list/array.

var typesOfAnimal = animals.Select(x=>x.Name).ToList();

But what if you want to return their name and sound? That's just as easy with the Select method. However, you'll have to create an anonymous object instead of just returning the property.

var animals = animals.Select(x=> { Name = x.Name, 
Noise = x.Sound}).ToList();

This should now return a list of anonymous objects, with a Name and a Sound property.

How to Combine Methods

Using the People class:

public class Person
{
    public string Name { get; set; }
    public string Address { get; set; }
}

var people = new List<Person>()
{
    new() { Name = "Harry Potter", Address = "123 Privet Drive, Hogwarts, United Kingdom" },
    new() { Name = "Alex the Kidd", Address = "Rock Paper Scissors Avenue, United Kingdom" },
    new() { Name = "Donkey Kong", Address = " The Monkey Temple, Jungle" }
};

You can combine LINQ API methods to carry out multiple actions. Take the following scenario as an example:

We want to find all the people in a list whose address contains "United Kingdom".

To accomplish this, you can utilize a combination of Where()and Contains(), passing the Contains() function as part of the predicate.

var ukResidents = peopleList.Where(p => p.Address.Contains("United Kingdom")).ToList();

Deferred Execution

LINQ queries use what's called deferred execution. This means that the query will not be executed immediately when it is defined.

Instead, it is executed when the query results are iterated or when certain operators trigger the execution explicitly. This deferred execution enables optimizations and improves performance by avoiding unnecessary computations.

This goes back to what I discussed earlier with the conversion of IQueryable to another object. For example, a list using .ToList(). It's the ToList()that converts the IQueryable object to a list and actually executes the query.

Lets take a look at an example:

var people = new List<Person>()
{
    new() { Name = "Harry Potter", Address = "123 Privet Drive, Hogwarts, United Kingdom" },
    new() { Name = "Alex the Kidd", Address = "Rock Paper Scissors Avenue, United Kingdom" },
    new() { Name = "Donkey Kong", Address = " The Monkey Temple, Jungle" }
};

// then we'll define the query
var peopleCalledHarryPotter = people.Where(x => x.Name == "Harry Potter");

// this will create the query object, You could write other code here.

// now convert the IQueryable query object to a List, thus invoking the actual query.

var list = peopleCalledHarryPotter.ToList();

Though a basic example, this demonstrates that you can create a queryable object and execute additional code before actually running the query using the .ToList() extension method.

How to Chain IQueryable API Methods

Similar to combining Where and Contains, you can further enhance your queries by chaining LINQ API methods.

For example, using Where() and GroupBy() together allows you to filter and then group data by a property.

Let's apply what we've learned and chain these methods. Instead of using .ToList() to create a new variable with the results, we can utilize the query object within a ForEach loop to execute the query and iterate over the results simultaneously.

Update the Person class to have a Age property:

public class Person
{
    public string Name { get; set; }
    public string Address { get; set; }    
    public int Age { get; set; }
}

Then look at the following code, which will first filter the list of people, and then group them based on Age.

using System;
using System.Collections.Generic;
using System.Linq;

public class Program
{
    public static void Main()
    {
        List<Person> people = new List<Person>
        {
            new Person { Name = "John", Age = 30 },
            new Person { Name = "Alice", Age = 25 },
            new Person { Name = "Bob", Age = 30 },
            new Person { Name = "Charlie", Age = 25 },
            new Person { Name = "Eve", Age = 35 }
        };

        var groupsOfPeople = people
            .Where(p => p.Age >= 30)  // Filter people with age >= 30
            .GroupBy(p => p.Age);    // Group people by their age

        foreach (var group in groupsOfPeople)
        {
            Console.WriteLine($"Age Group: {group.Key}"); // output the Age
            foreach (var person in group)
            {
                Console.WriteLine($"Name: {person.Name}, Age: {person.Age}");
            }
        }
    }
}

This combination of LINQ methods allow us to define more complex quieries without using the Language Level Query Syntax.

Sometimes it can based on personal preference, but I believe the method syntax is much more readable.

Conclusion

In this article, we've explored the power of LINQ in .NET, comparing its language-level query syntax and method syntax. We've demonstrated how to simplify complex queries using LINQ API methods and discussed common methods like OrderBy, First(), Single(), SingleOrDefault(), and Select.

We highlighted the importance of writing defensive code and the concept of deferred execution, which optimizes performance. By combining and chaining LINQ methods, you can create complex, readable queries efficiently.

LINQ is a versatile tool that enhances your ability to handle data in .NET applications. Whether using query syntax or method syntax, LINQ provides a powerful way to write efficient and maintainable code.

You can find some useful examples on the Microsoft website here

As always I'd welcome comments, or discussion on the topic. You can follow me on Twitter

• Understanding mocking: Why it's necessary for building a robust testing strategy.
• Exploring some of the most common mocking libraries: Such as Moq, NSubstitute, FakeItEasy, and Rhino Mocks.
• Mastering mocking techniques: Using each of these libraries, equipping you with the knowledge to choose the best mocking tool for your needs.

The aim of this tutorial is to give you the knowledge to make up your own mind on which mocking library you prefer, so you can go forward and write some powerful tests in your application.

Prerequisites for this tutorial

1. Understanding of C# programming
2. Understanding of C# Unit Testing
3. An IDE (Rider, Visual Studio, and so on), or Code Editor (VS Code, Sublime Text, Atom, and so on)

Getting Started/Setup

To speed up the process, I've made a public GitHub repo available for this tutorial,. You can clone and use it on your local machine to follow along.

Simply navigate to this link and clone the repo to your local machine.

Quick refresher if you've forgotten to do that: go to the link above, and in the top right corner click "Code", and then copy the URL provided.

Find your local git folder, (if you don't have one, create one in your user root folder). Then in your preferred terminal navigate to your git older, and execute the following command.

// (replacing <url> with the url)
git clone <url>

A Brief Overview of the Application

The solution you've just cloned is a basic Web API project which references a class library with some Todo domain objects and services which will alter a list of todo items.

For the purpose of this tutorial, these elements are stored in an in-memory list, rather than connecting to a database. But you can use a database or other forms of data persistence methods.

However, for the purpose of this tutorial, we're less concerned with persisting the data, and more so around mocking this service.

What Is Mocking?

With mocking you won't tell the difference

Mocking in software development is the concept of simulating a behavior or returned object of a class, method or service that another part of the system under test depends on.

When testing a particular component or unit of code, it's often necessary to isolate it from its dependencies, such as databases, web services, or other classes, in order to ensure that the test focuses solely on the functionality of the unit being tested rather than concerning itself with external aspects of the code.

Mocking allow developers to create mock objects or dummy implementations of these dependencies that behave in a predetermined way, mimicking the behavior of the real objects.

By using mocked objects or methods, we can control the input and output of the dependencies. This makes it a lot easier to test different scenarios, where business logic is dependent on the outcome of a dependency.

Example

Let's say we have a API endpoint that calls a repository which connects to a database. Our API response type depends on the returned value from the repository: we either return a 400 or a 200 response from our API.

We can simply mock the repository return value, and test that our API returns the correct response in both scenarios without having to actually touch our database at all.

In essence, mocking helps developers write more reliable and efficient tests by isolating the code under test and providing predictable behaviour for its dependencies, thereby improving the overall quality of the software.

What Are the Benefits of Mocking?

Benefits

Code Isolation

As I've already explained, mocking dependencies allows for isolation of code for testing. By mocking the dependencies, you can assert the points of failure in the code under test, and not the dependencies themselves (unless you mock them incorrectly – which hopefully this tutorial will help you avoid).

Faster Testing

By replacing real dependencies with mocked implementations, testing can be performed faster. You're not battling with inconsistencies, unreliable or unpredictable outcomes from those dependencies. It eliminates the need for setting up and tearing down external sources, which can sometimes be complex and time consuming.

Deterministic Testing

Mock objects offer a controlled environment, allowing developers to specify the exact behavior and responses of dependencies. This approach means that the tests are consistent, making it easier to find bugs and debug issues, especially those adopting a TDD (Test Driven Development) approach.

Parallel Testing

Mocking enables parallel testing (multiple tests being ran at the same time) by removing dependencies on external resources that may be limited or inaccessible during testing.

For example if you weren't mocking your database connection layer, trying to run tests in parallel may cause inconsistent pass/fail metrics, as another test could be affecting the database table you're utilizing in another test. Mocking this layer means your tests are now agnostic to this layer, and can be ran at the same time.

Reduced Test Maintenance

Since mock objects encapsulate the behavior of dependencies, changes to those dependencies do not necessarily require updates to the tests themselves. This reduces the maintenance overhead associated with evolving codebases and dependencies.

Enhanced Test Coverage

Mocking allows developers to simulate a wide range of scenarios and edge cases. By controlling the behavior of dependencies, developers can ensure that their tests exercise all relevant paths through the code, removing any real life or physical limitations.

Things To Be Aware of With Mocking

Complexity: Sometimes when mocking/testing complex areas of the application, mocking can also become complex. However, if the system is too difficult to mock, you may need to reassess your architecture.

Learning Curve: It requires an understanding of the syntax and concepts of the mocking library, which can be challenging for developers who are new to unit testing or the specific framework.

Over-specification: Mocking can lead to over-specifying the behavior of the code under test. This means that tests may become tightly coupled to the implementation details, making them brittle and prone to breaking when the implementation changes. It's essential to strike a balance between verifying behavior and focusing on the desired outcomes.

Be mindful of false-positive tests: While mocking allows you to isolate units of code, it may also create a false sense of security. Mocks simulate dependencies, but they may not fully replicate the behaviour of the real dependencies. Integration tests or end-to-end tests are still necessary to verify the system's behavior as a whole.

Popular .NET Mocking Libraries

Here are some popular .NET testing libraries:

• FakeItEasy
• NSubstitute
• Moq
• Rhino Mocks

These are just a list of the most commonly used .NET mocking libraries available online, but there are many more. I'd highly recommend using one of these as they have a larger community, more reputable code base, and good documentation (vital when starting out).

Each of these mocking libraries have their own syntax for creating mocks of objects however they all follow the same principles.

1. Declare the object/type/service you'd like to mock
2. How you want that object/type/service to run (the implementation)
3. What is the returned value (where necessary).

Looking at the Tests

If you open the solution, and navigate to the "Test" project, you can see that we have four files with each of the different mocking library tests in there.

1. FakeItEasyApiTests.cs
2. MoqApiTests.cs
3. NSubstituteApiTests.cs
4. RhinoMocksApiTests.cs

Within these files, you will see that we have four very basic XUnit tests. I've kept them brief and simple for the purpose of this tutorial.

Deep Dive Into the Test Structure

Each test file uses a constructor to initialize a private version of their respectable services, and you can see how these differ from one library to the next, yet still follow the same concepts.

// FakeItEasy
 _fakeTodoService = A.Fake<ITodoService>();

// NSubstitute
  _substituteTodoService = Substitute.For<ITodoService>();

// Moq
 _mockTodoService = new Mock<ITodoService>();

// Rhino Mocks
 _mockTodoService = MockRepository.GenerateMock<ITodoService>();

Choosing the "right" mocking library all comes down to personal preference, and what you feel is easier to write, work with and read/understand.

Some may find the use of words like Fake, or Substitute.For easier to comprehend or read. Whereas others may find the A.Fake unintuitive and prefer new Mock<type> more obvious.

Arrange, Act and Assert

Following the testing principle of AAA (Arrange, Act and Assert) we can carefully structure our tests, making it obvious what we're doing and where.

The AAA approach to testing involves three steps:

1. Arrange: Set up the test environment, mocked services/external dependencies.
2. Act: Perform the action being tested.
3. Assert: Verify the expected outcome.

Using Mocks to Simulate Returned Items

Let's test the getAll (GetAllTodoItems) endpoint by mocking the TodoService.GetAllTodos method to return a stubbed list of tasks.

This approach eliminates the need to set up and seed a database for each test scenario, ensuring focused testing of API endpoint returning values against specific criteria.

Mocks provide an ideal solution, allowing us to simulate the desired behavior without interference from other tests.

We can do this like so (remember the full code is available in the repo):

// FakeItEasy
A.CallTo(() => _fakeTodoService.GetAllTodos()).Returns(expectedTodos);

// NSubstitute
 _substituteTodoService.GetAllTodos().Returns(expectedTodos);

 // Moq
 _moqTodoService.Setup(s => s.GetAllTodos()).Returns(expectedTodos);

 // Rhino Mocks
 _mockTodoService.Stub(s => s.GetAllTodos()).Return(expectedTodos);

What are these methods doing?

A common feature you will see across the majority of libraries is the usage of lambda functions to dictate which method is being mocked.

The lambda function provided in the setup method is essentially a configuration step that defines what action should be taken when the mocked method is called. This configuration is stored and applied when the mocked method is invoked during the test.

Let's break it down, what we're doing:

1. The lambda specifies which method on the mocked service we wish to configure/setup.

2. The lambda we pass in isn't ran straight away by the setup method. We're not telling the test to run the method immediately; we're saying, "Remember this instruction/setup for when the actual method is called during the test."

3. When the method we're mocking gets called during the test then it checks if the call signature matches a setup configuration we've provided. If it matches, the test follows the instructions given during setup.

Important Notes:

NSubstitute, on the other hand, allows the developer to mock the method directly on the fake object. This means that you can access the fake GetAllTodos method and simply set the return value to your expected value.

Although Moq uses a Setup method, it differs ever so slightly from the other methods. Moq internally creates a proxy object that represents the mocked object, and exposes a .Object property to access it. We'll see how this works in the next part.

How to Call The System Under Test (SUT)

// FakeItEasy
var sut = new TodoController(_fakeTodoService);

// NSubstitute
var sut = new TodoController(_substituteTodoService);

// Moq -- slightly different to the others
 var sut = new TodoController(_moqTodoService.Object);

// Rhino Mocks
var sut = new TodoController(_mockTodoService);

In three of the four libraries, you can pass the mocked object directly. However, Moq requires accessing the .Object property on the mock to use it. Thus, we passed moqTodoService.Object as an argument to the controller.

an image showing that all the tests passed

Running the tests, you can see they all pass. Should you change any of the code in the repository, it would not make any difference as the repo is mocked in these tests. Have a go, try changing the repo functionality and re-running the tests, they will continue to pass.

We are concentrating on the functionality of the endpoint, not what the mocked repo is doing, and this is the beauty of mocking.

The Options with Mocking Are Endless

Mocking doesn't just allow us to set what is returned from a mocked object, it can also allow us to mock the implementation, including the ability to throw specific errors so we can test our API error handling and unhappy paths too.

This is illustrated in the Delete_Returns500_AndErrorMessageThrown_WhenExceptionThrown test within each library test file.

// FakeItEasy
A.CallTo(() => _fakeTodoService.Delete(1)).Throws(new Exception(errorMessage));

// NSubstitute
_substituteTodoService.When(x => x.Delete(1)).Do(x => throw new Exception(errorMessage));

// Moq
_moqTodoService.Setup(s => s.Delete(1)).Throws(new Exception(errorMessage));

// Rhino Mocks
 _mockTodoService.Stub(s => s.Delete(1)).Throw(new Exception(errorMessage));

Using the different libraries, we can make the Delete method on the service throw whatever exception we'd like to. This is ideal for when you want to return different status codes, or handle errors in different ways depending on the type of exception thrown.

As an example we could change Throws(new Exception(errorMessage) to Throws(new UnauthorizedAccessException() and test that if a 401 status code is returned when thrown.

Global Setup

You can assign multiple configurations to the same method. This is great in situations where you want to set up all your configurations of the mocked object in one place. For example, in the test class constructor.

In some test frameworks (like NUnit) you can use a [OneTimeSetUp] attribute above your method, which is ran before your test cases, or simply use your test class constructor.

In this scenario you could do something (in Moq) like:

public MoqApiTests()
{
        _mockTodoService = new Mock<ITodoService>();
        _mockTodoService.Setup(x => x.Delete(1)).Throws(new Exception("This is a generic exception"));
        _mockTodoService.Setup(x => x.Delete(2)).Throws(new UnauthorizedAccessException("You cannot perform this action on this item"));
}

In this example, we demonstrate setting up mocked service calls to the same method with various arguments, each causing it to throw different exceptions.

This approach is beneficial for testing different outcomes when different exceptions occur in separate tests, without cluttering our test code with repetitive setup.

For example:

// Test 1
var result = TodoController.Delete(1);
// Assert handles general exception

// Test 2
var result = TodoController.Delete(2); 
// Assert handles UnauthorizedAccessException

I prefer to set up mocks within each individual tests to ensure there are no external factors influencing the mock.

This way, I can easily identify what is being mocked within the test without searching for the mocked object and setup elsewhere.

What If I Don't Care What I'm Passing In?

In our deletion examples, we consistently passed an ID to the mock implementation. Consequently, if we were to call the method with a different ID like 101 through the TodoController.DeleteTodoItem call, we wouldn't receive the same result.

This is because we explicitly instructed the mocked object to throw an error when the stubbed method is called with an ID of 1.

To address this issue, we can be less specific. Each library has its own syntax for this, enabling us to specify that if any integer is passed to the method, it will throw a particular exception.

// FakeItEasy
A.CallTo(() => _fakeTodoService.Delete(A<int>._)).Throws( new Exception(errorMessage));

// NSubstitute
_substituteTodoService.When(x => x.Delete(Arg.Any<int>())).Do(x => throw new Exception(errorMessage));

// Moq
_mockTodoService.Setup(s => s.Delete(It.IsAny<int>())).Throws(new Exception(errorMessage));

// Rhino Mocks
_mockTodoService.Stub(s => s.Delete(Arg<int>.Is.Anything)).Throw(new Exception(errorMessage));

This code indicates that when any argument of type int is passed, it should throw this exception.

NSubstitute differs slightly in syntax: it requires explicit instruction to throw the specified error when encountering this scenario, unlike when were were informing it to return an object. This difference stems from the internal mechanisms of the library.

Asserting Mocks Are Called

In some cases, you might want to verify that a mocked service is called with the correct arguments. This is particularly useful when dealing with a "fire-and-forget" service.

In this scenario, your API endpoint is called, and while it always returns true, it also triggers a service to perform some action independently, which doesn't affect the API's return type (perhaps an asynchronous notification service).

This is one of the few instances where you may want to perform a quick sanity check to ensure that your "fire-and-forget" service is invoked (although ideally, you'd conduct an integration test with that service).

If you take a look at the DeleteTodoItem endpoint, and the DeleteAPI_CallsNotificationService_WithTaskId_AndUserId test within each test file you can see full examples of how this can be done.

We are verifying that when we call the DeleteTodoItem, on our happy path, the NotificationService.NotifyUserTaskCompleted is called with the ID of the item for deletion, and the hard-coded user ID.

As an exercise, you could create a user service which returns an ID of logged in user, and this can be used to pass the ID to the service. This can also be mocked in the test.

 // FakeItEasy
  A.CallTo(() => _fakeNotificationService.NotifyUserTaskCompleted(1,1)).MustHaveHappened(1, Times.Exactly);

// NSubstitute _notificationService.Received().NotifyUserTaskCompleted(1,1);

// Moq 
 _moqNotificationService.Verify(x => x.NotifyUserTaskCompleted(1,1)); // Defaults to Times.AtLeastOnce

// Rhino Mock
_mockNotificationService.AssertWasCalled(x=>x.NotifyUserTaskCompleted(1,1));

Conclusion

In conclusion, the versatility of mocked objects offers a myriad of applications, proving indispensable in the testing of individual units of code.

While I've covered several functionalities and validations achievable with mocks, there are more, such as method call order and negative validation.

In my view, the choice of a mocking library for a project is subjective, with no definitive right or wrong option. While some libraries may offer more convenient extensions or clearer syntax, the decision ultimately boils down to personal preference.

My hope is that this tutorial has provided you with a glimpse into the world of mocking and shed light on the syntax variances across different libraries.

As always, don't hesitate to reach out (links in bio).

We just published a full course on the freeCodeCamp.org YouTube channel that will teach you the essential skills you need to build your own mobile applications using .NET MAUI.

Frank Liu created this course. Frank is a full stack developer with about 20 years of development experience.

Throughout the course, you will learn how to create a Contacts app from scratch, using .NET MAUI. You will start with an introduction to .NET MAUI and learn how it compares to Xamarin Forms. Next, you will set up your development environment and create your first project.

From there, the course will guide you through the project structure, the three elements of stateful .NET MAUI, and page, layout, and view namespaces. You will also learn about URL-based navigation and the basics of ListView and data binding.

The course will then dive deeper into ListView and cover events handling, parameters in URL-based navigation, and using static repositories. You will also learn about stack layout for the Edit Contact page and view contact details, and update contact information.

In addition, the course covers more advanced topics such as Observable Collection, field validation with .NET MAUI CommunityToolkit, and creating reusable controls. You will also learn about grid layout and context actions, as well as how to use MenuItems in ListView and add a SearchBar in .NET MAUI.

By the end of the course, you will have gained the skills and knowledge necessary to build your own mobile applications with .NET MAUI. This course is perfect for anyone looking to develop cross-platform desktop and mobile applications using .NET MAUI.

Watch the full course on the freeCodeCamp.org YouTube channel (3-hour watch).

We just published a coruse on the freeCodeCamp.org YouTube channel that will teach you the power of Minimal APIs in .NET 7 and build well-constructed endpoints with C#, .NET 7, and Swagger.

You'll gain a deep understanding of API basics, routing, dependency injection, and more, culminating in the ability to create well-constructed Minimal API endpoints.

Topics Covered

This comprehensive course will cover the following topics:

1. Why Minimal API? - Understand the advantages of using Minimal APIs in your projects and how they differ from traditional APIs.
2. Create Project - Set up a new project with .NET 7 and explore the differences between Minimal and Standard APIs in terms of project structure and files.
3. Program File Changes - Learn about the changes you'll need to make to your Program.cs file to accommodate Minimal APIs.
4. API Basics - Dive into the fundamentals of APIs, including requests, responses, and HTTP verbs.
5. Create First Endpoint - Build your first Minimal API endpoint using C# and .NET 7.
6. Route Parameters - Learn how to use route parameters in your Minimal API endpoints for more dynamic functionality.
7. Create Coupon Model and Coupon Store - Set up a data model and storage solution for a coupon system, which will be used in subsequent endpoints.
8. Get All Endpoint - Implement an endpoint to retrieve all coupons from the coupon store.
9. Get Individual Coupon - Develop an endpoint to fetch a specific coupon based on its unique identifier.
10. Create Coupon - Create an endpoint to add new coupons to the store.
11. Name Endpoints - Understand the importance of naming your endpoints and how to do so effectively.
12. Products and Accepts in Minimal API - Learn how to use the Produces and Accepts attributes to define supported media types in your Minimal API endpoints.
13. Dependency Injection in Minimal API - Explore the process of implementing dependency injection in your Minimal APIs to improve testability and maintainability.
14. Add DTOs - Implement Data Transfer Objects (DTOs) to separate your API's data representation from its internal data structures.
15. AutoMapper and Dependency Injection - Learn how to use AutoMapper to map data between your DTOs and data models, integrating it with dependency injection.
16. Fluent Validators - Implement validation logic for your DTOs using Fluent Validation.
17. Async Endpoints - Explore the benefits of asynchronous programming and how to create asynchronous endpoints in your Minimal API.
18. API Response - Learn how to create custom API responses and handle errors gracefully in your Minimal API.
19. Assignment - Put and Delete - Apply your newfound knowledge by implementing update (PUT) and delete (DELETE) endpoints in your coupon system.
20. Assignment Solution - Put and Delete Endpoints - Review the solutions for the PUT and DELETE endpoints assignment, comparing your implementation with the recommended approach.

Conclusion

Upon completing this course, you'll have a solid understanding of how to implement Minimal APIs in .NET 7, and build robust and efficient API endpoints.

Watch the course on the freeCodeCamp.org YouTube channel (2-hour watch).

We just published a course on the freeCodeCamp.org YouTube channel that will teach you how to to create a basic React application that leverages a .NET Web API Component written in C#.

In order to integrate React with a .NET Web API component this course utilizes the 'ASP.NET Core with React.js' project template from within the free version of Visual Studio 2022 (the community edition). The App that you will build enables users to rank items by dragging and dropping the items (displayed in a list) to a cell position on the ranking grid (the grid is positioned above the list of relevant items).

Each cell position on the grid denotes a ranking value. For example, the top left cell is position number 1 denoting the top ranked item and the cell positioned to the immediate right of this cell denotes the 2nd ranked item. This continues all the way to the bottom right cell which is the worst possible ranking position.

Coding this project will give you an insight into how to build a simple app using React on the front-end that leverages a .NET Web API component on the backend.

Gavin Lon created this course. He is an experienced software developer and teacher.

Here are all the sections covered in this course:

• Project Creation
• Create the Server-side .NET Web API Code in C#
• Create 'RankItems' React Component
• Create Navigation Functionality
• Write Code to Import Movie Images
• Write Code to Display Movie Images
• Write Code for 'RankingGrid' React Component
• Write Code for Drag and Drop Functionality
• Write Code for Ranking Albums
• Write Code for Initialising Ranking Items (Reload Button)

Watch the full course on the freeCodeCamp.org YouTube channel (2-hour watch).

I recently switched to VS Code for development of a dockerized .NET core app. But I then realized that there weren't many up-to-date articles about debugging dockerized .NET core applications in VS Code.

Source: GIPHY

So, here I am, writing this article. I hope that it'll help others like myself in debugging their dockerized .NET core applications in VS Code.

In this article we will discuss the following:

1. VS Code extensions for Docker
2. VS Code launch configurations
3. How to debug .NET core apps on your local Docker

VS Code Extensions for Docker

Although no extension is really required (for you hardcore minimalists) to debug containerzied .NET core applications, I'd still recommend that you install the Docker extension by Microsoft. It will make it easy to create, manage, and debug containerized applications from right within VS Code.

Honestly, ever since I've started using the extension, I don't use the Docker Desktop anymore.

VS Code Launch Configurations

Now, in order to debug dockerized .NET Core applications, we will need to create a VS code launch configuration.

In this section, I'll talk about two sorts of launch configurations: one for docker run and the other for docker compose.

Later on, we'll also look into the final launch configurations and understand them so that we know what we're doing.

Docker Run Launch Configuration

If you installed the Docker extension by Microsoft, this should be easy.

First, press "Ctrl + P" in VS code and type in > Docker:

Next, select "Docker: Initialize for Docker Debugging".

Then select ".NET: ASP.NET Core" as your application platform. Select "Linux" as your operating system.

And voilà! You should now have a "Docker .NET Core Launch" launch configuration.

Note that Docker extension will want to overwrite your existing dockerfile. If you don't let it, it won't create the launch configurations. I'd recommend that you backup your dockerfile, let the extension overwrite it, and then restore your original file.

Docker Compose Launch Configurations

Now we all know that real-life applications are never that simple! You would probably have a DB container, an app container, and a few other containers all connected together via a docker-compose configuration.

If that is the case, here is how you'll create your launch configurations.

First, open your workspace in VS Code. If you already have existing launch configurations, you can skip the next part.

Next, press "Ctrl + Shift + D" to switch to the "Run & Debug Tab".

Click on "create a launch.json file" and choose ".NET 5+ and .NET Core" (This will create a basic launch configuration for running your application without Docker).

Now, while your launch.json file is open, click on Add Configuration button in the bottom right corner of the editor.

Select "Docker: .NET Core Attach (Preview)" from the opened dropdown.

It should have added a new configuration called "Docker: .NET Core Attach (Preview)".

Voilà! Now you're ready to debug your dockerized .NET Core application in VS Code.

How to Understand Launch Configurations

Before we start debugging our application, let's look into the launch configurations a bit closer to understand how they work.

There should be two files in the .vscode folder, in the root of your workspace.

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "docker-build",
            "label": "docker-build: debug",
            "dependsOn": [
                "build"
            ],
            "dockerBuild": {
                "tag": "webapi:dev",
                "target": "base",
                "dockerfile": "${workspaceFolder}/src/Dockerfile",
                "context": "${workspaceFolder}",
                "pull": true
            },
            "netCore": {
                "appProject": "${workspaceFolder}/src/webapi.csproj"
            }
        },
        {
            "type": "docker-run",
            "label": "docker-run: debug",
            "dependsOn": [
                "docker-build: debug"
            ],
            "dockerRun": {},
            "netCore": {
                "appProject": "${workspaceFolder}/src/webapi.csproj",
                "enableDebugging": true
            }
        }
    ]
}

First, let's take a look at the tasks.json file. This file has list of tasks that might be required by some of the launch configurations to launch the application properly.

The task we want to look at is "docker-run: debug". This is the task called when you launch using the "Docker .NET Core Launch" configuration (as we'll see later).

This task has three properties that we need to understand:

• netCore.appProject: This property is .NET Core app-specific and just points to the project file of your app.
• netCore.enableDebugging: This is another .NET Core app-specific property which tells VS code to launch the app with debugging capabilities.
• dependsOn: This is a generic property that defines if a task depends on other tasks for its execution.

Secondly, we need to understand what the "docker-build: debug" task does.

In addition to the netCore and dependsOn properties, it has a dockerBuild object that controls the docker build command which is run by VS Code to launch a docker run app.

Properties of the dockerBuild object are quite similar to the arguments that you pass to the docker build command.

You can read about all the dockerBuild object properties here and tasks in general here.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Docker .NET Core Attach",
      "type": "docker",
      "request": "attach",
      "platform": "netCore",
      "sourceFileMap": {
        "/src": "${workspaceFolder}/src"
      }
    },
    {
      "name": "Docker .NET Core Launch",
      "type": "docker",
      "request": "launch",
      "preLaunchTask": "docker-run: debug",
      "netCore": {
        "appProject": "${workspaceFolder}/src/webapi.csproj"
      }
    }
  ]
}

Now, let's take a look at the launch.json file where all the launch configurations live.

While most of these properties are standard, the one we care about is "sourceFileMap" in the "Docker .NET Core Attach" configuration.

In order to debug .NET Core applications that were built on a machine other than the VS Code machine (in this case a Docker), VS Code needs to understand how-to map your current workspace to the build machine hierarchy.

For example, if my project was built from the "/src" folder in Linux, this property will tell VS Code to replace "/src" with "${workspaceFolder}/src" in all the filepaths. In case this mapping is incorrect, VS Code will hit the breakpoint but will give an error that the file (being debugged) does not exist.

You can read more about launch.json properties in detail over here.

How to Debug .NET Core Apps on Your Local Docker

Docker Run

Now that we have the launch configurations figured out, this should be easy! Just follow the steps below.

First, press "Ctrl + Shift + D" to switch to the "Run & Debug Tab".

Then choose "Docker .NET Core Launch" and press the green play icon to debug.

Docker Compose

Debugging a Docker Compose container is slightly different. You'll have to make sure that your Docker Compose containers are already running before you attach the VS Code debugger.

Once they are up, follow these steps:

First, press "Ctrl + Shift + D" to switch to the "Run & Debug Tab".

Then choose "Docker: .NET Core Attach (Preview)" and press the green play icon to debug.

That is, it! I hope you found this helpful. If you have any questions or are confused about anything, you can reach out to me or you can check out the sample project on GitHub.

Happy Coding!

This article is a part of my coding series. You may find other useful articles for your daily development there as well.

We just published a course on the freeCodeCamp.org YouTube channel that will teach you how to create a REST API using industry-level .NET code. You will learn how to write code similar to what they write at top tech companies.

Amichai Mantinband created this course. Amichai is a software engineer at Microsoft and before that he worked as a college computer science instructor.

This course is a concise, start-to-finish video that developers can use as a template to onboard/structure small to medium sized industry-level CRUD applications.

Here are the sections covered in this course:

• Backend server architecture
• Implementing logic of API model
• Refactoring routes
• Create model for request data
• Create service interface
• Implement additional methods
• Handling errors
• Refactoring controller and services
• Refactoring error handling
• Testing API requests

Watch the full course below or on the freeCodeCamp.org YouTube channel (1-hour watch).