Modern .NET: DI, Minimal APIs, and Practical Architecture

Quickstart

If you want the highest-impact improvements first, do these in order. Each step is “small enough to do today” but compounds quickly when you ship more endpoints.

Overview

ASP.NET Core makes it easy to start an API. The hard part is keeping it clean as it grows: more endpoints, more dependencies, more integration points, more “just one quick change” requests.

The goal is not “perfect architecture.” It’s an API that’s easy to reason about when you’re tired, shipping fast, and debugging a bug report with a screenshot and no reproduction steps.

Core concepts

Before the walkthrough, align on a few mental models. If these click, most .NET architecture decisions become simpler.

DI as a graph, not a “bag of services”

The built-in container assembles an object graph: classes depend on interfaces, and DI creates them in the right order. When your graph is healthy, constructors stay small, responsibilities stay narrow, and tests are easy.

The HTTP pipeline: middleware, endpoints, and cross-cutting rules

Your request flows through middleware (logging, errors, auth) and ends at an endpoint handler. Architecture is mostly deciding where logic lives: cross-cutting rules belong in middleware/filters, business rules belong in application/domain services.

Practical architecture: boundaries that pay rent

The most useful boundary in a service is: business logic doesn’t know infrastructure. That doesn’t mean you need 12 projects and three diagrams. It means a few disciplined rules:

Step-by-step

Let’s build a small API the way you’d want it to look after 6 months: Minimal APIs, DI that behaves, and a structure that doesn’t fight you. The examples below are intentionally compact, but the patterns scale to real services.

Step 1 — Scaffold a solution that can grow

Start with a clean solution layout. Even if you keep everything in one project initially, create a place for tests from day one. This makes refactoring toward stronger boundaries much easier later.

# Create solution + API project
dotnet new sln -n ModernNetSample
dotnet new web -n Api
dotnet sln add Api/Api.csproj

# Common API add-ons (optional, but practical)
dotnet add Api package Swashbuckle.AspNetCore

# Test project (integration-style)
dotnet new xunit -n Api.Tests
dotnet add Api.Tests reference Api/Api.csproj
dotnet add Api.Tests package Microsoft.AspNetCore.Mvc.Testing

# Run tests (should pass)
dotnet test

Step 2 — Keep Program.cs focused: compose, configure, map

Program.cs is where you wire up the app. The goal is to make it readable like a checklist: register services → configure middleware → map endpoints. Everything else should live elsewhere.

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);

// --- Service registration (DI) ---
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Example options binding (configuration -> typed options)
builder.Services.Configure<TodoOptions>(builder.Configuration.GetSection("Todo"));

// Application services (keep state out; make them testable)
builder.Services.AddScoped<TodoService>();

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

// --- Middleware pipeline ---
app.UseExceptionHandler("/error");
app.UseStatusCodePages();

app.UseSwagger();
app.UseSwaggerUI();

// --- Endpoints ---
app.MapGet("/health", () => Results.Ok(new { status = "ok" }))
   .WithName("Health");

var todos = app.MapGroup("/todos").WithTags("Todos");

todos.MapGet("/", async (TodoService svc, CancellationToken ct) =>
{
    var items = await svc.ListAsync(ct);
    return Results.Ok(items);
})
.WithName("ListTodos");

todos.MapPost("/", async (CreateTodoRequest req, TodoService svc, IOptions<TodoOptions> opts, CancellationToken ct) =>
{
    if (string.IsNullOrWhiteSpace(req.Title))
        return Results.BadRequest(new { error = "Title is required." });

    if (req.Title.Length > opts.Value.MaxTitleLength)
        return Results.BadRequest(new { error = $"Title must be <= {opts.Value.MaxTitleLength} chars." });

    var created = await svc.CreateAsync(req, ct);
    return Results.Created($"/todos/{created.Id}", created);
})
.WithName("CreateTodo");

// Centralized error shape (Problem Details)
app.MapGet("/error", (HttpContext ctx) =>
{
    var feature = ctx.Features.Get<IExceptionHandlerFeature>();
    var ex = feature?.Error;

    return Results.Problem(
        title: "Unhandled error",
        detail: ex?.Message,
        statusCode: StatusCodes.Status500InternalServerError);
});

app.Run();

// --- Simple request/response contracts ---
record CreateTodoRequest(string Title);
record TodoDto(Guid Id, string Title, bool Done);

sealed class TodoOptions
{
    public int MaxTitleLength { get; set; } = 120;
}

// --- Application service (placeholder implementation) ---
sealed class TodoService
{
    private static readonly List<TodoDto> _store = new();

    public Task<IReadOnlyList<TodoDto>> ListAsync(CancellationToken ct)
        => Task.FromResult((IReadOnlyList<TodoDto>)_store);

    public Task<TodoDto> CreateAsync(CreateTodoRequest req, CancellationToken ct)
    {
        var dto = new TodoDto(Guid.NewGuid(), req.Title.Trim(), false);
        _store.Add(dto);
        return Task.FromResult(dto);
    }
}

In a real service, you would replace the in-memory list with persistence, and you would move TodoService and DTOs into feature files. But the shape matters: endpoints are thin, DI is explicit, and errors are standardized.

Step 3 — Make architecture decisions that stay easy to follow

You don’t need a “big rewrite” to get good architecture. You need a few repeatable patterns that keep files small and responsibilities clear. Here’s a simple way to structure a Minimal API codebase:

Step 4 — Add testing that protects behavior, not implementation

The fastest confidence boost is an integration-style test that boots your API in-memory and calls endpoints with HTTP. This catches DI misconfigurations, routing mistakes, serialization issues, and behavior regressions—without over-mocking.

using System.Net.Http.Json;
using Microsoft.AspNetCore.Mvc.Testing;
using Xunit;

public class TodosApiTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public TodosApiTests(WebApplicationFactory<Program> factory)
    {
        // CreateClient boots the API in-memory (no real network).
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task Post_then_list_contains_created_item()
    {
        var create = await _client.PostAsJsonAsync("/todos", new { title = "Ship it" });
        create.EnsureSuccessStatusCode();

        var items = await _client.GetFromJsonAsync<TodoDto[]>("/todos");
        Assert.NotNull(items);
        Assert.Contains(items!, x => x.Title == "Ship it");
    }

    // Mirror the API response contract to keep tests stable.
    private record TodoDto(Guid Id, string Title, bool Done);
}

Notice what we didn’t test: private methods, internal data structures, or “did method X get called.” We tested the contract: if we POST a todo, we can later GET it. That’s the behavior your users care about.

Step 5 — Production habits: cancellation, consistency, and observability

These are “small” details that prevent big outages and painful debugging sessions later:

Common mistakes

These are the real-world footguns that show up in code reviews (and production incidents). The fixes are usually simple once you know the pattern.

FAQ

Should I use Minimal APIs or controllers?

Use Minimal APIs when you want low ceremony, explicit routing, and a slim surface area—especially for small-to-medium services and internal APIs. Controllers can still be a good fit when you rely heavily on MVC conventions, attributes, or existing controller-based tooling. The key is consistency: pick one approach per service and standardize patterns (validation, errors, authorization) across all endpoints.

What’s the “composition root” in modern .NET?

The composition root is the place where you wire your app together: DI registrations, configuration binding, middleware pipeline, and endpoint mapping. In ASP.NET Core, this is typically Program.cs. Keeping this explicit makes the rest of your code easier to test and reason about.

How do I choose DI lifetimes correctly?

Start from “who owns the state.” If something is request-specific (like database units of work), it’s usually scoped. If it’s stateless and thread-safe, it can be singleton. If it’s a light helper with no shared state, transient works. When unsure, default to scoped for services that touch IO and transient for small pure services.

How do I keep Minimal API projects organized as they grow?

Use route groups and feature modules. Each feature gets its own endpoint mapping method (or class) and its own request/response contracts. Endpoints call application services; application services call infrastructure via interfaces. This keeps Program.cs readable and prevents “God files.”

How should I handle validation and errors?

Validate inputs as close to the boundary as possible (request DTO validation) and return predictable errors. Standardize failures with Problem Details so clients and tests see a consistent shape. For domain/business errors, prefer explicit results (e.g., “not found”, “conflict”) mapped to 404/409 rather than throwing exceptions for control flow.

What’s a reasonable “clean architecture” for a small service?

Keep it pragmatic: feature folders, a small application layer for use-cases, and domain code that doesn’t depend on EF/HTTP. You can keep everything in one project as folders. Split into multiple projects only when boundaries stabilize and you benefit from separate build/deployment units.

How do I test Minimal APIs without over-mocking?

Use integration-style tests with an in-memory server (via WebApplicationFactory). This exercises routing, JSON, DI, and middleware. Keep a small number of unit tests for pure domain logic, but let HTTP tests protect the API contract.

Cheatsheet

A scan-fast checklist you can keep next to your editor. If you follow this consistently, you’ll avoid most “it got messy” outcomes.

Wrap-up

Modern .NET makes building APIs fast—but staying fast requires structure: DI lifetimes that make sense, Minimal API endpoints that stay thin, and an architecture boundary where business rules don’t depend on infrastructure.

If you want to reinforce the habits, re-skim the Cheatsheet after your next feature. It’s designed to catch “small drift” before it becomes a rewrite.

Related posts

• Go for Backend Devs: Concurrency, Context, and Clean APIs
• Python in 60 Minutes: From Zero to Useful
• Top 25 Python Errors (And the 1-Line Fixes)
• Python Dataclasses: Cleaner Models With Less Boilerplate
• Make Python Faster: 12 Micro-Optimizations That Matter
• Asyncio Explained With 3 Real Projects