public class OrderProcessor
{
    public void ProcessOrder(Order order)
    {
        var db = new SqlConnection("Server=prod-db;Database=Orders;...");
        db.Open();

        var cmd = new SqlCommand("INSERT INTO Orders ...", db);
        cmd.ExecuteNonQuery();

        var smtp = new SmtpClient("smtp.company.com");
        smtp.Send("orders@company.com", order.CustomerEmail,
            "Order Confirmation", $"Your order {order.Id} is confirmed.");

        var logger = new StreamWriter("C:\\Logs\\orders.log", append: true);
        logger.WriteLine($"{DateTime.Now}: Order {order.Id} processed.");
        logger.Close();

        db.Close();
    }
}

You need to add a feature. The business wants to send SMS notifications in addition to email. You also need to write a unit test for the existing logic. You stare at the code and realize that you cannot test ProcessOrder without a live SQL Server, a live SMTP server, and write access to C:\Logs\. You cannot swap the email notification for an SMS notification without rewriting the method. You cannot change the database without changing this class. Every single dependency is hardcoded. Every change requires modifying this class. Every test requires the entire production infrastructure.

This is the problem that the Dependency Inversion Principle exists to solve. Not just as an academic exercise, not just as a bullet point on a job interview whiteboard, but as a practical engineering tool that determines whether your code is a flexible asset or a brittle liability.

Part 1: The Origins — Where the Dependency Inversion Principle Came From

The Dependency Inversion Principle — universally abbreviated as DIP — is the "D" in SOLID. Before we can appreciate what it means, we need to understand where it came from and why Robert C. Martin felt it was important enough to formalize.

Robert C. Martin and the C++ Report

Robert Cecil Martin, known universally as "Uncle Bob," first articulated the Dependency Inversion Principle in a paper published in the C++ Report in May/June 1996. The paper was titled simply "The Dependency Inversion Principle," and it was the third in a series of columns Martin wrote on object-oriented design principles for that magazine. The earlier columns covered the Open-Closed Principle and the Liskov Substitution Principle.

Martin opened the paper by observing that most software does not start out with bad design. Developers do not intentionally create rigid, fragile, immobile code. Instead, software degrades over time as requirements change and modifications accumulate. He identified three symptoms of degraded design: rigidity (difficulty making changes because every change cascades through the system), fragility (changes cause unexpected breakages in seemingly unrelated parts), and immobility (inability to reuse modules in other contexts because they are entangled with their dependencies).

Martin argued that the root cause of all three symptoms is the same: high-level modules depend on low-level modules. In traditional structured programming — the kind taught in computer science programs throughout the 1970s and 1980s — the natural design approach is top-down decomposition. You start with the high-level policy ("process an order") and decompose it into lower-level details ("write to database," "send email," "log to file"). The result is a dependency graph where high-level modules import and call low-level modules directly. When the low-level details change — a new database, a different email provider, a different logging framework — the high-level policy must change too. The important stuff depends on the unimportant stuff.

Martin's insight was that this dependency direction should be inverted.

The SOLID Acronym

Martin collected the Dependency Inversion Principle together with four other design principles — Single Responsibility, Open-Closed, Liskov Substitution, and Interface Segregation — in his 2000 paper "Design Principles and Design Patterns." Around 2004, software engineer Michael Feathers noticed that the initials of these five principles spelled SOLID and coined the acronym. The name stuck. Today, SOLID is one of the most recognized concepts in software engineering, and DIP sits as its capstone.

Martin himself noted that DIP is not truly an independent principle. It is, in many ways, the structural consequence of rigorously applying the Open-Closed Principle and the Liskov Substitution Principle together. If your code is open for extension but closed for modification (OCP), and if your abstractions are substitutable (LSP), then your dependency arrows will naturally point toward abstractions rather than concrete details. DIP formalizes and names this pattern so that developers can reason about it explicitly.

Intellectual Ancestors

Martin did not invent the idea of depending on abstractions in a vacuum. The concept has roots in several earlier ideas. Bertrand Meyer's 1988 book "Object-Oriented Software Construction" introduced the Open-Closed Principle. Barbara Liskov's 1987 keynote at the OOPSLA conference (later formalized in a 1994 paper with Jeannette Wing) established the substitutability principle that bears her name. The Gang of Four's "Design Patterns" book (1994) showed dozens of patterns — Strategy, Observer, Factory, Template Method — that rely on programming to interfaces rather than implementations.

What Martin did was distill these ideas into a crisp, two-part formal statement and give it a name that made it memorable and teachable. That formal statement is what we will examine next.

Part 2: The Formal Definition — Two Rules That Change Everything

The Dependency Inversion Principle, as stated by Robert C. Martin in his 1996 paper, consists of two parts:

A. High-level modules should not depend on low-level modules. Both should depend on abstractions.

B. Abstractions should not depend on details. Details should depend on abstractions.

These two sentences are deceptively simple. Every word matters. Let us unpack them carefully.

What Are High-Level and Low-Level Modules?

A "module" in Martin's original C++ context is roughly equivalent to a class or a namespace in C#. The distinction between "high-level" and "low-level" is about proximity to business policy versus proximity to implementation detail.

High-level modules contain the business rules, the policy decisions, the orchestration logic — the stuff that makes your application uniquely valuable. In an e-commerce system, the high-level module is the order processing logic that decides when to charge a customer, when to send a confirmation, and when to initiate shipping. In a blog engine, the high-level module is the content pipeline that reads markdown, resolves front matter, and assembles the output.

Low-level modules contain the implementation details — the stuff that can be swapped out without changing the business policy. The specific database you write to. The specific email provider you use. The specific file system path where logs are written. The specific HTTP client that calls an external API.

The critical insight of Part A is that the direction of dependency should not follow the direction of the call. Just because the order processor calls the database does not mean the order processor should depend on the database. Both should depend on an abstraction — an interface or abstract class — that represents the concept of "storing orders" without specifying how.

What Are Abstractions and Details?

Part B makes a subtler point. It is not enough to introduce an abstraction. The abstraction itself must not be contaminated by details of any particular implementation.

Consider this interface:

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id);
    Task SaveAsync(Order order);
    SqlConnection GetConnection(); // Leaking detail!
}

The first two methods are proper abstractions — they describe what the repository does without revealing how. The third method violates Part B. It exposes SqlConnection, which is a detail of the SQL Server implementation. Any code that depends on IOrderRepository now transitively depends on System.Data.SqlClient. If you later want to implement the repository with PostgreSQL, MongoDB, or an in-memory store, every consumer of IOrderRepository must change.

A clean abstraction looks like this:

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id);
    Task SaveAsync(Order order);
    Task<IReadOnlyList<Order>> GetRecentAsync(int count);
}

Every method describes a business-level operation. No method reveals anything about the storage mechanism. The abstraction depends on the domain model (Order), not on infrastructure types (SqlConnection, DbContext, MongoCollection<T>).

Why "Inversion"?

Martin himself addressed this question directly in his paper. He explained that in traditional structured programming — the procedural, top-down decomposition approach that dominated software engineering through the 1970s and 1980s — the natural dependency direction is from high-level to low-level. You start with main(), which calls processOrders(), which calls writeToDatabase(). Each layer depends on the layer beneath it.

Object-oriented programming with DIP inverts this relationship. The high-level module defines the abstraction (the interface). The low-level module implements it. Both depend on the abstraction, but the abstraction lives with the high-level module, not the low-level one. The dependency arrow between the high-level module and the low-level module has been reversed — inverted — compared to what you would get from naive top-down design.

This is the "inversion." It is not about inverting the call direction (the high-level module still calls the low-level module at runtime). It is about inverting the compile-time dependency direction.

Part 3: DIP in Plain English — The Wall Outlet Analogy

If the formal definition feels abstract, here is an analogy that makes it concrete.

Think about the electrical outlet in your wall. Your laptop charger, your phone charger, your desk lamp, and your coffee maker all plug into the same outlet. The outlet does not know or care what is plugged into it. The coffee maker does not know or care whether the outlet is connected to a coal power plant, a solar panel, a wind turbine, or a nuclear reactor. Both the devices and the power sources depend on a shared abstraction: the electrical outlet standard (in the United States, NEMA 5-15).

Now imagine a world without this abstraction. Every appliance is hardwired directly to a specific power source. Your coffee maker has a copper wire that runs all the way to a specific coal plant in West Virginia. If that plant shuts down, your coffee maker stops working. If you want to switch to solar power, you need to buy a new coffee maker — one that is hardwired to a solar panel.

That hardwired world is what your code looks like when high-level modules depend directly on low-level modules. The electrical outlet standard is the interface. DIP says: make your code work like the real world works, with standardized outlets (interfaces) that decouple producers from consumers.

Another analogy that Martin himself used in his 1996 paper involves a button and a lamp. A Button object senses the external environment (whether a user pressed it). A Lamp object controls a light. Without DIP, the Button depends directly on the Lamp — it calls lamp.TurnOn() and lamp.TurnOff(). If you later want the same button to control a motor, a heater, or an alarm, you have to modify the Button class. With DIP, the Button depends on an abstraction — perhaps ISwitchableDevice — and the Lamp, Motor, Heater, and Alarm all implement that abstraction. The Button never changes.

Part 4: DIP Is Not Dependency Injection (But They Are Friends)

This is the single most common source of confusion, so let us address it directly.

Dependency Inversion Principle (DIP) is a design principle. It tells you how to structure the relationships between your modules. It says: depend on abstractions, not on concrete implementations. It is a rule about the direction of your dependency arrows.

Dependency Injection (DI) is a technique — a specific mechanism for providing dependencies to a class from the outside rather than having the class create them internally. Constructor injection, property injection, and method injection are all forms of DI.

Inversion of Control (IoC) is a broader design principle in which the flow of control is inverted compared to traditional programming. Instead of your code calling library code, library code calls your code (the "Hollywood Principle: don't call us, we'll call you"). DI is one implementation of IoC.

IoC Container (also called a DI Container) is a framework that automates dependency injection. In .NET, the built-in Microsoft.Extensions.DependencyInjection is an IoC container. Third-party options like Autofac, Ninject, and StructureMap are also IoC containers.

Here is how they relate:

• DIP is the principle (depend on abstractions).
• DI is the technique (pass dependencies in from outside).
• IoC is the architectural pattern (invert who controls the flow).
• IoC Container is the tool (automate the wiring).

You can follow DIP without using DI. For example, you could use the Factory pattern or the Service Locator pattern to provide abstractions to your high-level modules. You can use DI without following DIP — you can inject concrete classes directly without any interfaces. But in practice, DIP and DI work together beautifully. DIP tells you to program against interfaces. DI gives you a clean mechanism for providing the implementations at runtime. And an IoC container automates the plumbing so you do not have to wire everything up by hand.

Martin Fowler published an influential article in January 2004 titled "Inversion of Control Containers and the Dependency Injection pattern," which helped clarify the distinction between these concepts. In that article, Fowler actually coined the term "Dependency Injection" because he felt "Inversion of Control" was too generic — many things in software involve inverted control (event handlers, template methods, etc.), and he wanted a more specific name for the pattern of passing dependencies to a class.

Part 5: DIP in C# — From Theory to Code

Let us return to the order processing example from the introduction and refactor it step by step.

Step 1: Identify the Dependencies

The original OrderProcessor depends on three concrete things:

1. SqlConnection — for persisting orders to a database.
2. SmtpClient — for sending email notifications.
3. StreamWriter to a specific file path — for logging.

Each of these is a low-level implementation detail. The high-level policy — "when an order is placed, persist it, notify the customer, and log the event" — should not depend on any of them.

Step 2: Define Abstractions

We create interfaces that capture the business-level concepts without revealing implementation details:

public interface IOrderRepository
{
    Task SaveAsync(Order order, CancellationToken cancellationToken = default);
    Task<Order?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
}

public interface INotificationService
{
    Task SendOrderConfirmationAsync(
        Order order,
        CancellationToken cancellationToken = default);
}

public interface IOrderLogger
{
    void LogOrderProcessed(Order order);
    void LogOrderFailed(Order order, Exception exception);
}

Notice several things about these interfaces:

• They use domain language ("order confirmation," "order processed") rather than infrastructure language ("SMTP," "SQL," "file").
• They include CancellationToken parameters where appropriate, because cancellation is a concept that belongs at the abstraction level.
• They are small and focused. INotificationService does not also handle logging. IOrderRepository does not also handle notifications. This is the Interface Segregation Principle (the "I" in SOLID) working alongside DIP.
• They return and accept domain types (Order), not infrastructure types (SqlDataReader, MailMessage).

Step 3: Implement the Abstractions

Now we write concrete implementations for each interface:

public sealed class SqlOrderRepository : IOrderRepository
{
    private readonly string _connectionString;

    public SqlOrderRepository(string connectionString)
    {
        _connectionString = connectionString;
    }

    public async Task SaveAsync(Order order, CancellationToken cancellationToken = default)
    {
        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);

        await using var command = new SqlCommand(
            "INSERT INTO Orders (Id, CustomerId, Total, CreatedAt) " +
            "VALUES (@Id, @CustomerId, @Total, @CreatedAt)", connection);

        command.Parameters.AddWithValue("@Id", order.Id);
        command.Parameters.AddWithValue("@CustomerId", order.CustomerId);
        command.Parameters.AddWithValue("@Total", order.Total);
        command.Parameters.AddWithValue("@CreatedAt", order.CreatedAt);

        await command.ExecuteNonQueryAsync(cancellationToken);
    }

    public async Task<Order?> GetByIdAsync(
        Guid id, CancellationToken cancellationToken = default)
    {
        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);

        await using var command = new SqlCommand(
            "SELECT Id, CustomerId, Total, CreatedAt FROM Orders WHERE Id = @Id",
            connection);
        command.Parameters.AddWithValue("@Id", id);

        await using var reader = await command.ExecuteReaderAsync(cancellationToken);
        if (await reader.ReadAsync(cancellationToken))
        {
            return new Order
            {
                Id = reader.GetGuid(0),
                CustomerId = reader.GetGuid(1),
                Total = reader.GetDecimal(2),
                CreatedAt = reader.GetDateTime(3)
            };
        }

        return null;
    }
}

public sealed class EmailNotificationService : INotificationService
{
    private readonly SmtpClient _smtpClient;
    private readonly string _fromAddress;

    public EmailNotificationService(SmtpClient smtpClient, string fromAddress)
    {
        _smtpClient = smtpClient;
        _fromAddress = fromAddress;
    }

    public async Task SendOrderConfirmationAsync(
        Order order, CancellationToken cancellationToken = default)
    {
        var message = new MailMessage(
            _fromAddress,
            order.CustomerEmail,
            "Order Confirmation",
            $"Your order {order.Id} for ${order.Total:F2} is confirmed.");

        await _smtpClient.SendMailAsync(message, cancellationToken);
    }
}

public sealed class SerilogOrderLogger : IOrderLogger
{
    private readonly ILogger _logger;

    public SerilogOrderLogger(ILogger logger)
    {
        _logger = logger;
    }

    public void LogOrderProcessed(Order order)
    {
        _logger.Information(
            "Order {OrderId} processed for customer {CustomerId}, total {Total}",
            order.Id, order.CustomerId, order.Total);
    }

    public void LogOrderFailed(Order order, Exception exception)
    {
        _logger.Error(
            exception,
            "Order {OrderId} failed for customer {CustomerId}",
            order.Id, order.CustomerId);
    }
}

Step 4: Refactor the High-Level Module

Now the OrderProcessor depends only on abstractions:

public sealed class OrderProcessor
{
    private readonly IOrderRepository _repository;
    private readonly INotificationService _notificationService;
    private readonly IOrderLogger _logger;

    public OrderProcessor(
        IOrderRepository repository,
        INotificationService notificationService,
        IOrderLogger logger)
    {
        _repository = repository;
        _notificationService = notificationService;
        _logger = logger;
    }

    public async Task ProcessOrderAsync(
        Order order, CancellationToken cancellationToken = default)
    {
        try
        {
            await _repository.SaveAsync(order, cancellationToken);
            await _notificationService.SendOrderConfirmationAsync(
                order, cancellationToken);
            _logger.LogOrderProcessed(order);
        }
        catch (Exception ex)
        {
            _logger.LogOrderFailed(order, ex);
            throw;
        }
    }
}

Compare this to the original. The OrderProcessor no longer knows about SQL Server, SMTP, or the file system. It expresses the business policy: save the order, notify the customer, log the result. That is all it does. That is all it should do.

Step 5: Wire It Up

In an ASP.NET Core application, you register your services in Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Register abstractions with their implementations
builder.Services.AddScoped<IOrderRepository>(sp =>
    new SqlOrderRepository(
        builder.Configuration.GetConnectionString("Orders")!));

builder.Services.AddScoped<INotificationService>(sp =>
    new EmailNotificationService(
        new SmtpClient(builder.Configuration["Smtp:Host"]),
        builder.Configuration["Smtp:FromAddress"]!));

builder.Services.AddSingleton<IOrderLogger>(sp =>
    new SerilogOrderLogger(Log.Logger));

// Register the high-level module
builder.Services.AddScoped<OrderProcessor>();

var app = builder.Build();

When ASP.NET Core needs to create an OrderProcessor, the DI container automatically resolves IOrderRepository, INotificationService, and IOrderLogger and passes the registered implementations to the constructor. The OrderProcessor never knows — and never needs to know — which implementations it receives.

Part 6: DIP and ASP.NET Core's Built-In DI Container

ASP.NET Core was designed from the ground up with dependency injection as a first-class citizen. The entire framework follows DIP. When you register middleware, configure authentication, add logging, or set up Entity Framework Core, you are registering implementations against abstractions that the framework resolves at runtime.

Service Lifetimes

The built-in DI container in Microsoft.Extensions.DependencyInjection supports three service lifetimes:

Transient — a new instance is created every time the service is requested. Use this for lightweight, stateless services where creating a new instance is cheap. Register with AddTransient<TService, TImplementation>().

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

Scoped — one instance is created per scope. In ASP.NET Core, a scope corresponds to a single HTTP request. Every service resolved within the same request gets the same instance. Use this for services that hold per-request state, like an Entity Framework DbContext. Register with AddScoped<TService, TImplementation>().

builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();

Singleton — one instance for the entire lifetime of the application. The first time the service is requested, an instance is created; every subsequent request gets the same instance. Use this for expensive-to-create objects, configuration wrappers, and services that maintain application-wide state. Register with AddSingleton<TService, TImplementation>().

builder.Services.AddSingleton<ICacheService, MemoryCacheService>();

A common pitfall is injecting a scoped service into a singleton. The scoped service will be captured by the singleton and effectively become a singleton itself, which can cause data leakage between requests. ASP.NET Core will throw an InvalidOperationException at startup if you enable scope validation (which is on by default in the Development environment).

Keyed Services (.NET 8+)

Starting with .NET 8, the built-in DI container supports keyed services. This solves a long-standing problem: what if you have multiple implementations of the same interface and you need to resolve a specific one in different places?

Before keyed services, you had three unappealing options: inject IEnumerable<INotificationService> and filter manually, write a custom factory, or use the service locator anti-pattern. Keyed services provide a clean, built-in solution.

// Register multiple implementations with different keys
builder.Services.AddKeyedScoped<INotificationService, EmailNotificationService>("email");
builder.Services.AddKeyedScoped<INotificationService, SmsNotificationService>("sms");
builder.Services.AddKeyedScoped<INotificationService, PushNotificationService>("push");

Resolve a specific implementation using the [FromKeyedServices] attribute:

public class OrderProcessor
{
    private readonly INotificationService _emailSender;
    private readonly INotificationService _smsSender;

    public OrderProcessor(
        [FromKeyedServices("email")] INotificationService emailSender,
        [FromKeyedServices("sms")] INotificationService smsSender)
    {
        _emailSender = emailSender;
        _smsSender = smsSender;
    }

    public async Task ProcessOrderAsync(Order order, CancellationToken ct = default)
    {
        // Send both email and SMS
        await _emailSender.SendOrderConfirmationAsync(order, ct);
        await _smsSender.SendOrderConfirmationAsync(order, ct);
    }
}

In Blazor components, you can use keyed services with the [Inject] attribute:

@code {
    [Inject(Key = "email")]
    public INotificationService? EmailService { get; set; }
}

A notable change in .NET 10 is that calling GetKeyedService() (singular) with KeyedService.AnyKey now throws an InvalidOperationException, because AnyKey is intended for resolving collections of services, not a single service. This is a correction that prevents ambiguous resolution bugs.

Open Generics

The DI container supports open generic registrations, which is a powerful way to apply DIP across an entire category of services:

// Register a generic repository for any entity type
builder.Services.AddScoped(typeof(IRepository<>), typeof(EfRepository<>));

Now whenever the container encounters a request for IRepository<Customer>, IRepository<Order>, or IRepository<Product>, it automatically creates the corresponding EfRepository<Customer>, EfRepository<Order>, or EfRepository<Product>. You write the interface once, the implementation once, and the container handles all the concrete generic types.

public interface IRepository<T> where T : class
{
    Task<T?> GetByIdAsync(Guid id, CancellationToken ct = default);
    Task<IReadOnlyList<T>> GetAllAsync(CancellationToken ct = default);
    Task AddAsync(T entity, CancellationToken ct = default);
    Task UpdateAsync(T entity, CancellationToken ct = default);
    Task DeleteAsync(Guid id, CancellationToken ct = default);
}

public class EfRepository<T> : IRepository<T> where T : class
{
    private readonly AppDbContext _context;

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

    public async Task<T?> GetByIdAsync(Guid id, CancellationToken ct = default)
        => await _context.Set<T>().FindAsync([id], ct);

    public async Task<IReadOnlyList<T>> GetAllAsync(CancellationToken ct = default)
        => await _context.Set<T>().ToListAsync(ct);

    public async Task AddAsync(T entity, CancellationToken ct = default)
    {
        await _context.Set<T>().AddAsync(entity, ct);
        await _context.SaveChangesAsync(ct);
    }

    public async Task UpdateAsync(T entity, CancellationToken ct = default)
    {
        _context.Set<T>().Update(entity);
        await _context.SaveChangesAsync(ct);
    }

    public async Task DeleteAsync(Guid id, CancellationToken ct = default)
    {
        var entity = await _context.Set<T>().FindAsync([id], ct);
        if (entity is not null)
        {
            _context.Set<T>().Remove(entity);
            await _context.SaveChangesAsync(ct);
        }
    }
}

Factory Registrations

Sometimes you need more control over how a service is created. Factory registrations let you provide a delegate that constructs the service:

builder.Services.AddScoped<IOrderRepository>(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    var connectionString = config.GetConnectionString("Orders")
        ?? throw new InvalidOperationException("Missing connection string.");

    var logger = sp.GetRequiredService<ILogger<NpgsqlOrderRepository>>();

    return new NpgsqlOrderRepository(connectionString, logger);
});

This is useful when the implementation's constructor requires values that are not themselves registered services (like a connection string), or when you need conditional logic to decide which implementation to create.

Part 7: DIP Enables Testing — The Practical Payoff

If there is one argument that convinces skeptical developers to adopt DIP, it is testability. When your high-level modules depend on abstractions, you can substitute test doubles — mocks, stubs, fakes — for the real implementations. This means you can write fast, isolated unit tests that do not require a database, a network connection, an SMTP server, or any other external infrastructure.

Testing Without DIP

Without DIP, testing the original OrderProcessor requires all of its infrastructure to be available:

// This is NOT a unit test. This is an integration test that requires:
// - A running SQL Server instance
// - A running SMTP server
// - Write access to C:\Logs\
// - Network connectivity
// It is slow, flaky, and expensive to maintain.
[Fact]
public void ProcessOrder_ShouldNotThrow()
{
    var processor = new OrderProcessor();
    var order = new Order
    {
        Id = Guid.NewGuid(),
        CustomerEmail = "test@example.com",
        Total = 99.99m
    };

    // This will actually try to connect to a database and send an email
    processor.ProcessOrder(order);
}

This test will fail in CI/CD unless you have a full infrastructure stack running. It is slow because it makes real network calls. It is flaky because SMTP servers sometimes time out. It tests too many things at once — a failure could be in the business logic, the database, the email server, or the logging system.

Testing With DIP

With DIP, you substitute lightweight test doubles and test the business logic in isolation:

public class OrderProcessorTests
{
    [Fact]
    public async Task ProcessOrderAsync_ShouldSaveAndNotifyAndLog()
    {
        // Arrange
        var savedOrders = new List<Order>();
        var notifiedOrders = new List<Order>();
        var loggedOrders = new List<Order>();

        var mockRepository = new FakeOrderRepository(savedOrders);
        var mockNotification = new FakeNotificationService(notifiedOrders);
        var mockLogger = new FakeOrderLogger(loggedOrders);

        var processor = new OrderProcessor(
            mockRepository, mockNotification, mockLogger);

        var order = new Order
        {
            Id = Guid.NewGuid(),
            CustomerId = Guid.NewGuid(),
            CustomerEmail = "test@example.com",
            Total = 99.99m,
            CreatedAt = DateTime.UtcNow
        };

        // Act
        await processor.ProcessOrderAsync(order);

        // Assert
        Assert.Single(savedOrders);
        Assert.Equal(order.Id, savedOrders[0].Id);

        Assert.Single(notifiedOrders);
        Assert.Equal(order.Id, notifiedOrders[0].Id);

        Assert.Single(loggedOrders);
        Assert.Equal(order.Id, loggedOrders[0].Id);
    }

    [Fact]
    public async Task ProcessOrderAsync_WhenSaveFails_ShouldLogAndRethrow()
    {
        // Arrange
        var failingRepository = new FailingOrderRepository();
        var mockNotification = new FakeNotificationService(new List<Order>());
        var loggedFailures = new List<(Order, Exception)>();
        var mockLogger = new FakeOrderLogger(failedOrders: loggedFailures);

        var processor = new OrderProcessor(
            failingRepository, mockNotification, mockLogger);

        var order = new Order
        {
            Id = Guid.NewGuid(),
            CustomerId = Guid.NewGuid(),
            CustomerEmail = "test@example.com",
            Total = 50.00m,
            CreatedAt = DateTime.UtcNow
        };

        // Act & Assert
        await Assert.ThrowsAsync<InvalidOperationException>(
            () => processor.ProcessOrderAsync(order));

        Assert.Single(loggedFailures);
        Assert.Equal(order.Id, loggedFailures[0].Item1.Id);
    }
}

Here are the simple fakes used in those tests:

public class FakeOrderRepository : IOrderRepository
{
    private readonly List<Order> _savedOrders;

    public FakeOrderRepository(List<Order> savedOrders)
    {
        _savedOrders = savedOrders;
    }

    public Task SaveAsync(Order order, CancellationToken ct = default)
    {
        _savedOrders.Add(order);
        return Task.CompletedTask;
    }

    public Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
        => Task.FromResult(_savedOrders.FirstOrDefault(o => o.Id == id));
}

public class FailingOrderRepository : IOrderRepository
{
    public Task SaveAsync(Order order, CancellationToken ct = default)
        => throw new InvalidOperationException("Database is unavailable.");

    public Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
        => throw new InvalidOperationException("Database is unavailable.");
}

public class FakeNotificationService : INotificationService
{
    private readonly List<Order> _notifiedOrders;

    public FakeNotificationService(List<Order> notifiedOrders)
    {
        _notifiedOrders = notifiedOrders;
    }

    public Task SendOrderConfirmationAsync(
        Order order, CancellationToken ct = default)
    {
        _notifiedOrders.Add(order);
        return Task.CompletedTask;
    }
}

public class FakeOrderLogger : IOrderLogger
{
    private readonly List<Order>? _processedOrders;
    private readonly List<(Order, Exception)>? _failedOrders;

    public FakeOrderLogger(
        List<Order>? processedOrders = null,
        List<(Order, Exception)>? failedOrders = null)
    {
        _processedOrders = processedOrders;
        _failedOrders = failedOrders;
    }

    public void LogOrderProcessed(Order order)
        => _processedOrders?.Add(order);

    public void LogOrderFailed(Order order, Exception exception)
        => _failedOrders?.Add((order, exception));
}

These tests run in milliseconds. They require no infrastructure. They fail only when the business logic is wrong, not when the database is down. They can run in CI/CD, on a developer's laptop, on a plane without internet. This is the practical payoff of DIP.

Using Mocking Libraries

Hand-written fakes are simple and transparent, but for larger codebases, mocking libraries reduce boilerplate. Here is the same test using NSubstitute (a popular, free .NET mocking library):

using NSubstitute;

public class OrderProcessorNSubstituteTests
{
    [Fact]
    public async Task ProcessOrderAsync_ShouldCallAllDependencies()
    {
        // Arrange
        var repository = Substitute.For<IOrderRepository>();
        var notification = Substitute.For<INotificationService>();
        var logger = Substitute.For<IOrderLogger>();

        var processor = new OrderProcessor(repository, notification, logger);

        var order = new Order
        {
            Id = Guid.NewGuid(),
            CustomerId = Guid.NewGuid(),
            CustomerEmail = "test@example.com",
            Total = 75.00m,
            CreatedAt = DateTime.UtcNow
        };

        // Act
        await processor.ProcessOrderAsync(order);

        // Assert
        await repository.Received(1).SaveAsync(order, Arg.Any<CancellationToken>());
        await notification.Received(1)
            .SendOrderConfirmationAsync(order, Arg.Any<CancellationToken>());
        logger.Received(1).LogOrderProcessed(order);
    }
}

NSubstitute creates a proxy object that implements the interface and records all calls made to it. The Received(1) assertion verifies that each method was called exactly once. This works because OrderProcessor depends on interfaces, not on concrete classes. Without DIP, NSubstitute (or Moq, or FakeItEasy, or any other mocking library) cannot create the proxy because there is no interface to proxy.

Part 8: Architectural Patterns That Rely on DIP

DIP is not just a class-level concern. Several well-known architectural patterns are built on DIP as a foundation.

Clean Architecture

Robert C. Martin's Clean Architecture (described in his 2017 book of the same name) is, at its core, an application of DIP at the architectural level. The architecture is organized in concentric rings:

1. Entities (innermost) — enterprise-wide business rules.
2. Use Cases — application-specific business rules.
3. Interface Adapters — controllers, presenters, gateways.
4. Frameworks and Drivers (outermost) — the web framework, the database, the UI.

The "Dependency Rule" of Clean Architecture states that dependencies can only point inward. The inner rings know nothing about the outer rings. The use case layer defines the repository interface; the infrastructure layer implements it. This is DIP applied at the package and project level.

In a .NET solution, this typically looks like:

MyApp.Domain/           (entities, value objects, domain events)
MyApp.Application/      (use cases, interfaces like IOrderRepository)
MyApp.Infrastructure/   (EF Core DbContext, email service, file system)
MyApp.Web/              (ASP.NET Core controllers, Blazor pages, Program.cs)

MyApp.Application has a project reference to MyApp.Domain (inward). MyApp.Infrastructure has project references to both MyApp.Application and MyApp.Domain (inward). MyApp.Web references everything and is responsible for wiring up the DI container. The dependency arrows always point inward, toward the domain.

Hexagonal Architecture (Ports and Adapters)

Alistair Cockburn's Hexagonal Architecture (2005) predates Clean Architecture and expresses a very similar idea using different terminology. The "ports" are the interfaces (abstractions) that the core application defines. The "adapters" are the concrete implementations that connect the core to the outside world — a database adapter, an HTTP adapter, a messaging adapter. The core depends only on the ports. The adapters depend on the ports and implement them.

In DIP terms: the ports are the abstractions that the high-level module (the core application) defines. The adapters are the low-level modules (the infrastructure) that implement those abstractions.

The Strategy Pattern

The Strategy pattern from the Gang of Four is perhaps the simplest manifestation of DIP. A class delegates part of its behavior to an interchangeable strategy object, accessed through an interface:

public interface IDiscountStrategy
{
    decimal CalculateDiscount(Order order);
}

public class NoDiscount : IDiscountStrategy
{
    public decimal CalculateDiscount(Order order) => 0m;
}

public class PercentageDiscount : IDiscountStrategy
{
    private readonly decimal _percentage;

    public PercentageDiscount(decimal percentage)
    {
        _percentage = percentage;
    }

    public decimal CalculateDiscount(Order order)
        => order.Total * _percentage / 100m;
}

public class LoyaltyDiscount : IDiscountStrategy
{
    private readonly ICustomerRepository _customerRepository;

    public LoyaltyDiscount(ICustomerRepository customerRepository)
    {
        _customerRepository = customerRepository;
    }

    public decimal CalculateDiscount(Order order)
    {
        var customer = _customerRepository.GetById(order.CustomerId);
        if (customer is null) return 0m;

        return customer.OrderCount switch
        {
            >= 100 => order.Total * 0.15m,
            >= 50 => order.Total * 0.10m,
            >= 10 => order.Total * 0.05m,
            _ => 0m
        };
    }
}

public class OrderPricingService
{
    private readonly IDiscountStrategy _discountStrategy;

    public OrderPricingService(IDiscountStrategy discountStrategy)
    {
        _discountStrategy = discountStrategy;
    }

    public decimal CalculateFinalPrice(Order order)
    {
        var discount = _discountStrategy.CalculateDiscount(order);
        return order.Total - discount;
    }
}

The OrderPricingService (high-level) depends on IDiscountStrategy (abstraction), not on any concrete discount implementation (detail). You can swap discount strategies without modifying the pricing service. You can test the pricing service with a mock discount strategy. You can add new discount strategies without touching any existing code. That is DIP, OCP, and LSP all working together.

The Repository Pattern

The Repository pattern, popularized by Martin Fowler's "Patterns of Enterprise Application Architecture" (2002) and widely used in .NET, is another direct application of DIP:

public interface IProductRepository
{
    Task<Product?> GetByIdAsync(int id, CancellationToken ct = default);
    Task<IReadOnlyList<Product>> SearchAsync(
        string query, CancellationToken ct = default);
    Task AddAsync(Product product, CancellationToken ct = default);
    Task UpdateAsync(Product product, CancellationToken ct = default);
}

Your business logic depends on IProductRepository. Whether the implementation uses Entity Framework Core with SQL Server, Dapper with PostgreSQL, an in-memory list for testing, or a REST API call to a microservice — the business logic does not know and does not care. The abstraction (the interface) lives in the domain or application layer. The implementation (the concrete class) lives in the infrastructure layer. Dependencies point inward.

Part 9: Common Pitfalls and Anti-Patterns

DIP is widely taught but frequently misapplied. Here are the most common mistakes, with explanations of why they are mistakes and how to fix them.

Pitfall 1: Interface Per Class — The "IFoo for Every Foo" Problem

Some developers learn that DIP means "always program against interfaces" and conclude that every single class needs a corresponding interface. The result is a codebase littered with interfaces like IUserService, IUserServiceImpl, IOrderHelper, IOrderHelperImpl — where each interface has exactly one implementation that will never be swapped out.

This is cargo cult programming. DIP says to depend on abstractions when the dependency direction matters. If a class is a simple data-transfer object, a value object, or a utility with no side effects, wrapping it in an interface adds ceremony without benefit.

The guideline: introduce an interface when at least one of these is true:

• The dependency crosses an architectural boundary (e.g., between your application layer and your infrastructure layer).
• You need to substitute the dependency in tests (typically because it has side effects like I/O, network calls, or database access).
• You realistically expect multiple implementations (different database backends, different notification channels, different caching strategies).
• The dependency is expensive or slow and you need to mock it for fast unit tests.

If none of these apply, it is perfectly fine for one class to depend on another class directly. DIP is about managing the dependencies that matter, not about wrapping everything in interfaces as a ritual.

Pitfall 2: Leaky Abstractions

An abstraction that reveals implementation details defeats the purpose of DIP. We saw an example earlier with GetConnection() on a repository interface. Here are more subtle examples:

// Bad: The interface knows about Entity Framework
public interface IProductRepository
{
    IQueryable<Product> GetQueryable(); // Leaks EF's IQueryable
    Task SaveChangesAsync(); // Leaks EF's unit-of-work pattern
}

// Bad: The interface knows about HTTP
public interface IWeatherService
{
    Task<HttpResponseMessage> GetForecastAsync(string city);
    // Returns HttpResponseMessage — what if we switch to gRPC?
}

// Good: The interface speaks domain language
public interface IProductRepository
{
    Task<IReadOnlyList<Product>> SearchAsync(
        string query, int page, int pageSize, CancellationToken ct = default);
    Task<Product?> GetByIdAsync(int id, CancellationToken ct = default);
}

// Good: The interface returns domain objects
public interface IWeatherService
{
    Task<WeatherForecast?> GetForecastAsync(
        string city, CancellationToken ct = default);
}

The test for a clean abstraction: could you implement this interface with a completely different technology without changing any consumer code? If IProductRepository returns IQueryable<Product>, consumers will write LINQ queries that only work with Entity Framework. If IWeatherService returns HttpResponseMessage, consumers must parse HTTP. The abstraction has been contaminated by the detail.

Pitfall 3: Constructor Over-Injection

When a class accepts seven or eight dependencies through its constructor, it is often a sign that the class has too many responsibilities — a Single Responsibility Principle violation, not a DIP problem. But the symptom appears at the DIP boundary (the constructor).

// This class probably does too much
public class OrderService(
    IOrderRepository orderRepository,
    ICustomerRepository customerRepository,
    IInventoryService inventoryService,
    IPaymentGateway paymentGateway,
    INotificationService notificationService,
    IDiscountService discountService,
    ITaxCalculator taxCalculator,
    IShippingService shippingService,
    IAuditLogger auditLogger)
{
    // ...
}

The fix is not to reduce the number of interfaces. The fix is to decompose the class into smaller, focused classes, each with two or three dependencies. Perhaps OrderService delegates pricing to a PricingService (which takes IDiscountService and ITaxCalculator), fulfillment to a FulfillmentService (which takes IInventoryService and IShippingService), and notification to the INotificationService directly.

Pitfall 4: The Service Locator Anti-Pattern

The Service Locator pattern uses a central registry to resolve dependencies at runtime. Instead of receiving dependencies through the constructor, a class asks the service locator for what it needs:

// Anti-pattern: Service Locator
public class OrderProcessor
{
    public async Task ProcessOrderAsync(Order order)
    {
        // Asking for dependencies at runtime
        var repository = ServiceLocator.Get<IOrderRepository>();
        var notification = ServiceLocator.Get<INotificationService>();

        await repository.SaveAsync(order);
        await notification.SendOrderConfirmationAsync(order);
    }
}

This superficially follows DIP — the class depends on interfaces, not concrete types. But it violates the spirit of DIP in several important ways:

• Hidden dependencies. You cannot tell what OrderProcessor needs by looking at its constructor. The dependencies are buried in the method bodies. A developer must read every line of code to understand what the class depends on.
• Untestable without infrastructure. To test OrderProcessor, you must set up a ServiceLocator with the right registrations. This is more complex and fragile than simple constructor injection.
• Tight coupling to the locator. The class depends on ServiceLocator, which is itself a concrete implementation detail. You have replaced concrete dependencies with a single, global concrete dependency.

The fix is straightforward: use constructor injection instead. Let the DI container do the locating. Your classes should receive their dependencies, not go looking for them.

Pitfall 5: Applying DIP Where It Does Not Belong

Not every dependency needs to be inverted. Consider:

public class FullName
{
    public string First { get; }
    public string Last { get; }

    public FullName(string first, string last)
    {
        First = first;
        Last = last;
    }

    public override string ToString() => $"{First} {Last}";
}

Should FullName have an IFullName interface? No. It is a value object with no side effects, no I/O, no external dependencies. It is trivially testable as-is. Wrapping it in an interface would add complexity for zero benefit.

Similarly, System.Math, System.Guid, System.DateTime.UtcNow (through an ITimeProvider in .NET 8+ or TimeProvider abstract class), string manipulation methods, and pure computation functions generally do not need abstraction. The exception is when these are difficult to control in tests (like DateTime.Now, which motivated .NET 8's TimeProvider).

Pitfall 6: Ignoring the Ownership Question

DIP says that both high-level and low-level modules should depend on abstractions. But who owns the abstraction?

If the low-level module defines the interface, you have not actually achieved inversion. You have just added an interface that still lives in the infrastructure layer. The high-level module still has a project reference to the infrastructure project. If you swap the infrastructure, you must change the high-level project's references.

The correct ownership: the interface lives with the code that uses it (the high-level module), not the code that implements it (the low-level module). In a Clean Architecture solution:

MyApp.Application/
    Interfaces/
        IOrderRepository.cs     <-- The interface lives HERE
        INotificationService.cs

MyApp.Infrastructure/
    Repositories/
        EfOrderRepository.cs    <-- The implementation lives HERE
    Services/
        SmtpNotificationService.cs

MyApp.Infrastructure has a project reference to MyApp.Application so it can implement the interfaces. MyApp.Application has no reference to MyApp.Infrastructure. The dependency arrow points inward. This is the inversion.

Part 10: DIP in Real-World .NET Applications — Beyond the Textbook

Example 1: Swapping Database Providers

One of the most powerful demonstrations of DIP is swapping database providers without changing business logic. Imagine you started with SQL Server and need to migrate to PostgreSQL:

// Application layer: the interface (unchanged)
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default);
    Task<IReadOnlyList<Order>> GetRecentAsync(int count, CancellationToken ct = default);
    Task SaveAsync(Order order, CancellationToken ct = default);
}

// Infrastructure layer: SQL Server implementation
public sealed class SqlServerOrderRepository : IOrderRepository
{
    private readonly string _connectionString;

    public SqlServerOrderRepository(string connectionString)
    {
        _connectionString = connectionString;
    }

    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
    {
        await using var conn = new SqlConnection(_connectionString);
        return await conn.QueryFirstOrDefaultAsync<Order>(
            "SELECT * FROM Orders WHERE Id = @Id", new { Id = id });
    }

    public async Task<IReadOnlyList<Order>> GetRecentAsync(
        int count, CancellationToken ct = default)
    {
        await using var conn = new SqlConnection(_connectionString);
        var results = await conn.QueryAsync<Order>(
            "SELECT TOP (@Count) * FROM Orders ORDER BY CreatedAt DESC",
            new { Count = count });
        return results.ToList();
    }

    public async Task SaveAsync(Order order, CancellationToken ct = default)
    {
        await using var conn = new SqlConnection(_connectionString);
        await conn.ExecuteAsync(
            "INSERT INTO Orders (Id, CustomerId, Total, CreatedAt) " +
            "VALUES (@Id, @CustomerId, @Total, @CreatedAt)", order);
    }
}

// Infrastructure layer: PostgreSQL implementation (new)
public sealed class NpgsqlOrderRepository : IOrderRepository
{
    private readonly string _connectionString;

    public NpgsqlOrderRepository(string connectionString)
    {
        _connectionString = connectionString;
    }

    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
    {
        await using var conn = new NpgsqlConnection(_connectionString);
        return await conn.QueryFirstOrDefaultAsync<Order>(
            "SELECT * FROM orders WHERE id = @Id", new { Id = id });
    }

    public async Task<IReadOnlyList<Order>> GetRecentAsync(
        int count, CancellationToken ct = default)
    {
        await using var conn = new NpgsqlConnection(_connectionString);
        var results = await conn.QueryAsync<Order>(
            "SELECT * FROM orders ORDER BY created_at DESC LIMIT @Count",
            new { Count = count });
        return results.ToList();
    }

    public async Task SaveAsync(Order order, CancellationToken ct = default)
    {
        await using var conn = new NpgsqlConnection(_connectionString);
        await conn.ExecuteAsync(
            "INSERT INTO orders (id, customer_id, total, created_at) " +
            "VALUES (@Id, @CustomerId, @Total, @CreatedAt)", order);
    }
}

The migration happens entirely in the infrastructure layer and the DI registration:

// Before: SQL Server
builder.Services.AddScoped<IOrderRepository>(sp =>
    new SqlServerOrderRepository(
        builder.Configuration.GetConnectionString("Orders")!));

// After: PostgreSQL
builder.Services.AddScoped<IOrderRepository>(sp =>
    new NpgsqlOrderRepository(
        builder.Configuration.GetConnectionString("Orders")!));

One line changes in Program.cs. Zero lines change in the application layer. Zero lines change in the domain layer. Zero tests break (assuming the PostgreSQL implementation passes the same integration test suite as the SQL Server one). This is the promise of DIP fulfilled.

Example 2: Feature Flags and Branch by Abstraction

DIP enables branch by abstraction, a technique for making large-scale changes to a codebase without long-lived branches. You define an interface for the behavior you want to change, implement both the old and new versions behind it, and use a feature flag to switch between them at runtime:

public interface IPricingEngine
{
    decimal CalculatePrice(Product product, Customer customer);
}

public class LegacyPricingEngine : IPricingEngine
{
    public decimal CalculatePrice(Product product, Customer customer)
    {
        // The old pricing logic
        return product.BasePrice * 1.08m; // Simple 8% markup
    }
}

public class NewPricingEngine : IPricingEngine
{
    private readonly IDiscountStrategy _discountStrategy;

    public NewPricingEngine(IDiscountStrategy discountStrategy)
    {
        _discountStrategy = discountStrategy;
    }

    public decimal CalculatePrice(Product product, Customer customer)
    {
        // The new, more sophisticated pricing logic
        var basePrice = product.BasePrice;
        var discount = _discountStrategy.CalculateDiscount(
            new Order { Total = basePrice, CustomerId = customer.Id });
        var markup = customer.Tier switch
        {
            CustomerTier.Wholesale => 1.03m,
            CustomerTier.Retail => 1.08m,
            CustomerTier.Premium => 1.05m,
            _ => 1.10m
        };
        return (basePrice - discount) * markup;
    }
}

// In Program.cs: use a feature flag to choose the implementation
builder.Services.AddScoped<IPricingEngine>(sp =>
{
    var featureFlags = sp.GetRequiredService<IOptions<FeatureFlags>>().Value;
    if (featureFlags.UseNewPricingEngine)
    {
        var discountStrategy = sp.GetRequiredService<IDiscountStrategy>();
        return new NewPricingEngine(discountStrategy);
    }

    return new LegacyPricingEngine();
});

You can deploy the new pricing engine to production behind a disabled feature flag, enable it for 1% of traffic, monitor the results, ramp up gradually, and roll back instantly if anything goes wrong. All of this is possible because the consuming code depends on IPricingEngine, not on either concrete implementation. Without DIP, you would be doing code surgery in the consuming classes to switch between pricing strategies.

Example 3: Resilient Multi-Provider Services

DIP makes it natural to build resilience patterns where you fail over from one implementation to another:

public sealed class ResilientNotificationService : INotificationService
{
    private readonly INotificationService _primary;
    private readonly INotificationService _fallback;
    private readonly ILogger<ResilientNotificationService> _logger;

    public ResilientNotificationService(
        [FromKeyedServices("email")] INotificationService primary,
        [FromKeyedServices("sms")] INotificationService fallback,
        ILogger<ResilientNotificationService> logger)
    {
        _primary = primary;
        _fallback = fallback;
        _logger = logger;
    }

    public async Task SendOrderConfirmationAsync(
        Order order, CancellationToken ct = default)
    {
        try
        {
            await _primary.SendOrderConfirmationAsync(order, ct);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex,
                "Primary notification failed for order {OrderId}, " +
                "falling back to secondary", order.Id);

            await _fallback.SendOrderConfirmationAsync(order, ct);
        }
    }
}

The ResilientNotificationService is itself an INotificationService. It is a decorator — a pattern that relies entirely on DIP. The consuming code sees INotificationService and knows nothing about the resilience logic. You could stack decorators: add retry logic, add circuit breaking, add telemetry — all as decorators that implement the same interface.

Part 11: DIP and the Other SOLID Principles

DIP does not exist in isolation. It works in concert with the other four SOLID principles, and understanding these relationships deepens your understanding of all five.

Single Responsibility Principle (SRP)

SRP says a class should have one reason to change. DIP enforces this by making dependencies explicit. When you see a constructor with eight interface parameters, it is a signal that the class may have too many responsibilities. DIP does not cause this problem, but it makes it visible, which is the first step toward fixing it.

Open-Closed Principle (OCP)

OCP says a module should be open for extension but closed for modification. DIP makes this possible. If your OrderProcessor depends on INotificationService, you can extend it to support push notifications by creating a new PushNotificationService class and registering it — without modifying OrderProcessor. The class is open for extension (new notification channels) and closed for modification (existing code does not change).

Liskov Substitution Principle (LSP)

LSP says that objects of a superclass should be replaceable with objects of any subclass without breaking the program. DIP relies on LSP. When the DI container hands your OrderProcessor an EmailNotificationService, the OrderProcessor assumes it behaves according to the INotificationService contract. If EmailNotificationService violates that contract — for example, by throwing an unexpected exception type or by having side effects not implied by the interface — then the substitution breaks. DIP provides the mechanism for substitution; LSP ensures the substitution is safe.

Interface Segregation Principle (ISP)

ISP says that no client should be forced to depend on methods it does not use. ISP directly improves DIP by encouraging smaller, more focused interfaces. If IOrderRepository has twenty methods but a particular consumer only needs GetByIdAsync, ISP suggests splitting the interface. This makes DIP more effective because the abstraction more precisely matches what the consumer actually needs, reducing coupling further.

Part 12: DIP in Blazor WebAssembly

Blazor WebAssembly, the framework this very blog is built on, uses DIP extensively. The DI container works the same way as in server-side ASP.NET Core, with a few nuances.

Registering Services in Blazor WASM

In a Blazor WebAssembly app, you register services in Program.cs:

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");

// Register abstractions
builder.Services.AddScoped<IBlogService, StaticBlogService>();
builder.Services.AddScoped<IThemeService, LocalStorageThemeService>();
builder.Services.AddSingleton<IAnalyticsService, ConsoleAnalyticsService>();

await builder.Build().RunAsync();

Injecting in Components

Blazor components receive dependencies through the [Inject] attribute:

@page "/blog"
@inject IBlogService BlogService
@inject IThemeService ThemeService

<h1>Blog</h1>

@if (posts is not null)
{
    @foreach (var post in posts)
    {
        <article>
            <h2><a href="blog/@post.Slug">@post.Title</a></h2>
            <p>@post.Summary</p>
        </article>
    }
}

@code {
    private BlogPostMetadata[]? posts;

    protected override async Task OnInitializedAsync()
    {
        posts = await BlogService.GetAllPostsAsync();
    }
}

The component depends on IBlogService, not on the specific implementation that fetches JSON from wwwroot/blog-data/. If you later want to fetch blog posts from an API instead of static files, you change the registration in Program.cs. The component does not change.

Scoping in Blazor WASM

There is an important difference in Blazor WebAssembly compared to server-side ASP.NET Core: there is no real "scope" in the HTTP request sense. In Blazor WASM, the app runs in the browser, and scoped services behave like singletons because there is only one "scope" — the app lifetime. If you register DbContext as scoped in Blazor Server, each circuit gets its own DbContext. In Blazor WASM, there is only one DbContext for the entire app session. Keep this in mind when designing your service lifetimes for Blazor WASM applications.

Testing Blazor Components with bUnit

DIP makes Blazor components testable with bUnit. You replace the real services with fakes:

using Bunit;

public class BlogPageTests : BunitContext
{
    [Fact]
    public void BlogPage_ShouldRenderPosts()
    {
        // Arrange
        var fakeBlogService = new FakeBlogService(new[]
        {
            new BlogPostMetadata
            {
                Slug = "test-post",
                Title = "Test Post",
                Summary = "A test summary",
                Date = new DateTime(2026, 3, 27)
            }
        });

        Services.AddSingleton<IBlogService>(fakeBlogService);

        // Act
        var cut = Render<Blog>();

        // Assert
        cut.Find("h2").MarkupMatches("<h2><a href=\"blog/test-post\">Test Post</a></h2>");
        cut.Find("p").MarkupMatches("<p>A test summary</p>");
    }
}

Without DIP, the Blog component would be hardwired to fetch JSON from wwwroot/blog-data/, and testing it would require a running HTTP server serving those static files. With DIP, you inject a fake that returns test data immediately.

Part 13: When Not to Use DIP

DIP is a powerful tool, but like all tools, it can be misapplied. Here are situations where strict adherence to DIP is unnecessary or counterproductive.

Small Scripts and One-Off Tools

If you are writing a hundred-line console app to migrate data from one format to another, and it will run once and be deleted, introducing interfaces and DI adds complexity without benefit. Write the simplest code that works. DIP is an investment in maintainability and flexibility — investments that only pay off when the code will be maintained and needs to be flexible.

Value Objects and DTOs

As discussed earlier, not every type needs an interface. Value objects (Money, Address, DateRange), data-transfer objects (OrderDto, CreateUserRequest), and records that hold data without behavior are not candidates for DIP. They have no side effects to mock, no I/O to abstract away, and no alternative implementations to swap in.

Stable, Simple Dependencies

If a dependency is stable (it will never be swapped out) and simple (it has no side effects that interfere with testing), an interface may not be necessary. For example, a static helper method that formats a phone number is not something you need to abstract. The key question is always: "Does this dependency make my class hard to test or hard to change?" If the answer is no, you can skip the interface.

Over-Abstraction and Abstraction Fatigue

There is a real cost to abstraction. Every interface is a new file to maintain, a new type to navigate in an IDE, and a new indirection for other developers to trace through when debugging. If your codebase has more interfaces than classes, something has gone wrong. Use DIP judiciously, at the boundaries that matter, and leave the internals of each module to use concrete types freely.

Martin Fowler has written about this tradeoff, noting that the correct number of abstractions depends on the cost of change in your specific context. In a rapidly evolving startup codebase, fewer abstractions and more flexibility to refactor may be appropriate. In a long-lived enterprise system with multiple teams, more abstractions at boundary points prevent expensive coordination between teams.

Part 14: A Checklist for Applying DIP in Your .NET Projects

Here is a practical checklist you can apply to your own codebase, whether you are starting a new project or refactoring an existing one.

Identify your architectural boundaries. Where does your business logic end and your infrastructure begin? Draw a line. Interfaces go on the business side. Implementations go on the infrastructure side.

Define interfaces at the boundary. For each piece of infrastructure your business logic uses — databases, APIs, file systems, message queues, caches, email services — define an interface in your application or domain layer.

Use domain language in your interfaces. The interface should describe what the business needs, not how the infrastructure works. SaveOrderAsync, not ExecuteSqlCommandAsync. SendOrderConfirmationAsync, not SmtpSendAsync.

Register services in one place. Your DI registrations should live in the composition root — Program.cs in ASP.NET Core. This is the one place that knows about concrete types and wires abstractions to implementations.

Use constructor injection. Receive dependencies through the constructor. Avoid property injection (which makes dependencies optional and easy to forget) and service locator (which hides dependencies).

Choose the right lifetime. Use Transient for lightweight, stateless services. Use Scoped for per-request services like DbContext. Use Singleton for expensive, thread-safe services. Never inject a shorter-lived service into a longer-lived one.

Do not abstract what does not need abstracting. Value objects, DTOs, static helpers, and simple in-memory computations generally do not need interfaces. Abstract the things that have side effects, are expensive, or might change.

Keep interfaces small. Prefer multiple small interfaces over one large interface. A repository with thirty methods is harder to mock and harder to implement correctly than three focused interfaces with ten methods each.

Verify with tests. If you cannot write a fast, isolated unit test for your class, you probably have a DIP violation somewhere. The inability to mock a dependency is a signal that the dependency is concrete where it should be abstract.

Watch for constructor bloat. If a class has more than four or five injected dependencies, it may be doing too much. Consider decomposing it into smaller, more focused classes.

Resources

• Martin, Robert C. "The Dependency Inversion Principle." C++ Report, May 1996. PDF available at cs.utexas.edu
• Martin, Robert C. "Agile Software Development, Principles, Patterns, and Practices." Prentice Hall, 2002. The book that brought SOLID to a wide audience.
• Martin, Robert C. "Clean Architecture: A Craftsman's Guide to Software Structure and Design." Prentice Hall, 2017.
• Fowler, Martin. "Inversion of Control Containers and the Dependency Injection pattern." January 2004. martinfowler.com/articles/injection.html
• Fowler, Martin. "DIP in the Wild." martinfowler.com/articles/dipInTheWild.html
• Microsoft. "Dependency injection in ASP.NET Core." learn.microsoft.com
• Microsoft. "Dependency injection — .NET." learn.microsoft.com
• Seemann, Mark. "Dependency Injection Principles, Practices, and Patterns." Manning Publications, 2019. The definitive book on DI in .NET.
• Cockburn, Alistair. "Hexagonal Architecture." alistair.cockburn.us

This article will take you from the origin story of the ISP, through the theory, into the .NET Base Class Library where Microsoft themselves struggled with it, through practical C# refactoring examples, and finally into the modern .NET 10 world of default interface methods, minimal APIs, and microservice boundaries. By the end, you will have a mental model for recognizing fat interfaces, a toolkit for breaking them apart, and the judgment to know when to stop splitting.

Part 1: The Origin Story — A Printer, a Fat Class, and an Hour-Long Build

The Interface Segregation Principle was not conceived in an ivory tower. It was born out of pain at Xerox in the early 1990s.

Robert C. Martin — universally known as Uncle Bob — was consulting for Xerox on a new multifunction printer system. This printer could print, staple, fax, and collate. The software driving it had been built from scratch. At the heart of the system sat a single Job class. Every task — print jobs, staple jobs, fax jobs — went through this one class. The Job class knew about every operation the printer could perform.

As the system grew, the Job class grew with it. It accumulated methods for every conceivable operation. And here is where the real damage showed up: because every module in the system depended on this single class, even the tiniest change to a fax-related method triggered a recompilation of the stapling module, the printing module, and everything else. The build cycle ballooned to an hour. Development became nearly impossible. A one-line fix to fax retry logic meant every developer on the team had to wait an hour before they could test anything.

Martin's solution was to insert interfaces between the Job class and its clients. Instead of every module depending directly on the monolithic Job class, each module would depend on a narrow interface tailored to its needs. A StapleJob interface exposed only the methods the stapling module needed. A PrintJob interface exposed only the methods the printing module needed. The Job class still implemented all of those interfaces — it still contained the actual logic — but the modules no longer knew about each other's methods. A change to a fax method no longer triggered recompilation of the stapling code, because the stapling code did not depend on the fax interface.

This was the moment the Interface Segregation Principle crystallized. Martin later formulated it as a single sentence:

"Clients should not be forced to depend on methods they do not use."

He published the principle formally in his 2002 book Agile Software Development: Principles, Patterns, and Practices, and it became the "I" in the SOLID acronym (coined by Michael Feathers around 2004). But the underlying insight predates the book by nearly a decade. It was born on a factory floor, from a real system with real build times that had become real obstacles.

Part 2: What the ISP Actually Says (and What It Does Not Say)

The ISP is frequently misunderstood. Let us be precise about what it claims and what it does not.

What ISP says

An interface should be designed from the perspective of its clients. If two clients use different subsets of an interface's methods, those subsets should be expressed as separate interfaces. The goal is to prevent a change demanded by one client from rippling through to another client that does not care about that change.

Think of it like a restaurant menu. A vegetarian diner and a meat-loving diner both eat at the same restaurant. If the restaurant hands them a single menu that is 40 pages long, the vegetarian has to flip past 30 pages of steak and pork to find the three salad options. Worse, if the chef changes the steak section, the vegetarian's menu is reprinted too. A better design: give the vegetarian a focused vegetarian menu and the carnivore a focused carnivore menu. The kitchen (the implementing class) still prepares all the dishes, but each diner (client) only sees what is relevant to them.

What ISP does not say

ISP does not say every interface should have one method. This is a common over-application. An interface with five methods is perfectly fine if every client that depends on it uses all five. The principle is about unused dependencies, not about counting methods. An ILogger with LogDebug, LogInformation, LogWarning, LogError, and LogCritical is not an ISP violation if every consumer of the logger calls all five methods (or at least could reasonably call any of them).

ISP is not the same as the Single Responsibility Principle (SRP). SRP says a class should have one reason to change. ISP says a client should not depend on methods it does not use. They are related but distinct. You can violate ISP without violating SRP, and vice versa. An interface might have a single responsibility (managing user accounts) but still be too fat for certain clients (a reporting module that only needs to read user names).

ISP is not about NotImplementedException. If a class implements an interface and throws NotImplementedException for some methods, that is a Liskov Substitution Principle (LSP) violation, not an ISP violation per se. ISP focuses on the client side — what the consuming class is forced to depend on — not the implementing side. Of course, in practice, the two often appear together. A fat interface leads to implementations that cannot fully honor the contract, which is both an ISP smell and an LSP violation. But they are distinct diagnoses.

ISP is not limited to the C# interface keyword. The principle applies to any abstraction boundary. A class with twenty public methods where different consumers use different subsets is an ISP problem even if no interface keyword is in sight. Abstract classes, base classes, and even module APIs in microservice architectures can all exhibit fat-interface problems.

The precise formulation

Uncle Bob later refined the principle in his article on the topic: when a client depends on a class that contains methods the client does not use, but that other clients do use, then that client will be affected by the changes those other clients force upon the class. The clients become indirectly coupled to each other through the shared interface, even though they have no direct relationship.

Part 3: ISP in the .NET Base Class Library

The .NET BCL is a fascinating study in interface segregation — both its successes and its historical failures. The designers of the framework have been wrestling with ISP since .NET 1.0, and the evolution of collection interfaces tells the story better than any textbook.

The IList problem

Consider IList<T>. It defines methods for reading (this[int index], IndexOf), adding (Add, Insert), removing (Remove, RemoveAt), and clearing (Clear). If your code only needs to iterate over a collection, depending on IList<T> forces you to carry the conceptual weight of all those mutation methods. Your class is now coupled to the idea that collections can be modified, even if your code never modifies anything.

Worse, Array in .NET implements IList<T>. But arrays have a fixed size. Calling Add on an array throws NotSupportedException. This is a textbook LSP violation that exists precisely because of an ISP problem: IList<T> bundles reading and writing into a single contract, forcing fixed-size collections to implement methods they cannot meaningfully support.

The read-only interfaces arrive in .NET 4.5

For years, .NET developers asked Microsoft for read-only collection interfaces. The BCL team initially declined, arguing that the value did not justify the added complexity. Then WinRT arrived. The Windows Runtime exposed IVectorView<T> and IMapView<K, V>, and .NET needed corresponding types for interop. This external pressure finally pushed the team to introduce IReadOnlyCollection<T> and IReadOnlyList<T> in .NET 4.5.

The result is a textbook application of ISP:

// IEnumerable<T> — forward-only iteration, nothing more
public interface IEnumerable<out T> : IEnumerable
{
    IEnumerator<T> GetEnumerator();
}

// IReadOnlyCollection<T> — iteration plus a count
public interface IReadOnlyCollection<out T> : IEnumerable<T>
{
    int Count { get; }
}

// IReadOnlyList<T> — iteration, count, and indexed access
public interface IReadOnlyList<out T> : IReadOnlyCollection<T>
{
    T this[int index] { get; }
}

// ICollection<T> — adds mutation (Add, Remove, Clear)
public interface ICollection<T> : IEnumerable<T>
{
    int Count { get; }
    bool IsReadOnly { get; }
    void Add(T item);
    void Clear();
    bool Contains(T item);
    void CopyTo(T[] array, int arrayIndex);
    bool Remove(T item);
}

// IList<T> — adds indexed mutation (Insert, RemoveAt, indexer set)
public interface IList<T> : ICollection<T>
{
    T this[int index] { get; set; }
    int IndexOf(T item);
    void Insert(int index, T item);
    void RemoveAt(int index);
}

Notice the hierarchy. Each interface adds a narrow slice of capability. A method that only needs to iterate takes IEnumerable<T>. A method that also needs a count takes IReadOnlyCollection<T>. A method that needs indexed access takes IReadOnlyList<T>. And only a method that genuinely needs to mutate the collection takes ICollection<T> or IList<T>. This is ISP in action: each client depends only on the capability it actually uses.

The IQueryable hierarchy

LINQ provides another beautiful example. IQueryable<T> inherits from IEnumerable<T>, IQueryable, and IEnumerable. The capability of iterating over a collection is segregated from the capability of evaluating expression trees against a query provider. Code that only needs to iterate depends on IEnumerable<T>. Code that needs to build and translate expression trees depends on IQueryable<T>. The consuming code declares exactly the level of capability it requires.

Stream and the CanRead / CanWrite pattern

The System.IO.Stream class takes a different approach to the same problem. Rather than segregating into multiple interfaces, Stream uses capability flags: CanRead, CanWrite, CanSeek, and CanTimeout. Callers check these flags before invoking read or write operations.

This is a pragmatic compromise. A strict ISP application would split Stream into IReadableStream, IWritableStream, ISeekableStream, and various combinations. The BCL team decided that the combinatorial explosion of interfaces was worse than the capability-flag approach. This is a valid engineering trade-off, and it reminds us that ISP is a principle, not a law. Sometimes the cure is worse than the disease.

The practical guideline for .NET collection types

A widely-accepted guideline in modern .NET follows directly from ISP:

Accept the most general type you can. Return the most specific type you can.

For method parameters, prefer IEnumerable<T> (the most general). For return types, prefer IReadOnlyList<T> (the most specific read-only indexed collection). This way, callers of your method get the richest possible contract without mutation capability, and your method accepts the widest possible range of inputs.

// Good: accepts IEnumerable<T>, returns IReadOnlyList<T>
public IReadOnlyList<Customer> FilterActive(IEnumerable<Customer> customers)
{
    return customers.Where(c => c.IsActive).ToList();
}

// Bad: accepts List<Customer> (too specific), returns IEnumerable<Customer> (too vague)
public IEnumerable<Customer> FilterActive(List<Customer> customers)
{
    return customers.Where(c => c.IsActive);
}

Part 4: Recognizing Fat Interfaces in Your Own Code

Before you can fix an ISP violation, you need to spot one. Here are the telltale signs, ordered from obvious to subtle.

Sign 1: NotImplementedException or NotSupportedException

This is the most glaring symptom. If a class implements an interface and some methods throw NotImplementedException, one of two things is happening: the implementation is incomplete (a temporary state), or the interface is too broad for this class. If it is the latter, you have an ISP problem on the implementing side and almost certainly an LSP problem on the consuming side.

// Smells like ISP violation
public class ReadOnlyProductStore : IProductStore
{
    public Product GetById(int id) { /* works fine */ }
    public IReadOnlyList<Product> GetAll() { /* works fine */ }
    public void Add(Product product) => throw new NotSupportedException();
    public void Update(Product product) => throw new NotSupportedException();
    public void Delete(int id) => throw new NotSupportedException();
}

The ReadOnlyProductStore is telling you that it does not belong behind the IProductStore interface. It needs a read-only interface.

Sign 2: Clients that only use a subset of methods

Open any class that depends on an interface. Count the methods it actually calls. If it calls three out of twelve, the interface is too fat for this client. This is the canonical ISP violation, and it is far more common than the NotImplementedException variant.

public class ProductReportGenerator
{
    private readonly IProductRepository _repository;

    public ProductReportGenerator(IProductRepository repository)
    {
        _repository = repository;
    }

    public Report Generate()
    {
        // Only calls GetAll and GetById — never Add, Update, or Delete
        var products = _repository.GetAll();
        // ... build report ...
    }
}

The ProductReportGenerator depends on IProductRepository but only uses the read methods. It is coupled to the write methods unnecessarily. If someone adds a BulkDelete method to IProductRepository, the ProductReportGenerator is affected by the change even though it never deletes anything.

Sign 3: Mock objects in tests that have many Setup calls for unused methods

When you write unit tests using a mocking framework, pay attention to how many Setup or Returns calls you need. If you are setting up eight methods on a mock but the code under test only calls two, that is a strong signal that the interface is too fat.

// If you find yourself writing this:
var mock = new Mock<IDocumentService>();
mock.Setup(x => x.Upload(It.IsAny<Document>())).Returns(Task.CompletedTask);
mock.Setup(x => x.Download(It.IsAny<int>())).Returns(Task.FromResult(doc));
mock.Setup(x => x.Delete(It.IsAny<int>())).Returns(Task.CompletedTask);
mock.Setup(x => x.ExtractText(It.IsAny<int>())).Returns(Task.FromResult(""));
mock.Setup(x => x.GenerateThumbnail(It.IsAny<int>())).Returns(Task.FromResult(thumb));
// ... but the class under test only calls Download()
// ... you have an ISP problem.

Sign 4: Frequent recompilation of unrelated code

This was the original symptom at Xerox and it remains relevant today, especially in large solutions with many projects. If modifying an interface in one assembly forces recompilation of assemblies that do not use the changed method, you are experiencing the ISP violation's original pain point. In a modern .NET solution, this manifests as unnecessarily long dotnet build times and spurious CI failures in projects that should not be affected by the change.

Sign 5: Interface names that are vague or overly general

Names like IService, IManager, IHandler, or IRepository (without any qualifier) are often signs that the interface is trying to be everything to everyone. A well-segregated interface has a name that tells you exactly what it does: IProductReader, IOrderWriter, IAuditLogger, IThumbnailGenerator.

Part 5: Refactoring Fat Interfaces — A Step-by-Step Walkthrough

Let us take a realistic example and walk through the refactoring from a fat interface to well-segregated ones. We will use a scenario familiar to .NET web developers: a user repository.

The starting point: a fat IUserRepository

public interface IUserRepository
{
    // Read operations
    Task<User?> GetByIdAsync(int id);
    Task<User?> GetByEmailAsync(string email);
    Task<IReadOnlyList<User>> GetAllAsync();
    Task<IReadOnlyList<User>> SearchAsync(string query);

    // Write operations
    Task AddAsync(User user);
    Task UpdateAsync(User user);
    Task DeleteAsync(int id);

    // Bulk operations
    Task BulkImportAsync(IEnumerable<User> users);
    Task BulkDeleteAsync(IEnumerable<int> ids);

    // Reporting
    Task<int> GetTotalCountAsync();
    Task<IReadOnlyList<User>> GetRecentlyActiveAsync(DateTime since);
    Task<Dictionary<string, int>> GetRegistrationsByMonthAsync(int year);
}

Thirteen methods. Not enormous by real-world standards, but let us look at who actually calls what.

The web API controllers use GetByIdAsync, GetAllAsync, SearchAsync, AddAsync, UpdateAsync, and DeleteAsync. The admin bulk import tool uses BulkImportAsync and BulkDeleteAsync. The dashboard widget uses GetTotalCountAsync, GetRecentlyActiveAsync, and GetRegistrationsByMonthAsync. The authentication middleware uses only GetByEmailAsync.

Four clients, four different subsets. Every client is coupled to every other client's methods.

Step 1: Identify the client groups

Group the methods by which clients use them:

• Read (single): GetByIdAsync, GetByEmailAsync — used by controllers and auth middleware
• Read (collection): GetAllAsync, SearchAsync — used by controllers
• Write: AddAsync, UpdateAsync, DeleteAsync — used by controllers
• Bulk: BulkImportAsync, BulkDeleteAsync — used by admin tool
• Reporting: GetTotalCountAsync, GetRecentlyActiveAsync, GetRegistrationsByMonthAsync — used by dashboard

Step 2: Define focused interfaces

public interface IUserReader
{
    Task<User?> GetByIdAsync(int id);
    Task<User?> GetByEmailAsync(string email);
    Task<IReadOnlyList<User>> GetAllAsync();
    Task<IReadOnlyList<User>> SearchAsync(string query);
}

public interface IUserWriter
{
    Task AddAsync(User user);
    Task UpdateAsync(User user);
    Task DeleteAsync(int id);
}

public interface IUserBulkOperations
{
    Task BulkImportAsync(IEnumerable<User> users);
    Task BulkDeleteAsync(IEnumerable<int> ids);
}

public interface IUserReporting
{
    Task<int> GetTotalCountAsync();
    Task<IReadOnlyList<User>> GetRecentlyActiveAsync(DateTime since);
    Task<Dictionary<string, int>> GetRegistrationsByMonthAsync(int year);
}

Step 3: Optionally compose larger interfaces

If some clients genuinely need both reading and writing, you can compose:

public interface IUserRepository : IUserReader, IUserWriter { }

This is a common and idiomatic C# pattern. The web API controllers can depend on IUserRepository (which gives them read and write), while the dashboard depends only on IUserReporting, and the auth middleware depends only on IUserReader.

Step 4: Update the implementing class

The implementing class does not change much. It simply declares that it implements all the interfaces:

public class SqlUserRepository : IUserRepository, IUserBulkOperations, IUserReporting
{
    private readonly AppDbContext _db;

    public SqlUserRepository(AppDbContext db) => _db = db;

    // IUserReader
    public async Task<User?> GetByIdAsync(int id)
        => await _db.Users.FindAsync(id);

    public async Task<User?> GetByEmailAsync(string email)
        => await _db.Users.FirstOrDefaultAsync(u => u.Email == email);

    public async Task<IReadOnlyList<User>> GetAllAsync()
        => await _db.Users.OrderBy(u => u.Name).ToListAsync();

    public async Task<IReadOnlyList<User>> SearchAsync(string query)
        => await _db.Users.Where(u => u.Name.Contains(query)).ToListAsync();

    // IUserWriter
    public async Task AddAsync(User user)
    {
        _db.Users.Add(user);
        await _db.SaveChangesAsync();
    }

    public async Task UpdateAsync(User user)
    {
        _db.Users.Update(user);
        await _db.SaveChangesAsync();
    }

    public async Task DeleteAsync(int id)
    {
        var user = await _db.Users.FindAsync(id);
        if (user is not null)
        {
            _db.Users.Remove(user);
            await _db.SaveChangesAsync();
        }
    }

    // IUserBulkOperations
    public async Task BulkImportAsync(IEnumerable<User> users)
    {
        _db.Users.AddRange(users);
        await _db.SaveChangesAsync();
    }

    public async Task BulkDeleteAsync(IEnumerable<int> ids)
    {
        var users = await _db.Users.Where(u => ids.Contains(u.Id)).ToListAsync();
        _db.Users.RemoveRange(users);
        await _db.SaveChangesAsync();
    }

    // IUserReporting
    public async Task<int> GetTotalCountAsync()
        => await _db.Users.CountAsync();

    public async Task<IReadOnlyList<User>> GetRecentlyActiveAsync(DateTime since)
        => await _db.Users.Where(u => u.LastActiveAt >= since).ToListAsync();

    public async Task<Dictionary<string, int>> GetRegistrationsByMonthAsync(int year)
        => await _db.Users
            .Where(u => u.CreatedAt.Year == year)
            .GroupBy(u => u.CreatedAt.Month)
            .ToDictionaryAsync(
                g => g.Key.ToString("D2"),
                g => g.Count());
}

The class is the same size it was before. The difference is in how it is consumed. Each client now depends on exactly the interface it needs.

Step 5: Register in DI

In your Program.cs or DI configuration:

builder.Services.AddScoped<SqlUserRepository>();
builder.Services.AddScoped<IUserReader>(sp => sp.GetRequiredService<SqlUserRepository>());
builder.Services.AddScoped<IUserWriter>(sp => sp.GetRequiredService<SqlUserRepository>());
builder.Services.AddScoped<IUserRepository>(sp => sp.GetRequiredService<SqlUserRepository>());
builder.Services.AddScoped<IUserBulkOperations>(sp => sp.GetRequiredService<SqlUserRepository>());
builder.Services.AddScoped<IUserReporting>(sp => sp.GetRequiredService<SqlUserRepository>());

Now each class can request exactly the interface it needs through constructor injection:

// The dashboard only sees reporting methods
public class DashboardService
{
    private readonly IUserReporting _reporting;
    public DashboardService(IUserReporting reporting) => _reporting = reporting;
}

// The auth middleware only sees read methods
public class AuthenticationHandler
{
    private readonly IUserReader _users;
    public AuthenticationHandler(IUserReader users) => _users = users;
}

// The admin tool only sees bulk operations
public class BulkImportService
{
    private readonly IUserBulkOperations _bulk;
    public BulkImportService(IUserBulkOperations bulk) => _bulk = bulk;
}

The payoff

After this refactoring, consider what happens when the reporting team asks for a new method, GetChurnRateAsync. You add it to IUserReporting and implement it in SqlUserRepository. The auth middleware, the web controllers, and the admin tool are completely unaffected. They do not depend on IUserReporting. Their interfaces have not changed. Their tests do not need to be updated. Their assemblies do not need to be recompiled (in a multi-project solution). This is precisely the decoupling the ISP was designed to achieve.

Part 6: ISP and the Other SOLID Principles

The SOLID principles are not isolated rules. They interact with and reinforce each other. Understanding how ISP relates to the other four helps you apply all of them more effectively.

ISP and Single Responsibility Principle (SRP)

SRP says a class should have one reason to change. ISP says a client should not depend on methods it does not use. In practice, a fat interface often indicates that the implementing class has multiple responsibilities. Splitting the interface along ISP lines frequently reveals SRP violations in the implementation, too. The user repository refactoring above hints at this: the reporting queries are a conceptually different responsibility from the CRUD operations. In a mature system, you might split them into separate classes behind separate interfaces.

But they can diverge. An interface might be fat for ISP purposes while the implementing class is perfectly SRP-compliant. Consider a JsonSerializer interface with methods for serialization and deserialization. Both operations are the same responsibility (JSON conversion), but a client that only serializes does not need the deserialization methods. That is an ISP concern, not an SRP concern.

ISP and Open/Closed Principle (OCP)

OCP says software entities should be open for extension but closed for modification. Fat interfaces make OCP harder to follow because adding a method to an interface is a modification that forces changes in every implementation. Well-segregated interfaces are easier to extend: you can add new interfaces for new capabilities without modifying existing ones.

ISP and Liskov Substitution Principle (LSP)

ISP and LSP are two sides of the same coin. ISP prevents clients from depending on methods they do not use (the client perspective). LSP prevents implementations from failing to honor the contract (the implementation perspective). Fat interfaces lead to both problems: the client depends on too much, and the implementation throws NotSupportedException for things it cannot do. Fix the ISP violation, and the LSP violation often disappears automatically. Array implementing IList<T> is the canonical example: the ISP violation (forcing array consumers to see Add) directly causes the LSP violation (Add throwing an exception).

ISP and Dependency Inversion Principle (DIP)

DIP says high-level modules should not depend on low-level modules; both should depend on abstractions. ISP refines this: the abstractions themselves should be well-designed. A fat abstraction is not much better than a concrete dependency. DIP tells you to use interfaces. ISP tells you to make those interfaces the right size.

Part 7: ISP in ASP.NET Core and Modern .NET

Modern .NET and ASP.NET Core provide several features and patterns that interact directly with ISP.

Dependency injection and interface-per-concern

ASP.NET Core's built-in DI container makes ISP natural to apply. You register services by interface, and each consumer requests only the interface it needs. The DI container resolves everything at runtime. This is exactly what we showed in the user repository example above.

A particularly powerful pattern is registering a single implementation class behind multiple interfaces:

// Register the concrete type once
builder.Services.AddScoped<SqlUserRepository>();

// Forward each interface to the same instance
builder.Services.AddScoped<IUserReader>(sp => sp.GetRequiredService<SqlUserRepository>());
builder.Services.AddScoped<IUserWriter>(sp => sp.GetRequiredService<SqlUserRepository>());

This preserves ISP at the consumer level while keeping a single implementation at the runtime level. The consumer sees a narrow interface; the container provides the full implementation.

Minimal APIs and endpoint-specific dependencies

ASP.NET Core minimal APIs encourage you to inject dependencies directly into endpoint handlers rather than into controller classes. This makes ISP violations more visible, because each handler declares exactly what it needs:

app.MapGet("/users/{id}", async (int id, IUserReader reader) =>
{
    var user = await reader.GetByIdAsync(id);
    return user is not null ? Results.Ok(user) : Results.NotFound();
});

app.MapPost("/users", async (User user, IUserWriter writer) =>
{
    await writer.AddAsync(user);
    return Results.Created($"/users/{user.Id}", user);
});

app.MapGet("/dashboard/stats", async (IUserReporting reporting) =>
{
    var count = await reporting.GetTotalCountAsync();
    return Results.Ok(new { TotalUsers = count });
});

Each endpoint depends on exactly the interface it needs. There is no controller class pulling in twelve dependencies that different action methods use in different combinations. Minimal APIs make ISP almost effortless.

Default interface methods (C# 8+)

C# 8 introduced default interface methods (DIMs), which let you add methods to an interface with a default implementation, so existing implementing classes are not forced to change.

public interface IUserReader
{
    Task<User?> GetByIdAsync(int id);
    Task<User?> GetByEmailAsync(string email);
    Task<IReadOnlyList<User>> GetAllAsync();
    Task<IReadOnlyList<User>> SearchAsync(string query);

    // Default implementation — existing implementers are not forced to provide this
    Task<bool> ExistsAsync(int id)
        => GetByIdAsync(id).ContinueWith(t => t.Result is not null);
}

DIMs can mitigate ISP pressure by allowing you to grow an interface without breaking existing implementations. But they are not a substitute for proper segregation. If different clients need fundamentally different subsets of an interface, no amount of default methods will fix the coupling. DIMs are best used for adding convenience methods that build on existing methods, not for bolting unrelated capabilities onto an interface.

The IHost and IHostBuilder interfaces

ASP.NET Core's hosting model itself demonstrates ISP. The IHost interface is deliberately narrow: StartAsync, StopAsync, Dispose, and a Services property. The builder (IHostBuilder) is separate. Configuration, logging, and DI are all configured through the builder, not through the host. The running host exposes only what running code needs. This separation allows different consumers (health check probes, graceful shutdown handlers, background services) to depend on the narrow IHost interface without being coupled to the builder's configuration API.

Part 8: ISP Beyond OOP — Microservices, APIs, and Event-Driven Systems

The ISP is not limited to C# interfaces in a single codebase. The same principle applies at architectural boundaries.

REST API design

A REST API is an interface in the broadest sense. If you expose a single /api/users endpoint that supports GET, POST, PUT, DELETE, PATCH, and a dozen query parameters, every consumer of that API is coupled to the full surface area. A consumer that only reads user data still needs to understand the write endpoints exist (at minimum, to ignore them). If you version the API and change a write endpoint, read-only consumers must still validate that nothing they depend on has changed.

API segregation looks like this: separate read endpoints from write endpoints, or even separate them into distinct services. A read-optimized service with caching sits behind /api/users/query, while a write service with validation and event publishing sits behind /api/users/command. This is the CQRS (Command Query Responsibility Segregation) pattern, and it is ISP applied at the service boundary.

Message contracts in event-driven systems

In an event-driven architecture, messages are interfaces. If you define a single UserEvent class with fields for creation, update, deletion, and password reset, every subscriber must deserialize and ignore the fields it does not care about. Worse, if you add a field for a new event type, every subscriber's deserialization might break.

ISP-compliant event design uses separate event types: UserCreatedEvent, UserUpdatedEvent, UserDeletedEvent, UserPasswordResetEvent. Each subscriber handles only the events it cares about. This is exactly the ISP applied to message contracts.

gRPC service definitions

gRPC uses Protocol Buffers to define service contracts. A .proto file with 30 RPC methods in a single service definition is a fat interface. Clients generated from this proto file will have stubs for all 30 methods, even if they only call two. The idiomatic gRPC approach is to define multiple, focused service definitions in separate .proto files (or at least separate service blocks within the same file). This keeps the generated client code lean and reduces the coupling between different consumers.

Part 9: Common Pitfalls and How to Avoid Them

Pitfall 1: Over-segregation

The most common mistake when learning ISP is splitting interfaces too aggressively. If you end up with one interface per method, you have not improved anything. You have just traded one problem (fat interfaces) for another (a proliferation of micro-interfaces that are individually meaningless and collectively confusing).

The rule of thumb: split when different clients use different subsets. If every client uses every method, there is nothing to split. If you find yourself creating ICanAdd, ICanDelete, ICanUpdate, and ICanGetById as four separate single-method interfaces, step back and ask whether any client actually uses ICanAdd without also using ICanUpdate. If the answer is no, merge them.

Pitfall 2: Splitting by implementation detail instead of client need

Interfaces should be designed from the perspective of the client, not the implementation. Do not split an interface because the implementing class has two private fields. Split it because two clients need different subsets of the public contract. The implementation is free to use whatever internal structure it wants.

A bad split:

// Split based on which database table the methods hit — an implementation detail
public interface IUserTableQueries { /* queries on User table */ }
public interface IAuditLogTableQueries { /* queries on AuditLog table */ }

A good split:

// Split based on what consumers need
public interface IUserReader { /* methods for reading user data */ }
public interface IAuditTrail { /* methods for recording and querying audit events */ }

Pitfall 3: Breaking changes during refactoring

When you refactor a fat interface into multiple smaller ones, you are making a breaking change. Every consumer of the original interface must be updated to depend on one of the new interfaces. In a small codebase this is trivial. In a large codebase with hundreds of consumers, it can be daunting.

The pragmatic approach: keep the original fat interface as a composition of the new smaller ones, at least temporarily.

// Old interface — now composed of smaller ones
public interface IUserRepository : IUserReader, IUserWriter, IUserBulkOperations, IUserReporting
{
    // No new members — just aggregates the smaller interfaces
}

Existing code continues to compile. New code can depend on the smaller interfaces. Over time, you can migrate consumers one by one and eventually deprecate the fat composite interface.

Pitfall 4: Ignoring ISP in test doubles

If your test doubles (mocks, stubs, fakes) implement the full fat interface, you are masking the ISP violation. The tests work, but they quietly accept the coupling. When you move to well-segregated interfaces, your test doubles become simpler and your tests become more focused. A test for the dashboard should only need a mock of IUserReporting, not a mock of the entire repository.

Pitfall 5: Applying ISP to value objects and DTOs

ISP is about behavioral contracts — methods and their dependencies. It does not apply to data transfer objects, records, or value objects in the same way. A UserDto with fifteen properties is not an ISP violation. It is a data container. The ISP applies to the interfaces through which behavior is exposed, not to the shape of data structures. (You might have other concerns about a DTO with fifteen properties — perhaps it is doing too much — but that is SRP, not ISP.)

Part 10: ISP in Blazor WebAssembly

For those of us building Blazor WebAssembly applications — like this very blog you are reading on Observer Magazine — ISP has practical implications for how we structure our services.

Service interfaces for Blazor components

In a Blazor WASM app, components inject services to fetch data, manage state, and interact with APIs. A common mistake is to create a single IApiService that every component depends on:

// Fat interface — every component depends on everything
public interface IApiService
{
    Task<IReadOnlyList<BlogPost>> GetBlogPostsAsync();
    Task<BlogPost?> GetBlogPostAsync(string slug);
    Task<IReadOnlyList<Product>> GetProductsAsync();
    Task<Product?> GetProductAsync(int id);
    Task SaveProductAsync(Product product);
    Task DeleteProductAsync(int id);
    Task<UserProfile> GetCurrentUserAsync();
    Task UpdateUserProfileAsync(UserProfile profile);
    Task<WeatherForecast[]> GetForecastAsync();
}

The blog components only need blog methods. The product showcase only needs product methods. The user profile page only needs user methods. Every component is coupled to every other component's data-fetching needs.

A well-segregated design:

public interface IBlogService
{
    Task<IReadOnlyList<BlogPostMetadata>> GetPostsAsync();
    Task<BlogPostMetadata?> GetPostAsync(string slug);
    Task<string> GetPostHtmlAsync(string slug);
}

public interface IProductCatalog
{
    Task<IReadOnlyList<Product>> GetProductsAsync();
    Task<Product?> GetProductAsync(int id);
}

public interface IProductEditor
{
    Task SaveProductAsync(Product product);
    Task DeleteProductAsync(int id);
}

public interface IUserProfileService
{
    Task<UserProfile> GetCurrentUserAsync();
    Task UpdateUserProfileAsync(UserProfile profile);
}

Each Blazor component injects only the interface it needs. The blog page depends on IBlogService. The product detail page depends on IProductCatalog. The admin editor depends on IProductEditor. When you change the blog data format, the product components are completely unaffected.

Testability benefits in Blazor

This segregation pays enormous dividends in bUnit tests. Consider testing a blog post component:

[Fact]
public void BlogPost_RendersTitle()
{
    // With segregated interfaces, the mock is minimal
    var mockBlog = new Mock<IBlogService>();
    mockBlog.Setup(b => b.GetPostAsync("test-slug"))
        .ReturnsAsync(new BlogPostMetadata { Title = "Test Post", Slug = "test-slug" });
    mockBlog.Setup(b => b.GetPostHtmlAsync("test-slug"))
        .ReturnsAsync("<p>Hello</p>");

    using var ctx = new BunitContext();
    ctx.Services.AddSingleton(mockBlog.Object);

    var cut = ctx.Render<BlogPost>(parameters =>
        parameters.Add(p => p.Slug, "test-slug"));

    cut.Find("h1").TextContent.ShouldBe("Test Post");
}

No need to mock product methods, user methods, or weather methods. The test sets up exactly the interface the component uses. This makes tests faster to write, easier to read, and more resistant to changes in unrelated parts of the system.

Part 11: Practical Heuristics — When to Split and When to Stop

After all this theory and examples, here are concrete heuristics you can apply in your daily work.

Split when

1. Two or more clients use different subsets of the same interface. This is the canonical ISP trigger.
2. You find yourself writing NotImplementedException in an implementation. The interface is asking for something this class cannot do.
3. Your mocks are bloated. If setting up a mock requires configuring methods the test never exercises, the interface is too fat for this consumer.
4. A change to one method ripples to unrelated consumers. If adding a reporting method forces you to update an authentication handler, the coupling is wrong.
5. You are splitting a monolith into microservices. Each service should expose a focused API, not a mirror of the monolith's fat interface.

Do not split when

1. Every client uses every method. If there is no divergence in how clients consume the interface, splitting adds complexity without benefit.
2. The interface has fewer than five methods and they are all cohesive. An ILogger with five log-level methods is fine.
3. The split would create single-method interfaces that are always used together. If ICanRead and ICanCount are always injected together, merge them into IReadOnlyCollection (which is exactly what Microsoft did).
4. You are working on a throwaway prototype. ISP is an investment in long-term maintainability. If the code will be deleted next sprint, the investment does not pay off.
5. The interface is a well-known framework type. Do not wrap ILogger<T> in your own IMyLogger just to remove methods you do not call. The framework type is well-understood, widely documented, and carries minimal ISP risk because its methods are highly cohesive.

The "one more method" test

When someone asks to add a method to an existing interface, ask yourself: "Will every existing client of this interface benefit from or be unaffected by this addition?" If the answer is yes, add the method. If the answer is "no, this is only for the new admin panel," create a new interface for the admin panel's needs. This single question, asked consistently, prevents most ISP violations from ever forming.

Part 12: A Real-World Example from This Project

Observer Magazine itself — the Blazor WebAssembly application you are reading right now — applies ISP throughout its service layer. Here is a concrete example.

The application has an analytics service for tracking page views and reactions. The original design might have been a single IAnalyticsService:

public interface IAnalyticsService
{
    Task TrackPageViewAsync(string pageName, string details = "");
    Task IncrementViewAsync(string slug);
    Task<int?> GetViewCountAsync(string slug);
    Task AddReactionAsync(string slug, string reaction);
    Task<Dictionary<string, int>?> GetReactionsAsync(string slug);
}

But consider the consumers. The Blog.razor page only calls TrackPageViewAsync to record that someone visited the blog index. The BlogPost.razor page calls IncrementViewAsync, GetViewCountAsync, and GetReactionsAsync. The Reactions.razor component calls AddReactionAsync and GetReactionsAsync.

Different components use different subsets. In a fully ISP-compliant design, these would be separate interfaces. In practice, for a project this size, the trade-off is debatable — the interface is small, the team is small, and the cost of the coupling is low. But if the analytics service grows to include A/B testing, funnel tracking, and conversion metrics, the pressure to split will increase. Knowing where to draw the line is as important as knowing the principle.

Part 13: ISP in the Age of Source Generators and AOT

Modern .NET 10 introduces patterns that interact with ISP in interesting ways.

Source generators and minimal interfaces

Source generators in .NET can produce boilerplate code from interfaces. The System.Text.Json source generator, for example, reads your serialization attributes and generates optimized serializer code at compile time. For this to work well, the interfaces your generators consume should be focused and stable. A fat interface that changes frequently will trigger frequent regeneration and recompilation — echoing the original Xerox build-time problem.

Native AOT and interface dispatch

Native Ahead-of-Time compilation eliminates the JIT compiler and produces native binaries. One consequence: the AOT compiler must statically analyze all possible interface implementations at compile time. Fat interfaces with many implementations can increase the size of the dispatch tables the compiler generates. Well-segregated interfaces with fewer implementations per interface produce leaner binaries. This is a marginal concern for most applications, but it becomes relevant at the edges — embedded systems, serverless functions with tight cold-start budgets, and mobile applications where binary size matters.

Keyed services in .NET 8+

.NET 8 introduced keyed services in the DI container, allowing you to register multiple implementations of the same interface distinguished by a key:

builder.Services.AddKeyedScoped<IUserReader, CachedUserReader>("cached");
builder.Services.AddKeyedScoped<IUserReader, SqlUserReader>("sql");

This interacts with ISP by making it easier to have multiple implementations of the same focused interface for different contexts (cached for the web layer, direct SQL for the admin layer). Without segregated interfaces, keyed services become harder to use because the keys would need to distinguish not just the implementation but also the subset of the interface the consumer needs.

Part 14: Summary and Takeaways

The Interface Segregation Principle is one of the most practical of the SOLID principles. It directly addresses a problem that every growing codebase eventually faces: interfaces that started simple and grew fat as requirements accumulated. The principle is not about counting methods or enforcing a maximum interface size. It is about ensuring that each consumer of an interface depends only on the capabilities it actually uses.

The key ideas to carry with you:

Design interfaces from the client's perspective. Ask "what does this consumer need?" not "what can this class do?" The answers to those two questions should produce different interfaces.

The .NET BCL is your teacher. Study the progression from IEnumerable<T> to IReadOnlyCollection<T> to IReadOnlyList<T> to ICollection<T> to IList<T>. Each step adds a narrow slice of capability. This is ISP done well.

Composition over proliferation. When you split interfaces, compose them back together for clients that need the full surface area. IUserRepository : IUserReader, IUserWriter is idiomatic C#.

The principle is fractal. ISP applies at the class level (C# interfaces), the service level (REST APIs, gRPC services), the system level (microservice boundaries), and the event level (message contracts). The same question — "is this consumer forced to depend on things it does not use?" — applies everywhere.

Know when to stop. Not every interface needs splitting. Not every three-method interface hides an ISP violation. Apply the principle when you see the symptoms: bloated mocks, unrelated recompilations, NotImplementedException, and clients that use three out of twelve methods.

Resources

Here are the key resources for further study:

• Robert C. Martin, Agile Software Development: Principles, Patterns, and Practices (Prentice Hall, 2002) — the original book-length treatment of all five SOLID principles, including the ISP chapter with the Xerox story and ATM transaction example.
• Robert C. Martin, "The Interface Segregation Principle" — the original article available at https://web.archive.org/web/20150924054349/http://www.objectmentor.com/resources/articles/isp.pdf
• Microsoft, "Guidelines for Collections" — https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/guidelines-for-collections
• NDepend Blog, "SOLID Design in C#: The Interface Segregation Principle (ISP) with Examples" — https://blog.ndepend.com/solid-design-the-interface-segregation-principle-isp/
• DevIQ, "Interface Segregation Principle" — https://deviq.com/principles/interface-segregation/
• Scott Hannen, "The Interface Segregation Principle Applied in C#/.NET" — https://scotthannen.org/blog/2019/01/01/interface-segregation-principle-applied.html
• Vladimir Khorikov (Enterprise Craftsmanship), "IEnumerable vs IReadOnlyList" — https://enterprisecraftsmanship.com/posts/ienumerable-vs-ireadonlylist/

You have just been bitten by a violation of the Liskov Substitution Principle.

The Liskov Substitution Principle — the "L" in SOLID — is arguably the most misunderstood and the most consequential of the five principles. It is the principle that separates an inheritance hierarchy that works from one that is a ticking time bomb. It is the principle that explains why a Square is not a Rectangle, why a ReadOnlyCollection should not inherit from List<T>, and why your carefully designed plugin architecture falls apart every time someone writes a new adapter.

This article is going to take you through the entire story — from the academic origins at OOPSLA 1987 to the practical rules you should apply in your C# code today. We will examine real violations, write real fixes, explore the relationship between LSP and Design by Contract, and end with a checklist you can pin to your wall.

Let us begin.

Part 1: Origins — Barbara Liskov and the Birth of a Principle

To understand the Liskov Substitution Principle, you need to understand the person behind it.

Barbara Liskov was born in 1939 in Los Angeles. She earned her bachelor's degree in mathematics from UC Berkeley in 1961, then worked at the Mitre Corporation before returning to academia. In 1968, she became one of the first women in the United States to earn a PhD in computer science, from Stanford, under the supervision of John McCarthy — the father of artificial intelligence. Her thesis was on chess endgame programs, and during that work she developed the killer heuristic, a technique still used in game tree search algorithms.

After Stanford, Liskov joined MIT in 1972, where she led the design and implementation of the CLU programming language. CLU was groundbreaking. It introduced concepts that are foundational to every language you use today: data abstraction, encapsulation, iterators, parametric polymorphism, and exception handling. If you have ever written a foreach loop, you owe a debt to CLU. If you have ever defined an interface, you are working in an intellectual tradition that traces back to Liskov's research group at MIT in the 1970s.

In 1987, Liskov delivered a keynote address at OOPSLA (the Object-Oriented Programming, Systems, Languages, and Applications conference) titled Data Abstraction and Hierarchy. In that talk, she presented an informal rule about when one type can safely stand in for another:

What is wanted here is something like the following substitution property: If for each object o1 of type S there is an object o2 of type T such that for all programs P defined in terms of T, the behavior of P is unchanged when o1 is substituted for o2, then S is a subtype of T.

This is the original formulation. It is deliberately informal — Liskov herself later called it an "informal rule." The key insight is deceptively simple: if your code works with a base type, it should continue to work when you hand it a derived type. No surprises. No exceptions. No "well, except when..."

Seven years later, in 1994, Liskov and Jeannette Wing published a rigorous formalization in their paper A Behavioral Notion of Subtyping in ACM Transactions on Programming Languages and Systems. This paper introduced the history constraint (sometimes called the "history rule"), which addresses what happens when a subtype adds new methods that can mutate state in ways the supertype never allowed. This was the key innovation beyond Bertrand Meyer's earlier Design by Contract work.

In 2000, Robert C. Martin published his paper Design Principles and Design Patterns, which collected five object-oriented design principles. Around 2004, Michael Feathers coined the SOLID acronym to make them memorable. The "L" stands for Liskov Substitution.

In 2008, Barbara Liskov received the Turing Award — the highest honor in computer science — for her contributions to programming language and system design, especially related to data abstraction, fault tolerance, and distributed computing.

Why This History Matters

You might be wondering why we are spending time on history in a programming article. Here is why: the Liskov Substitution Principle is not a style preference. It is not a "clean code" guideline that you can take or leave. It is a mathematically grounded property of type systems. When you violate it, you break the fundamental contract that makes polymorphism work. Understanding that it comes from the same intellectual tradition as data abstraction, formal verification, and type theory helps you take it seriously — and helps you understand why certain designs fail.

Part 2: The Principle in Plain Language

Let us strip away the formal notation and state the principle as simply as possible.

If you have code that works correctly with a base type, it must also work correctly with any subtype of that base type, without the calling code needing to know or care which subtype it received.

That is the entire principle. Everything else — preconditions, postconditions, invariants, the history rule — is a consequence of this one requirement.

Think of it like a vending machine. The machine's contract says: "Insert a coin, press a button, receive a drink." If you insert a US quarter, it works. If you insert a Canadian quarter (same size, same shape), it should also work — because the machine's contract is defined in terms of "a coin of this size and weight," not "a US quarter specifically." But if you insert a wooden token that is the same size but does not conduct electricity for the coin sensor, the machine jams. The wooden token looks like a valid substitution from the outside, but it violates the behavioral contract.

LSP is about behavioral compatibility, not just structural compatibility. A type can implement all the same methods, have all the same properties, and still violate LSP if its behavior breaks the expectations of code written against the base type.

The Three Levels of Substitutability

It helps to think about substitutability at three increasingly strict levels:

Level 1: Syntactic substitutability. The subtype compiles wherever the base type is expected. In C#, this is enforced by the compiler. If Dog inherits from Animal, you can pass a Dog to any method that accepts an Animal. This is necessary but not sufficient for LSP.

Level 2: Semantic substitutability. The subtype behaves correctly wherever the base type is expected. Methods return meaningful results, state transitions are valid, and no unexpected exceptions are thrown. This is what LSP demands.

Level 3: Behavioral equivalence. The subtype behaves identically to the base type. This is actually too strong — LSP does not require identical behavior. A SortedList<T> does not behave identically to List<T> (it maintains sorted order), but it can still be a valid behavioral subtype if the base type's contract does not specify insertion order.

The sweet spot — and the requirement of LSP — is Level 2. Subtypes must honor the contracts of their base types while being free to extend them in compatible ways.

Part 3: The Formal Rules — Contracts, Preconditions, and the History Constraint

The Liskov Substitution Principle can be decomposed into a set of concrete rules. These rules are drawn from Liskov and Wing's 1994 paper and from Bertrand Meyer's Design by Contract methodology. Understanding each one will let you mechanically check whether a given inheritance relationship is valid.

Rule 1: Contravariance of Preconditions

A subtype must not strengthen preconditions.

A precondition is a condition that must be true before a method can be called. If the base class method accepts any positive integer, the subtype method must also accept any positive integer. It may accept more (like zero or negative integers), but it must not accept less.

Here is a violation in C#:

public class BaseProcessor
{
    public virtual void Process(int value)
    {
        // Accepts any integer
        Console.WriteLine($"Processing {value}");
    }
}

public class StrictProcessor : BaseProcessor
{
    public override void Process(int value)
    {
        // VIOLATION: Strengthened precondition
        if (value < 0)
            throw new ArgumentOutOfRangeException(
                nameof(value), "Value must be non-negative");

        Console.WriteLine($"Strictly processing {value}");
    }
}

Code written against BaseProcessor legitimately passes -5 and expects it to work. StrictProcessor blows up. That is an LSP violation.

The fix is to either relax the precondition or restructure the hierarchy so that StrictProcessor does not inherit from BaseProcessor:

public interface IProcessor
{
    void Process(int value);
}

public class GeneralProcessor : IProcessor
{
    public void Process(int value)
    {
        Console.WriteLine($"Processing {value}");
    }
}

public class NonNegativeProcessor : IProcessor
{
    // The interface contract now explicitly documents
    // what each implementation accepts
    public void Process(int value)
    {
        if (value < 0)
            throw new ArgumentOutOfRangeException(
                nameof(value), "Value must be non-negative");

        Console.WriteLine($"Strictly processing {value}");
    }
}

Now neither class claims to substitute for the other. They both implement a shared interface, and the caller chooses based on their needs.

Rule 2: Covariance of Postconditions

A subtype must not weaken postconditions.

A postcondition is a guarantee about what is true after a method returns. If the base class method guarantees that the return value is non-null, the subtype must also return non-null. The subtype may strengthen the postcondition (e.g., guarantee the return value is also non-empty), but it must not weaken it.

public class DataFetcher
{
    public virtual IReadOnlyList<string> FetchRecords()
    {
        // Postcondition: always returns a non-null list
        return new List<string> { "default" };
    }
}

public class LazyDataFetcher : DataFetcher
{
    public override IReadOnlyList<string>? FetchRecords()
    {
        // VIOLATION: Can return null, weakening the postcondition
        // (In practice, C# nullable reference types would catch this,
        // but the principle applies regardless of language features)
        return null;
    }
}

Any caller that trusts the base class contract and writes var count = fetcher.FetchRecords().Count; will get a NullReferenceException. The postcondition was weakened.

Rule 3: Invariant Preservation

A subtype must preserve all invariants of the base type.

An invariant is a condition that is always true for an object throughout its lifetime. If the base class guarantees that Balance >= 0 at all times, every subtype must also maintain Balance >= 0 at all times.

public class BankAccount
{
    public decimal Balance { get; protected set; }

    public BankAccount(decimal initialBalance)
    {
        if (initialBalance < 0)
            throw new ArgumentException("Initial balance must be non-negative");
        Balance = initialBalance;
    }

    // Invariant: Balance >= 0
    public virtual void Withdraw(decimal amount)
    {
        if (amount > Balance)
            throw new InvalidOperationException("Insufficient funds");
        Balance -= amount;
    }
}

public class OverdraftAccount : BankAccount
{
    public decimal OverdraftLimit { get; }

    public OverdraftAccount(decimal initialBalance, decimal overdraftLimit)
        : base(initialBalance)
    {
        OverdraftLimit = overdraftLimit;
    }

    public override void Withdraw(decimal amount)
    {
        // VIOLATION: Allows Balance to go negative,
        // breaking the base class invariant
        if (amount > Balance + OverdraftLimit)
            throw new InvalidOperationException("Exceeds overdraft limit");
        Balance -= amount;
    }
}

Code that depends on the BankAccount invariant (Balance >= 0) will produce incorrect results when handed an OverdraftAccount. For example, a report that calculates "accounts with zero balance" by checking account.Balance == 0 will miss overdrafted accounts entirely.

The fix depends on your domain. One approach: do not make OverdraftAccount inherit from BankAccount. Instead, define a more general IAccount interface whose contract does not promise non-negative balances, and let each implementation document its own invariants.

public interface IAccount
{
    decimal Balance { get; }
    void Withdraw(decimal amount);
    // Contract: Withdraw throws if amount exceeds
    // the account's available funds (definition varies by type)
}

public class StandardAccount : IAccount
{
    public decimal Balance { get; private set; }

    public StandardAccount(decimal initialBalance)
    {
        if (initialBalance < 0)
            throw new ArgumentException("Must be non-negative");
        Balance = initialBalance;
    }

    public void Withdraw(decimal amount)
    {
        if (amount > Balance)
            throw new InvalidOperationException("Insufficient funds");
        Balance -= amount;
    }
}

public class OverdraftAccount : IAccount
{
    public decimal Balance { get; private set; }
    public decimal OverdraftLimit { get; }

    public OverdraftAccount(decimal initialBalance, decimal overdraftLimit)
    {
        Balance = initialBalance;
        OverdraftLimit = overdraftLimit;
    }

    public void Withdraw(decimal amount)
    {
        if (amount > Balance + OverdraftLimit)
            throw new InvalidOperationException("Exceeds overdraft limit");
        Balance -= amount;
    }
}

Rule 4: The History Constraint

A subtype must not allow state changes that the base type's contract forbids.

This is the rule that Liskov and Wing added in their 1994 paper, and it is the one most developers have never heard of. It says: if the base type is immutable, a subtype must also be immutable (at least from the perspective of the base type's interface). If the base type's specification says a property can only increase, the subtype must not allow it to decrease.

The classic example: an immutable point and a mutable point.

public class ImmutablePoint
{
    public int X { get; }
    public int Y { get; }

    public ImmutablePoint(int x, int y)
    {
        X = x;
        Y = y;
    }
}

public class MutablePoint : ImmutablePoint
{
    // VIOLATION: Adds mutation capability that contradicts
    // the base class's immutability contract
    public new int X { get; set; }
    public new int Y { get; set; }

    public MutablePoint(int x, int y) : base(x, y)
    {
        X = x;
        Y = y;
    }

    public void MoveTo(int newX, int newY)
    {
        X = newX;
        Y = newY;
    }
}

Code that stores an ImmutablePoint in a dictionary as a key (relying on the fact that X and Y will never change, and therefore the hash code is stable) will corrupt the dictionary if a MutablePoint sneaks in and then gets mutated. The history constraint says this inheritance relationship is invalid because the subtype introduces state transitions that the base type's history forbids.

Rule 5: Exception Compatibility

A subtype must not throw new exceptions that the base type's contract does not permit.

If the base class method is documented to throw ArgumentException on invalid input and IOException on I/O failure, a subtype should not introduce SecurityException or NotImplementedException. The calling code is prepared to handle certain exceptions; introducing new ones breaks the contract.

public abstract class FileStore
{
    /// <summary>
    /// Saves data to the store.
    /// Throws IOException if the write fails.
    /// Throws ArgumentNullException if data is null.
    /// </summary>
    public abstract void Save(byte[] data);
}

public class EncryptedFileStore : FileStore
{
    public override void Save(byte[] data)
    {
        ArgumentNullException.ThrowIfNull(data);

        // VIOLATION: Throws an exception type the base
        // class contract never mentioned
        throw new CryptographicException(
            "Encryption key not configured");
    }
}

The fix: either make CryptographicException inherit from IOException (not ideal), or document the base class contract to allow for more general exceptions, or handle the encryption setup in the constructor so Save never encounters this state.

Signature Rules

In addition to the behavioral rules above, LSP also implies structural rules at the type level. C# enforces most of these automatically:

Contravariance of method parameter types in the subtype. If the base method accepts Animal, the override should accept Animal or a more general type. C# method overriding requires exact parameter type matches, so this is enforced by the compiler.

Covariance of method return types in the subtype. If the base method returns Animal, the override may return Dog (a more specific type). C# supports covariant return types starting with C# 9 and .NET 5.

public class AnimalShelter
{
    public virtual Animal GetAnimal() => new Animal();
}

public class DogShelter : AnimalShelter
{
    // Covariant return type — valid in C# 9+
    public override Dog GetAnimal() => new Dog();
}

Part 4: The Classic Violations — And Why They Are Wrong

Every article about LSP mentions the rectangle-square problem. We will cover it here because it is genuinely instructive, but we will also go beyond it into violations you are more likely to encounter in production .NET code.

Violation 1: The Rectangle and the Square

This is the textbook example, and it illustrates the principle perfectly.

In geometry, a square is a rectangle. Every square has four right angles and four sides, and opposite sides are equal. So it seems natural to model this with inheritance:

public class Rectangle
{
    public virtual int Width { get; set; }
    public virtual int Height { get; set; }

    public int Area => Width * Height;
}

public class Square : Rectangle
{
    private int _side;

    public override int Width
    {
        get => _side;
        set
        {
            _side = value;
            // Must keep Width == Height for a square
        }
    }

    public override int Height
    {
        get => _side;
        set
        {
            _side = value;
        }
    }
}

Now consider this code, written against Rectangle:

public void ResizeAndCheck(Rectangle rect)
{
    rect.Width = 5;
    rect.Height = 10;

    // For a rectangle, Area should be 50
    Debug.Assert(rect.Area == 50);
}

Pass in a Rectangle — the assertion passes. Pass in a Square — the assertion fails, because setting Height = 10 also set Width = 10, so the area is 100.

The problem is not with geometry. The problem is that the Rectangle class has an implicit contract: setting Width does not change Height, and vice versa. The Square subclass violates this postcondition.

The fix: do not make Square inherit from Rectangle. Instead, model them as siblings under a common IShape interface:

public interface IShape
{
    int Area { get; }
}

public class Rectangle : IShape
{
    public int Width { get; set; }
    public int Height { get; set; }
    public int Area => Width * Height;
}

public class Square : IShape
{
    public int Side { get; set; }
    public int Area => Side * Side;
}

Or, if immutability is acceptable, use immutable value types where the issue disappears entirely:

public readonly record struct Rectangle(int Width, int Height)
{
    public int Area => Width * Height;
}

public readonly record struct Square(int Side)
{
    public int Area => Side * Side;
}

Violation 2: The Read-Only Collection That Is Not

This one shows up constantly in .NET code:

public class ReadOnlyRepository<T> : List<T>
{
    public ReadOnlyRepository(IEnumerable<T> items) : base(items) { }

    // "Disable" mutation by throwing
    public new void Add(T item) =>
        throw new NotSupportedException("Collection is read-only");

    public new void Remove(T item) =>
        throw new NotSupportedException("Collection is read-only");

    public new void Clear() =>
        throw new NotSupportedException("Collection is read-only");
}

This class inherits from List<T>, which has a contract that says "you can add, remove, and clear items." The new keyword hides the base methods but does not override them. If you cast to List<T> or IList<T>, the original Add, Remove, and Clear methods are still callable. Even if you used override (which you cannot, since List<T> methods are not virtual), throwing NotSupportedException weakens the postcondition — callers of List<T>.Add expect the item to be added, not an exception.

The fix: do not inherit from List<T>. Instead, expose IReadOnlyList<T> or IReadOnlyCollection<T>:

public class ReadOnlyRepository<T>
{
    private readonly List<T> _items;

    public ReadOnlyRepository(IEnumerable<T> items)
    {
        _items = new List<T>(items);
    }

    public IReadOnlyList<T> Items => _items.AsReadOnly();
}

Or simply use the built-in ReadOnlyCollection<T>, which wraps a list and throws NotSupportedException from its IList<T> implementation. Wait — does that violate LSP? Yes, technically it does. This is why IReadOnlyList<T> was introduced in .NET 4.5 — to provide a separate interface hierarchy that does not promise mutability. The lesson: prefer IReadOnlyList<T> over IList<T> when your type does not support mutation.

Violation 3: The NotImplementedException Anti-Pattern

This is perhaps the single most common LSP violation in real codebases:

public interface IPaymentGateway
{
    void Charge(decimal amount);
    void Refund(decimal amount);
    PaymentStatus CheckStatus(string transactionId);
}

public class BasicPaymentGateway : IPaymentGateway
{
    public void Charge(decimal amount)
    {
        // Implementation...
    }

    public void Refund(decimal amount)
    {
        // This gateway does not support refunds
        throw new NotImplementedException(
            "Refunds are not supported by this gateway");
    }

    public PaymentStatus CheckStatus(string transactionId)
    {
        // Implementation...
    }
}

Any code that processes refunds through IPaymentGateway will explode when it encounters BasicPaymentGateway. The interface says "I can refund." The implementation says "actually, I can't."

The fix is interface segregation (the "I" in SOLID works hand-in-hand with the "L"):

public interface IPaymentGateway
{
    void Charge(decimal amount);
    PaymentStatus CheckStatus(string transactionId);
}

public interface IRefundableGateway : IPaymentGateway
{
    void Refund(decimal amount);
}

public class BasicPaymentGateway : IPaymentGateway
{
    public void Charge(decimal amount) { /* ... */ }
    public PaymentStatus CheckStatus(string transactionId) { /* ... */ }
    // No Refund method — no lie
}

public class FullPaymentGateway : IRefundableGateway
{
    public void Charge(decimal amount) { /* ... */ }
    public void Refund(decimal amount) { /* ... */ }
    public PaymentStatus CheckStatus(string transactionId) { /* ... */ }
}

Now the type system tells the truth. If you need refund capability, accept IRefundableGateway. If you only need charging, accept IPaymentGateway. No runtime surprises.

Violation 4: The Derived Class That Ignores Parameters

public abstract class Logger
{
    public abstract void Log(string message, LogLevel level);
}

public class ConsoleLogger : Logger
{
    public override void Log(string message, LogLevel level)
    {
        // VIOLATION: Ignores log level entirely,
        // always writes to console
        Console.WriteLine(message);
    }
}

If the base class contract says "messages at LogLevel.None are suppressed," and ConsoleLogger writes everything regardless, it violates the postcondition. Callers who set LogLevel.None expecting silence will be surprised.

Violation 5: Temporal Coupling in Derived Classes

public abstract class DataPipeline
{
    public abstract void Configure(PipelineOptions options);
    public abstract void Execute();
}

public class BatchPipeline : DataPipeline
{
    private PipelineOptions? _options;

    public override void Configure(PipelineOptions options)
    {
        _options = options;
    }

    public override void Execute()
    {
        // VIOLATION: Throws if Configure was not called first,
        // introducing a precondition the base class didn't require
        if (_options is null)
            throw new InvalidOperationException(
                "Must call Configure before Execute");

        // Process...
    }
}

If the base class contract does not require calling Configure before Execute, then BatchPipeline has strengthened the precondition. The fix: either document the requirement on the base class (making it a universal precondition) or eliminate the temporal coupling by requiring configuration in the constructor.

Part 5: LSP in the .NET Framework and Runtime

The .NET ecosystem itself contains both good examples of LSP adherence and some well-known violations. Understanding where the framework gets it right — and where it does not — will sharpen your instincts.

Stream: A Mostly-Good Hierarchy

System.IO.Stream is one of the most widely used abstract classes in .NET. Its subclasses include FileStream, MemoryStream, NetworkStream, GZipStream, CryptoStream, SslStream, and many more. The design handles LSP through capability queries:

public abstract class Stream
{
    public abstract bool CanRead { get; }
    public abstract bool CanWrite { get; }
    public abstract bool CanSeek { get; }

    public abstract int Read(byte[] buffer, int offset, int count);
    public abstract void Write(byte[] buffer, int offset, int count);
    public abstract long Seek(long offset, SeekOrigin origin);
    // ...
}

A NetworkStream sets CanSeek to false and throws NotSupportedException from Seek. Is that an LSP violation? It depends on how you define the contract. If the contract of Stream.Seek is "seeks to a position in the stream," then yes, NetworkStream violates it. But the actual contract, as documented, is "seeks to a position in the stream if CanSeek is true; otherwise throws NotSupportedException." The capability flags are part of the contract.

This is a pragmatic compromise. Ideally, you would have separate IReadableStream, IWritableStream, and ISeekableStream interfaces (and indeed, newer designs sometimes take this approach). But Stream was designed in .NET 1.0 and must maintain backward compatibility. The capability-flag pattern is the next best thing.

ICollection and IReadOnlyCollection: A Course Correction

The original ICollection<T> interface (introduced in .NET 2.0) includes Add, Remove, and Clear methods. ReadOnlyCollection<T> implements ICollection<T> and throws NotSupportedException from the mutation methods. This is a well-known LSP weakness in the framework.

.NET 4.5 introduced IReadOnlyCollection<T> and IReadOnlyList<T> as separate interface hierarchies that do not promise mutation. This was an explicit recognition that the original design forced types into LSP violations. Today, the recommendation is:

• Accept IReadOnlyList<T> or IReadOnlyCollection<T> when you only need to read.
• Accept IList<T> or ICollection<T> when you need to mutate.
• Return IReadOnlyList<T> from methods that return collections you do not want callers to modify.

Array Covariance: A Famous Type Hole

C# arrays are covariant, which means you can assign a string[] to an object[] variable:

object[] objects = new string[3];
objects[0] = "hello";    // Fine
objects[1] = 42;         // Compiles! But throws ArrayTypeMismatchException at runtime

This is a genuine LSP violation baked into the language for backward compatibility (inherited from Java's design). An object[] promises "you can put any object in here." A string[] does not honor that promise. The type system says it is valid; the runtime says otherwise.

This is why generic collections (List<T>) are preferred over arrays for APIs. Generic variance in C# is safe: IEnumerable<out T> is covariant, IComparer<in T> is contravariant, and these are enforced at compile time.

Part 6: Design Patterns That Promote (and Violate) LSP

Patterns That Help

Strategy Pattern. The Strategy pattern is a natural fit for LSP. You define an interface, create multiple implementations, and swap them at runtime. As long as each implementation honors the interface contract, LSP is satisfied.

public interface ISortingStrategy<T>
{
    void Sort(List<T> items, IComparer<T> comparer);
}

public class QuickSortStrategy<T> : ISortingStrategy<T>
{
    public void Sort(List<T> items, IComparer<T> comparer)
    {
        // Quick sort implementation
        items.Sort(comparer); // Delegates to built-in
    }
}

public class BubbleSortStrategy<T> : ISortingStrategy<T>
{
    public void Sort(List<T> items, IComparer<T> comparer)
    {
        // Bubble sort implementation
        for (int i = 0; i < items.Count - 1; i++)
        {
            for (int j = 0; j < items.Count - 1 - i; j++)
            {
                if (comparer.Compare(items[j], items[j + 1]) > 0)
                {
                    (items[j], items[j + 1]) = (items[j + 1], items[j]);
                }
            }
        }
    }
}

Both strategies sort the list. The result is the same (a sorted list). The performance differs, but the postcondition is identical. LSP is preserved.

Template Method Pattern. When you define an algorithm's skeleton in a base class and let subclasses override specific steps, LSP is maintained as long as the overridden steps honor their contracts. The base class controls the overall flow; subclasses customize the details.

public abstract class ReportGenerator
{
    // Template method — not virtual
    public string Generate(ReportData data)
    {
        var header = BuildHeader(data);
        var body = BuildBody(data);
        var footer = BuildFooter(data);
        return $"{header}\n{body}\n{footer}";
    }

    protected abstract string BuildHeader(ReportData data);
    protected abstract string BuildBody(ReportData data);
    protected virtual string BuildFooter(ReportData data)
        => $"Generated at {DateTime.UtcNow:u}";
}

Decorator Pattern. Decorators wrap an existing object to add behavior. Because the decorator implements the same interface and delegates to the wrapped object, LSP is naturally preserved:

public interface IMessageSender
{
    Task SendAsync(string recipient, string body);
}

public class EmailSender : IMessageSender
{
    public async Task SendAsync(string recipient, string body)
    {
        // Send email...
        await Task.CompletedTask;
    }
}

public class LoggingMessageSender : IMessageSender
{
    private readonly IMessageSender _inner;
    private readonly ILogger _logger;

    public LoggingMessageSender(IMessageSender inner, ILogger logger)
    {
        _inner = inner;
        _logger = logger;
    }

    public async Task SendAsync(string recipient, string body)
    {
        _logger.LogInformation("Sending message to {Recipient}", recipient);
        await _inner.SendAsync(recipient, body);
        _logger.LogInformation("Message sent to {Recipient}", recipient);
    }
}

Patterns That Risk Violations

Adapter Pattern (when misused). Adapters translate one interface to another. If the adapted interface does not fully support the target interface's contract, the adapter will violate LSP. For example, adapting a key-value store (which supports only Get and Put) to a full IDatabase interface (which includes Transaction, Rollback, and Query) will likely produce NotImplementedException stubs.

Null Object Pattern (when lazy). The Null Object pattern provides a do-nothing implementation to avoid null checks. This is fine when the contract permits no-ops (e.g., a NullLogger that silently discards messages). It is an LSP violation when the contract requires meaningful action (e.g., a NullRepository that claims to save data but does not).

Part 7: LSP and Dependency Injection in ASP.NET Core

Dependency injection (DI) is the standard approach in modern ASP.NET Core applications, and LSP is the principle that makes DI work safely. When you register a service in the DI container:

builder.Services.AddScoped<IOrderService, OrderService>();

You are telling the framework: "Wherever someone asks for IOrderService, give them an OrderService." This is only safe if OrderService is a valid behavioral subtype of IOrderService — i.e., it honors every contract the interface promises.

A Real-World DI Scenario

Imagine a notification service with multiple implementations:

public interface INotificationService
{
    /// <summary>
    /// Sends a notification to the specified user.
    /// Returns true if the notification was delivered, false otherwise.
    /// Never throws on delivery failure — returns false instead.
    /// </summary>
    Task<bool> NotifyAsync(string userId, string message);
}

public class EmailNotificationService : INotificationService
{
    private readonly IEmailClient _emailClient;

    public EmailNotificationService(IEmailClient emailClient)
    {
        _emailClient = emailClient;
    }

    public async Task<bool> NotifyAsync(string userId, string message)
    {
        try
        {
            await _emailClient.SendAsync(userId, "Notification", message);
            return true;
        }
        catch (Exception)
        {
            return false; // Honors the "never throws" contract
        }
    }
}

public class SmsNotificationService : INotificationService
{
    private readonly ISmsGateway _gateway;

    public SmsNotificationService(ISmsGateway gateway)
    {
        _gateway = gateway;
    }

    public async Task<bool> NotifyAsync(string userId, string message)
    {
        try
        {
            var phone = await LookupPhoneNumber(userId);
            await _gateway.SendSmsAsync(phone, message);
            return true;
        }
        catch (Exception)
        {
            return false; // Honors the "never throws" contract
        }
    }

    private Task<string> LookupPhoneNumber(string userId)
    {
        // Lookup implementation...
        return Task.FromResult("+1234567890");
    }
}

Both implementations honor the contract: they return bool, they never throw on delivery failure. You can swap between them in Program.cs and the rest of the application works unchanged. That is LSP in action.

Now consider a broken implementation:

public class PushNotificationService : INotificationService
{
    public async Task<bool> NotifyAsync(string userId, string message)
    {
        // VIOLATION: Throws instead of returning false
        var token = await GetPushToken(userId)
            ?? throw new InvalidOperationException(
                $"No push token for user {userId}");

        await SendPush(token, message);
        return true;
    }

    // ...
}

This violates the "never throws on delivery failure" postcondition. Any calling code that does not expect an exception from NotifyAsync will fail. Register this in DI, and you have a production bug waiting to happen.

Testing for LSP in DI Scenarios

A useful testing pattern: write contract tests against the interface and run them for every registered implementation.

public abstract class NotificationServiceContractTests
{
    protected abstract INotificationService CreateService();

    [Fact]
    public async Task NotifyAsync_WithValidInput_ReturnsBoolean()
    {
        var service = CreateService();
        var result = await service.NotifyAsync("user-1", "Hello");
        Assert.IsType<bool>(result);
    }

    [Fact]
    public async Task NotifyAsync_NeverThrowsOnDeliveryFailure()
    {
        var service = CreateService();

        // This should not throw, even if delivery fails
        var exception = await Record.ExceptionAsync(
            () => service.NotifyAsync("nonexistent-user", "Hello"));

        Assert.Null(exception);
    }

    [Fact]
    public async Task NotifyAsync_WithNullUserId_ThrowsArgumentNullException()
    {
        var service = CreateService();

        await Assert.ThrowsAsync<ArgumentNullException>(
            () => service.NotifyAsync(null!, "Hello"));
    }
}

public class EmailNotificationServiceTests : NotificationServiceContractTests
{
    protected override INotificationService CreateService()
    {
        var mockClient = new MockEmailClient();
        return new EmailNotificationService(mockClient);
    }
}

public class SmsNotificationServiceTests : NotificationServiceContractTests
{
    protected override INotificationService CreateService()
    {
        var mockGateway = new MockSmsGateway();
        return new SmsNotificationService(mockGateway);
    }
}

If PushNotificationService fails NotifyAsync_NeverThrowsOnDeliveryFailure, you have caught the LSP violation before it reaches production.

Part 8: LSP and Generics in C#

C# generics interact with LSP in subtle ways, especially around variance.

Covariance (out)

IEnumerable<out T> is covariant. This means IEnumerable<Dog> is substitutable for IEnumerable<Animal> — which is safe because IEnumerable<T> only produces values of type T, it never consumes them. The consumer receives objects that are at least as specific as Animal, so all Animal operations work.

IEnumerable<Dog> dogs = new List<Dog> { new Dog("Rex"), new Dog("Buddy") };
IEnumerable<Animal> animals = dogs; // Safe — covariance

foreach (Animal animal in animals)
{
    Console.WriteLine(animal.Name); // Works — Dog IS-A Animal
}

Contravariance (in)

IComparer<in T> is contravariant. This means IComparer<Animal> is substitutable for IComparer<Dog> — which is safe because a comparer that can compare any two animals can certainly compare two dogs.

IComparer<Animal> animalComparer = new AnimalByNameComparer();
IComparer<Dog> dogComparer = animalComparer; // Safe — contravariance

var dogs = new List<Dog> { new Dog("Rex"), new Dog("Buddy") };
dogs.Sort(dogComparer); // Works — the comparer can handle Dogs

Invariance and the Trouble with Mutable Collections

IList<T> is invariant — IList<Dog> is not assignable to IList<Animal>. This is correct! If it were covariant:

// Hypothetical (does not compile, and for good reason):
IList<Animal> animals = new List<Dog>();
animals.Add(new Cat()); // A Cat in a List<Dog> — disaster!

Invariance protects LSP. The type system prevents you from creating a situation where a collection promises to accept any Animal but can actually only hold Dog instances.

Generic Constraints and LSP

When you write generic constraints, you are defining contracts:

public class Repository<T> where T : IEntity, new()
{
    public T Create()
    {
        var entity = new T();
        entity.Id = Guid.NewGuid();
        return entity;
    }
}

The constraint where T : IEntity, new() ensures that any type used with Repository<T> satisfies LSP relative to IEntity: it has an Id property and a parameterless constructor. The generic constraint is a compile-time LSP check.

Part 9: LSP Beyond Inheritance — Interfaces, Records, and Composition

A common misconception: LSP only applies to class inheritance. In fact, LSP applies to any subtyping relationship, including interface implementation, and even to any situation where one component can be substituted for another.

Interfaces and LSP

When a class implements an interface, it enters into an LSP contract. Every implementation of IDisposable.Dispose() must be safe to call multiple times (the documented contract). Every implementation of IEquatable<T>.Equals must be reflexive, symmetric, and transitive. These are behavioral contracts, and violating them is an LSP violation.

Records and LSP

C# records support inheritance:

public abstract record Shape(string Color);
public record Circle(string Color, double Radius) : Shape(Color);
public record Rectangle(string Color, double Width, double Height) : Shape(Color);

Records automatically generate Equals, GetHashCode, ToString, and copy constructors. The generated Equals considers all properties, including those introduced in derived records. This is generally LSP-safe because the generated behavior is consistent with the declared properties.

However, be careful with with expressions and polymorphism:

Shape shape = new Circle("Red", 5.0);
Shape modified = shape with { Color = "Blue" };
// modified is a Circle with Color="Blue" and Radius=5.0
// The runtime type is preserved — LSP is maintained

Composition Over Inheritance: The LSP Escape Hatch

When you find yourself struggling to make an inheritance hierarchy LSP-compliant, it is often a sign that inheritance is the wrong tool. Composition — building complex objects by combining simpler ones — sidesteps LSP issues entirely because there is no subtyping relationship to violate.

// Instead of:
public class LoggedRepository : Repository  // Fragile, LSP-risky
{
    // Override every method to add logging...
}

// Prefer:
public class LoggedRepository : IRepository  // No inheritance, no LSP risk
{
    private readonly IRepository _inner;
    private readonly ILogger _logger;

    public LoggedRepository(IRepository inner, ILogger logger)
    {
        _inner = inner;
        _logger = logger;
    }

    public async Task<Entity> GetByIdAsync(Guid id)
    {
        _logger.LogInformation("Fetching entity {Id}", id);
        return await _inner.GetByIdAsync(id);
    }

    // Delegate all methods to _inner, adding logging as needed
}

This is not an argument against inheritance — it is an argument for being deliberate about when to use it. Use inheritance when the "is-a" relationship is genuine and the base class contract is stable. Use composition when you want to add behavior without taking on the obligations of a subtyping contract.

Part 10: Detecting LSP Violations

How do you find LSP violations in an existing codebase? Here are concrete techniques.

Technique 1: Search for NotImplementedException and NotSupportedException

Run this in your project:

grep -rn "NotImplementedException\|NotSupportedException" --include="*.cs" .

Every hit is a potential LSP violation. Not every one will be — Stream subclasses that throw from Seek when CanSeek is false are contractually valid — but each one deserves scrutiny.

Technique 2: Search for Type Checks in Consumer Code

grep -rn "is \|as \|GetType()\|typeof(" --include="*.cs" .

Code that checks the runtime type of an object before deciding what to do is often working around an LSP violation:

// This is a code smell — the caller should not need to know the subtype
public decimal CalculateFee(IAccount account)
{
    if (account is PremiumAccount)
        return 0m;
    if (account is OverdraftAccount overdraft)
        return overdraft.OverdraftFee;
    return 5.00m;
}

The fix: push the fee calculation into the type hierarchy:

public interface IAccount
{
    decimal CalculateFee();
}

public class StandardAccount : IAccount
{
    public decimal CalculateFee() => 5.00m;
}

public class PremiumAccount : IAccount
{
    public decimal CalculateFee() => 0m;
}

public class OverdraftAccount : IAccount
{
    public decimal OverdraftFee { get; init; }
    public decimal CalculateFee() => OverdraftFee;
}

Technique 3: Contract Tests

As shown in Part 7, write abstract test classes that define the expected behavior of an interface, then inherit from them for each implementation. If a new implementation fails a contract test, you have found an LSP violation before it ships.

Technique 4: Code Analysis and Roslyn Analyzers

While there is no built-in Roslyn analyzer specifically for LSP, you can write custom analyzers that flag common patterns:

• Methods that throw NotImplementedException
• Override methods that throw exceptions the base class does not declare
• Override methods with if (someCondition) throw at the top (strengthened preconditions)
• Classes that implement an interface but new-hide methods instead of implementing them

Technique 5: Review Virtual Method Overrides

During code review, pay special attention to every override keyword. Ask:

1. Does this override accept all inputs the base method accepts?
2. Does this override produce all outputs the base method promises?
3. Does this override maintain all invariants the base class establishes?
4. Does this override throw only exceptions the base class allows?

If the answer to any question is "no," you have found a violation.

Part 11: LSP and the Other SOLID Principles

LSP does not exist in isolation. It interacts with every other SOLID principle.

Single Responsibility Principle (SRP) and LSP

A class with too many responsibilities is harder to subtype correctly, because the subclass must honor contracts across all those responsibilities. Keeping classes focused (SRP) makes LSP compliance easier.

Open/Closed Principle (OCP) and LSP

OCP says: "open for extension, closed for modification." LSP says: "extensions must honor the base contract." Together they mean: you can add new behavior through subtyping, but only if the new type is a valid substitute for the base type. OCP tells you to extend; LSP tells you how to extend safely.

Interface Segregation Principle (ISP) and LSP

ISP says: "don't force implementations to depend on methods they don't use." When interfaces are bloated, implementors are tempted to throw NotImplementedException from methods they cannot meaningfully implement — which violates LSP. Segregating interfaces into smaller, focused ones makes it possible for every implementor to honor the full contract.

As we saw with the payment gateway example: splitting IPaymentGateway into IPaymentGateway and IRefundableGateway simultaneously satisfies ISP and LSP.

Dependency Inversion Principle (DIP) and LSP

DIP says: "depend on abstractions, not concretions." LSP says: "those abstractions are only useful if all implementations honor their contracts." DIP without LSP is just indirection for indirection's sake — you depend on an interface, but the implementations behind it behave unpredictably. LSP makes DIP trustworthy.

Part 12: LSP in Functional and Hybrid Styles

Modern C# is increasingly functional, with pattern matching, records, expression-bodied members, and LINQ everywhere. Does LSP still matter when you are writing functional-style code?

Yes, but the vocabulary changes.

In functional programming, the equivalent of LSP is that functions with the same type signature should be interchangeable if they are used in the same context. A Func<int, int> that represents "double the input" and a Func<int, int> that represents "square the input" are both valid substitutions in any context that accepts Func<int, int> — as long as the calling code does not depend on specific behavior beyond "takes an int, returns an int."

Higher-order functions rely on LSP implicitly:

public IEnumerable<T> Filter<T>(
    IEnumerable<T> source,
    Func<T, bool> predicate)
{
    foreach (var item in source)
    {
        if (predicate(item))
            yield return item;
    }
}

This works with any predicate because the contract of Func<T, bool> is simply "takes a T, returns a bool." A predicate that throws half the time, or that has side effects like deleting files, technically satisfies the type signature but violates the implicit behavioral contract of "a pure test function."

Discriminated Unions and Exhaustive Matching

When you model variants with a closed hierarchy and pattern matching, LSP is satisfied by construction — every variant is known and every case is handled:

public abstract record PaymentResult;
public record PaymentSucceeded(string TransactionId) : PaymentResult;
public record PaymentFailed(string Reason) : PaymentResult;
public record PaymentPending(string CheckUrl) : PaymentResult;

public string Describe(PaymentResult result) => result switch
{
    PaymentSucceeded s => $"Paid! Transaction: {s.TransactionId}",
    PaymentFailed f => $"Failed: {f.Reason}",
    PaymentPending p => $"Pending. Check at: {p.CheckUrl}",
    _ => throw new UnreachableException()
};

Each variant is a valid substitution for PaymentResult. The exhaustive switch ensures every variant is handled. This is LSP-by-design.

Part 13: Common Pitfalls and How to Avoid Them

Pitfall 1: Confusing "Is-A" in the Real World with "Is-A" in Code

A square is a rectangle in geometry. An ostrich is a bird in biology. But that does not mean Square should inherit from Rectangle, or Ostrich should inherit from Bird if Bird has a Fly() method.

The "is-a" relationship in code means "can be substituted for." Ask the substitution question, not the taxonomy question: "Can I use a Square everywhere I use a Rectangle without changing behavior?" If the answer is no, do not use inheritance.

Pitfall 2: Inheriting for Code Reuse, Not Substitutability

Inheritance is often used as a code reuse mechanism: "I need these five methods from BaseService, so I will inherit from it." But inheritance creates a subtyping relationship, and now your class must honor the entire contract of BaseService. If you only want code reuse, use composition:

// Don't do this:
public class SpecialOrderService : OrderService { }

// Do this instead:
public class SpecialOrderService
{
    private readonly OrderService _orderService;

    public SpecialOrderService(OrderService orderService)
    {
        _orderService = orderService;
    }
}

Pitfall 3: Sealing Too Late

If a class is not designed for inheritance, seal it. C# classes are unsealed by default, which invites subtyping. If your class has implicit contracts that are not documented (like "setting Width does not change Height"), a subclass will eventually violate them.

public sealed class Configuration
{
    public string ConnectionString { get; init; } = "";
    public int MaxRetries { get; init; } = 3;
}

Starting with .NET 7, the runtime can optimize sealed classes more aggressively (devirtualization), so sealing is a performance win as well.

Pitfall 4: Not Documenting Contracts

LSP violations often stem from undocumented contracts. If the only way to know that Dispose() must be idempotent is to read the implementation, some future implementor will get it wrong.

Use XML documentation comments to document preconditions, postconditions, and invariants:

public interface ICache<TKey, TValue> where TKey : notnull
{
    /// <summary>
    /// Retrieves a value from the cache.
    /// </summary>
    /// <param name="key">The cache key. Must not be null.</param>
    /// <returns>
    /// The cached value, or default(TValue) if the key is not found.
    /// Never throws on a missing key.
    /// </returns>
    TValue? Get(TKey key);

    /// <summary>
    /// Adds or updates a value in the cache.
    /// </summary>
    /// <param name="key">The cache key. Must not be null.</param>
    /// <param name="value">The value to cache. May be null.</param>
    /// <remarks>
    /// Postcondition: After Set returns, Get(key) returns value
    /// (or an equivalent, if the cache performs serialization).
    /// </remarks>
    void Set(TKey key, TValue value);
}

Pitfall 5: Ignoring LSP in Test Doubles

Mocks and stubs are subtype implementations used in tests. If your mock violates the contract of the interface it implements, your tests may pass even when the production implementation has bugs — or your tests may fail for reasons unrelated to the code under test.

// BAD mock: violates the contract that Get never throws on missing key
public class BadMockCache : ICache<string, string>
{
    public string? Get(string key) =>
        throw new KeyNotFoundException(); // Contract says: return default, don't throw

    public void Set(string key, string value) { }
}

// GOOD mock: honors the contract
public class GoodMockCache : ICache<string, string>
{
    private readonly Dictionary<string, string> _store = new();

    public string? Get(string key) =>
        _store.TryGetValue(key, out var value) ? value : default;

    public void Set(string key, string value) =>
        _store[key] = value;
}

Part 14: A Practical Checklist

When designing a new class hierarchy or implementing an interface, run through this checklist:

Before writing the subtype:

1. Have I documented the preconditions, postconditions, and invariants of the base type or interface?
2. Is the "is-a" relationship genuine in the behavioral sense, not just the taxonomic sense?
3. Could I achieve my goal with composition instead of inheritance?
4. If I am inheriting from a concrete class, is it designed for inheritance (not sealed, virtual methods documented)?

While writing the subtype:

5. Do all overridden methods accept at least the same range of inputs as the base?
6. Do all overridden methods produce at least the same guarantees on output as the base?
7. Do I maintain all invariants from the base class?
8. Do I throw only exception types that the base class contract allows?
9. Am I introducing any new state that contradicts the base class's immutability or state-transition rules?

After writing the subtype:

10. Can I pass my subtype to every method that accepts the base type and have all existing tests pass?
11. Have I written contract tests that verify my implementation against the interface's behavioral contract?
12. Have I tested with null inputs, empty collections, boundary values, and failure scenarios?

Part 15: LSP in the Age of Source Generators, Interceptors, and AI

Modern .NET development is evolving rapidly. Source generators can create implementations of interfaces at compile time. Interceptors can replace method implementations transparently. AI coding assistants generate implementations from interface definitions. In each case, LSP remains the quality gate.

A source-generated implementation of IRepository<T> must honor the same contracts as a hand-written one. An interceptor that replaces a caching layer must maintain the same preconditions and postconditions. An AI-generated implementation of INotificationService must satisfy the same contract tests.

The tooling changes. The principle does not.

If anything, LSP becomes more important as code generation increases. When humans write every line, they bring context and judgment. When code is generated — whether by a T4 template, a Roslyn source generator, or an LLM — the behavioral contract is the only thing ensuring correctness. Write clear contracts. Write contract tests. Let the principle do its work.

Part 16: Resources and Further Reading

Here are authoritative references for deeper study:

• Barbara Liskov and Jeannette Wing, "A Behavioral Notion of Subtyping" (1994) — The foundational paper. Published in ACM Transactions on Programming Languages and Systems, Vol. 16, No. 6.
• Robert C. Martin, "Design Principles and Design Patterns" (2000) — The paper that collected the five principles that became SOLID.
• Robert C. Martin, Agile Software Development: Principles, Patterns, and Practices (2002) — Chapter 10 covers LSP with detailed C++ and Java examples.
• Barbara Liskov, "Data Abstraction and Hierarchy" (1987) — The original OOPSLA keynote, published in SIGPLAN Notices.
• Bertrand Meyer, Object-Oriented Software Construction (1988, 2nd ed. 1997) — Introduces Design by Contract, which provides the vocabulary (preconditions, postconditions, invariants) used to formalize LSP.
• Microsoft C# Documentation — Covariance and Contravariance in Generics: https://learn.microsoft.com/en-us/dotnet/standard/generics/covariance-and-contravariance
• Microsoft .NET Design Guidelines — Choosing Between Class and Struct: https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/
• Barbara Liskov — ACM Turing Award Laureate Profile: https://amturing.acm.org/award_winners/liskov_1108679.cfm
• SOLID Principles — Wikipedia: https://en.wikipedia.org/wiki/SOLID

Conclusion

The Liskov Substitution Principle is not about rectangles and squares. It is not an academic curiosity. It is the invisible contract that makes polymorphism — the most powerful feature of object-oriented programming — actually work.

Every time you write ILogger logger in a method signature, you are trusting that whatever implementation arrives at runtime will behave like a logger. Every time you register a service in the DI container, you are trusting that the concrete type honors the interface's contract. Every time you swap an adapter, a strategy, or a decorator, you are trusting that the new component is a valid substitute for the old one.

When that trust is justified — when every subtype honors every contract — your system is modular, testable, and resilient to change. When it is not — when subtypes throw unexpected exceptions, ignore parameters, break invariants, or strengthen preconditions — you get the kind of bugs that are hardest to diagnose: the ones that only appear when a specific subtype is used in a specific context that nobody anticipated.

Barbara Liskov's insight, first articulated at a conference in 1987, formalized in 1994, and adopted as a pillar of software design by 2000, remains as relevant today as it was then. The languages have changed. The frameworks have changed. The deployment targets have changed. But the need for behavioral substitutability — for types that keep their promises — has not changed, and never will.

Write clear contracts. Honor them in every implementation. Test them with contract tests. Seal what is not designed for extension. Prefer composition when inheritance does not fit. And the next time you see a NotImplementedException, treat it as a design smell, not a TODO — because somewhere downstream, someone is trusting your type to do what it says.

That trust is the Liskov Substitution Principle. Do not break it.

Then your product owner walks over and says, "We're adding DHL. And Amazon Logistics. And a regional carrier called OnTrac. Oh, and we need to support freight shipping for palletized orders. Can you have that done by next sprint?"

You open ShippingCalculator.cs. It is 400 lines long. The switch has grown tentacles. Every carrier's logic references shared local variables. The unit tests are brittle — each one constructs a fake order and asserts against a hardcoded dollar amount that was correct in 2024. You add the DHL case. A FedEx test breaks. You fix the FedEx test. The USPS case now returns the wrong surcharge. You spend the rest of the afternoon playing whack-a-mole with regressions.

This is the problem that the Open/Closed Principle exists to prevent.

Part 1: What Is the Open/Closed Principle?

The Open/Closed Principle (OCP) is one of the five SOLID principles of object-oriented design. Its canonical formulation is deceptively simple:

Software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification.

That single sentence has generated more conference talks, blog posts, and heated Slack arguments than perhaps any other principle in software engineering. Let us break it down.

Open for extension means you can add new behavior to the entity. You can teach it new tricks. You can make it handle cases it did not handle before.

Closed for modification means you should not have to crack open the existing source code and change it to add that new behavior. The existing code — the code that is tested, deployed, and working in production — stays untouched.

The word "should" is doing heavy lifting here. The OCP is a principle, not a law. It describes an ideal to design toward, not an absolute rule that can never be broken. But when you manage to achieve it, the results are remarkable: new features arrive by writing new code, not by rewriting old code. Regressions drop. Deployments get smaller. Code reviews get easier. Your Thursday afternoons get less stressful.

The "O" in SOLID

The SOLID acronym represents five principles that Robert C. Martin (widely known as Uncle Bob) consolidated in his 2000 paper Design Principles and Design Patterns. The acronym itself was coined around 2004 by Michael Feathers, who rearranged the initials into a memorable word:

• S — Single Responsibility Principle (SRP)
• O — Open/Closed Principle (OCP)
• L — Liskov Substitution Principle (LSP)
• I — Interface Segregation Principle (ISP)
• D — Dependency Inversion Principle (DIP)

The five principles are deeply interrelated. The OCP tells you what your goal is: build software that can be extended without modification. The Dependency Inversion Principle tells you how to get there: depend on abstractions, not concretions. The Liskov Substitution Principle tells you the rules your abstractions must follow. The Interface Segregation Principle tells you how to keep those abstractions lean. And the Single Responsibility Principle tells you how to scope each module so that extension points align with likely axes of change.

Think of SOLID as a constellation, not a checklist. The principles reinforce each other, and understanding the OCP in isolation is like understanding one star without seeing the pattern it belongs to.

Part 2: A Brief History — From Meyer to Martin

Bertrand Meyer and the Original Formulation (1988)

The Open/Closed Principle was first articulated by Bertrand Meyer in his 1988 book Object-Oriented Software Construction. Meyer was writing at a time when the software industry was grappling with a fundamental problem: libraries were hard to evolve. If you shipped a compiled library and a client depended on it, adding a field to a data structure or a method to a class could break every program that used that library. Recompilation cascades were real and expensive.

Meyer proposed a solution rooted in inheritance. His formulation went something like this: a class is closed because it can be compiled, stored in a library, baselined, and used by other classes without fear of change. But it is also open because any new class can inherit from it and add new fields, new methods, and new behavior — without modifying the original class or disturbing its existing clients.

In Meyer's world, the mechanism for achieving OCP was implementation inheritance. You extend behavior by subclassing. The parent class stays frozen. The child class adds what is new.

This was a reasonable idea in 1988. The dominant paradigm was procedural programming. Object-oriented languages like Eiffel (which Meyer himself created) and early C++ were still proving their worth. Inheritance was the exciting new tool, and Meyer wielded it well.

Robert C. Martin and the Polymorphic Reformulation (1996)

By the mid-1990s, the software industry had learned some hard lessons about implementation inheritance. Deep inheritance hierarchies created tight coupling. The "fragile base class problem" — where changes to a parent class broke child classes in unexpected ways — became a recognized anti-pattern. Developers began to favor composition over inheritance, and interfaces over concrete base classes.

In 1996, Robert C. Martin published an article titled "The Open-Closed Principle" that reframed Meyer's idea for this new reality. Martin kept the core insight — software should be extensible without modification — but changed the mechanism. Instead of relying on implementation inheritance, Martin advocated for abstracted interfaces. You define a contract (an interface or an abstract base class), and then you create multiple implementations that can be polymorphically substituted for each other. The interface is closed to modification. New implementations are open for extension.

This is the version of the OCP that most developers know today. When someone says "follow the Open/Closed Principle," they almost always mean Martin's polymorphic formulation, not Meyer's inheritance-based one.

Why the Distinction Matters

The difference between Meyer's OCP and Martin's OCP is not merely academic. It changes how you write code.

Meyer's approach says: "Here is a concrete class. Subclass it to add behavior." This leads to class hierarchies. It works well when the base class is genuinely designed for inheritance (think Stream in .NET, or HttpMessageHandler), but it falls apart when developers start subclassing everything in sight and end up with six levels of inheritance just to add a logging statement.

Martin's approach says: "Here is an interface. Implement it to add behavior." This leads to flat, composable architectures. It works well with dependency injection containers, plugin systems, and microservice boundaries. It is the approach that modern C# and ASP.NET Core are designed around.

Both formulations are valid. Both have their place. But for the rest of this article, when we say "OCP," we mean Martin's polymorphic formulation unless otherwise noted — because that is what you will use every day as a .NET developer.

Part 3: The Problem — Code That Violates the OCP

Before we talk about how to follow the OCP, let us spend some time understanding what happens when you do not. Violations of the OCP are everywhere, and they tend to follow a few recognizable patterns.

Pattern 1: The Giant Switch Statement

This is the most common violation. You have a method that does different things based on a type discriminator, and every time a new type appears, you add another case.

public class InvoicePrinter
{
    public string Print(Invoice invoice)
    {
        switch (invoice.Type)
        {
            case InvoiceType.Standard:
                return FormatStandardInvoice(invoice);
            case InvoiceType.Recurring:
                return FormatRecurringInvoice(invoice);
            case InvoiceType.ProForma:
                return FormatProFormaInvoice(invoice);
            // When the business adds "Credit Note" next quarter,
            // you will be right back in this file adding another case.
            default:
                throw new ArgumentOutOfRangeException(
                    nameof(invoice.Type),
                    $"Unknown invoice type: {invoice.Type}");
        }
    }

    private string FormatStandardInvoice(Invoice invoice) { /* ... */ }
    private string FormatRecurringInvoice(Invoice invoice) { /* ... */ }
    private string FormatProFormaInvoice(Invoice invoice) { /* ... */ }
}

Every time a new invoice type is introduced, this class must be modified. That means recompiling, retesting, and redeploying the module that contains it — even though the existing invoice types have not changed at all.

Pattern 2: The If-Else Chain

A close cousin of the switch statement. Instead of switching on an enum, you check conditions or types directly.

public decimal CalculateDiscount(Customer customer, decimal orderTotal)
{
    if (customer.Tier == "Gold")
    {
        return orderTotal * 0.15m;
    }
    else if (customer.Tier == "Silver")
    {
        return orderTotal * 0.10m;
    }
    else if (customer.Tier == "Bronze")
    {
        return orderTotal * 0.05m;
    }
    else if (customer.Tier == "Employee")
    {
        return orderTotal * 0.25m;
    }
    else
    {
        return 0m;
    }
}

This code works perfectly — until the business invents a "Platinum" tier, or a "Loyalty Program" tier, or a "Black Friday Override" tier. Each addition requires modifying this method.

Pattern 3: The Type-Checking Method

This one is especially insidious because it often hides behind the is keyword in C#.

public void ProcessPayment(IPayment payment)
{
    if (payment is CreditCardPayment cc)
    {
        ChargeCreditCard(cc.CardNumber, cc.Amount);
    }
    else if (payment is BankTransferPayment bt)
    {
        InitiateBankTransfer(bt.Iban, bt.Amount);
    }
    else if (payment is CryptoPayment crypto)
    {
        SendCrypto(crypto.WalletAddress, crypto.Amount);
    }
    else
    {
        throw new NotSupportedException(
            $"Payment type {payment.GetType().Name} is not supported.");
    }
}

You have an interface (IPayment), which looks like you are following the OCP. But then you immediately undermine it by checking the concrete type and branching. The interface is just window dressing. This method still needs to be modified every time a new payment type is added.

Why Do These Violations Happen?

They happen because they are the easiest thing to write in the moment. When you have one or two cases, a switch or if-else is perfectly readable. It is only when the third, fourth, and tenth cases arrive that the pain becomes acute. The OCP is fundamentally about anticipating change — not in a crystal-ball way, but in a "what kind of change is likely in this domain?" way.

The shipping calculator will probably need new carriers. The invoice printer will probably need new invoice types. The payment processor will probably need new payment methods. If you can see the axis of change, you can design for it.

Part 4: Applying the OCP in C# — The Basics

Let us fix the violations from Part 3. The core technique is always the same: extract the varying behavior behind an abstraction, and let new behavior arrive as new implementations of that abstraction.

Step 1: Define an Abstraction

Start by identifying the behavior that changes. In the invoice printer example, the thing that changes is how each invoice type is formatted. So we define an interface for that behavior:

public interface IInvoiceFormatter
{
    InvoiceType SupportedType { get; }
    string Format(Invoice invoice);
}

Step 2: Implement the Abstraction for Each Case

Each existing case in the switch statement becomes its own class:

public class StandardInvoiceFormatter : IInvoiceFormatter
{
    public InvoiceType SupportedType => InvoiceType.Standard;

    public string Format(Invoice invoice)
    {
        // All the logic that was in FormatStandardInvoice()
        var sb = new StringBuilder();
        sb.AppendLine($"INVOICE #{invoice.Number}");
        sb.AppendLine($"Date: {invoice.Date:yyyy-MM-dd}");
        sb.AppendLine($"Customer: {invoice.CustomerName}");
        sb.AppendLine();
        foreach (var line in invoice.Lines)
        {
            sb.AppendLine($"  {line.Description,-40} {line.Amount,12:C}");
        }
        sb.AppendLine(new string('-', 54));
        sb.AppendLine($"  {"Total",-40} {invoice.Total,12:C}");
        return sb.ToString();
    }
}

public class RecurringInvoiceFormatter : IInvoiceFormatter
{
    public InvoiceType SupportedType => InvoiceType.Recurring;

    public string Format(Invoice invoice)
    {
        var sb = new StringBuilder();
        sb.AppendLine($"RECURRING INVOICE #{invoice.Number}");
        sb.AppendLine($"Billing Period: {invoice.PeriodStart:MMM yyyy} - {invoice.PeriodEnd:MMM yyyy}");
        sb.AppendLine($"Next Charge: {invoice.NextChargeDate:yyyy-MM-dd}");
        sb.AppendLine($"Customer: {invoice.CustomerName}");
        sb.AppendLine();
        foreach (var line in invoice.Lines)
        {
            sb.AppendLine($"  {line.Description,-40} {line.Amount,12:C}");
        }
        sb.AppendLine(new string('-', 54));
        sb.AppendLine($"  {"Monthly Total",-40} {invoice.Total,12:C}");
        return sb.ToString();
    }
}

public class ProFormaInvoiceFormatter : IInvoiceFormatter
{
    public InvoiceType SupportedType => InvoiceType.ProForma;

    public string Format(Invoice invoice)
    {
        var sb = new StringBuilder();
        sb.AppendLine("*** PRO FORMA — NOT A TAX INVOICE ***");
        sb.AppendLine($"Estimate #{invoice.Number}");
        sb.AppendLine($"Valid Until: {invoice.ExpiryDate:yyyy-MM-dd}");
        sb.AppendLine($"Prepared For: {invoice.CustomerName}");
        sb.AppendLine();
        foreach (var line in invoice.Lines)
        {
            sb.AppendLine($"  {line.Description,-40} {line.Amount,12:C}");
        }
        sb.AppendLine(new string('-', 54));
        sb.AppendLine($"  {"Estimated Total",-40} {invoice.Total,12:C}");
        return sb.ToString();
    }
}

Step 3: Compose via the Abstraction

Now the InvoicePrinter depends only on the interface, not on any specific formatter:

public class InvoicePrinter
{
    private readonly IReadOnlyDictionary<InvoiceType, IInvoiceFormatter> _formatters;

    public InvoicePrinter(IEnumerable<IInvoiceFormatter> formatters)
    {
        _formatters = formatters.ToDictionary(f => f.SupportedType);
    }

    public string Print(Invoice invoice)
    {
        if (!_formatters.TryGetValue(invoice.Type, out var formatter))
        {
            throw new NotSupportedException(
                $"No formatter registered for invoice type '{invoice.Type}'.");
        }

        return formatter.Format(invoice);
    }
}

This class is now closed for modification. You will never need to change it again (unless the fundamental concept of "invoice printing" itself changes, which is a different kind of change — more on that later). And it is open for extension: when the business adds "Credit Note" as a new invoice type, you write a single new class:

public class CreditNoteFormatter : IInvoiceFormatter
{
    public InvoiceType SupportedType => InvoiceType.CreditNote;

    public string Format(Invoice invoice)
    {
        var sb = new StringBuilder();
        sb.AppendLine("*** CREDIT NOTE ***");
        sb.AppendLine($"Credit Note #{invoice.Number}");
        sb.AppendLine($"Original Invoice: #{invoice.OriginalInvoiceNumber}");
        sb.AppendLine($"Customer: {invoice.CustomerName}");
        sb.AppendLine();
        foreach (var line in invoice.Lines)
        {
            sb.AppendLine($"  {line.Description,-40} {line.Amount,12:C}");
        }
        sb.AppendLine(new string('-', 54));
        sb.AppendLine($"  {"Credit Total",-40} {invoice.Total,12:C}");
        return sb.ToString();
    }
}

Register it in your dependency injection container, and you are done. The InvoicePrinter never knew it existed, never needed to be recompiled, and never needed to be retested. The only new code is the CreditNoteFormatter itself and its own unit tests.

Step 4: Wire It Up in DI

In ASP.NET Core (or any application using Microsoft.Extensions.DependencyInjection), registration looks like this:

builder.Services.AddSingleton<IInvoiceFormatter, StandardInvoiceFormatter>();
builder.Services.AddSingleton<IInvoiceFormatter, RecurringInvoiceFormatter>();
builder.Services.AddSingleton<IInvoiceFormatter, ProFormaInvoiceFormatter>();
builder.Services.AddSingleton<IInvoiceFormatter, CreditNoteFormatter>();

builder.Services.AddSingleton<InvoicePrinter>();

When the DI container resolves InvoicePrinter, it will inject an IEnumerable<IInvoiceFormatter> containing all registered formatters. The printer builds its dictionary and is ready to go.

This is the textbook OCP refactoring. It works for the discount calculator (extract an IDiscountStrategy interface), for the payment processor (let each IPayment implementation carry its own Process() method), and for the shipping calculator that started this article (extract an IShippingRateProvider interface with one implementation per carrier).

Part 5: Design Patterns That Embody the OCP

The OCP is not just a principle — it is the conceptual foundation beneath many of the classic design patterns from the Gang of Four book and beyond. If you have ever used one of these patterns, you were following the OCP, even if you did not call it by name.

Strategy Pattern

The Strategy pattern is the most direct expression of the OCP. You define a family of algorithms (strategies), encapsulate each one behind a common interface, and make them interchangeable. The context class (the one that uses the strategy) never changes when a new strategy is added.

We already saw this with the invoice formatter example. Here is another example — a file compression service:

public interface ICompressionStrategy
{
    string FileExtension { get; }
    byte[] Compress(byte[] data);
    byte[] Decompress(byte[] data);
}

public class GzipCompression : ICompressionStrategy
{
    public string FileExtension => ".gz";

    public byte[] Compress(byte[] data)
    {
        using var output = new MemoryStream();
        using (var gzip = new GZipStream(output, CompressionLevel.Optimal))
        {
            gzip.Write(data, 0, data.Length);
        }
        return output.ToArray();
    }

    public byte[] Decompress(byte[] data)
    {
        using var input = new MemoryStream(data);
        using var gzip = new GZipStream(input, CompressionMode.Decompress);
        using var output = new MemoryStream();
        gzip.CopyTo(output);
        return output.ToArray();
    }
}

public class BrotliCompression : ICompressionStrategy
{
    public string FileExtension => ".br";

    public byte[] Compress(byte[] data)
    {
        using var output = new MemoryStream();
        using (var brotli = new BrotliStream(output, CompressionLevel.Optimal))
        {
            brotli.Write(data, 0, data.Length);
        }
        return output.ToArray();
    }

    public byte[] Decompress(byte[] data)
    {
        using var input = new MemoryStream(data);
        using var brotli = new BrotliStream(input, CompressionMode.Decompress);
        using var output = new MemoryStream();
        brotli.CopyTo(output);
        return output.ToArray();
    }
}

Adding Zstandard compression next year? Write a ZstdCompression class. Nothing else changes.

Decorator Pattern

The Decorator pattern lets you wrap an existing object with additional behavior, without modifying the original. Each decorator implements the same interface as the object it wraps, so decorators are invisible to the consumer.

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(int id);
    Task SaveAsync(Order order);
}

// The base implementation — talks to the database
public class SqlOrderRepository : IOrderRepository
{
    private readonly DbContext _db;

    public SqlOrderRepository(DbContext db) => _db = db;

    public async Task<Order?> GetByIdAsync(int id)
        => await _db.Set<Order>().FindAsync(id);

    public async Task SaveAsync(Order order)
    {
        _db.Set<Order>().Update(order);
        await _db.SaveChangesAsync();
    }
}

// A decorator that adds caching — does not modify SqlOrderRepository
public class CachedOrderRepository : IOrderRepository
{
    private readonly IOrderRepository _inner;
    private readonly IMemoryCache _cache;
    private readonly ILogger<CachedOrderRepository> _logger;

    public CachedOrderRepository(
        IOrderRepository inner,
        IMemoryCache cache,
        ILogger<CachedOrderRepository> logger)
    {
        _inner = inner;
        _cache = cache;
        _logger = logger;
    }

    public async Task<Order?> GetByIdAsync(int id)
    {
        var cacheKey = $"order:{id}";
        if (_cache.TryGetValue(cacheKey, out Order? cached))
        {
            _logger.LogDebug("Cache hit for order {OrderId}", id);
            return cached;
        }

        var order = await _inner.GetByIdAsync(id);
        if (order is not null)
        {
            _cache.Set(cacheKey, order, TimeSpan.FromMinutes(5));
        }

        return order;
    }

    public async Task SaveAsync(Order order)
    {
        await _inner.SaveAsync(order);
        _cache.Remove($"order:{order.Id}");
    }
}

// A decorator that adds audit logging — does not modify either of the above
public class AuditedOrderRepository : IOrderRepository
{
    private readonly IOrderRepository _inner;
    private readonly IAuditLog _auditLog;

    public AuditedOrderRepository(IOrderRepository inner, IAuditLog auditLog)
    {
        _inner = inner;
        _auditLog = auditLog;
    }

    public Task<Order?> GetByIdAsync(int id) => _inner.GetByIdAsync(id);

    public async Task SaveAsync(Order order)
    {
        await _inner.SaveAsync(order);
        await _auditLog.RecordAsync("Order", order.Id, "Saved");
    }
}

You can stack decorators: AuditedOrderRepository wrapping CachedOrderRepository wrapping SqlOrderRepository. Each layer adds behavior without modifying the layers beneath it. The SqlOrderRepository class does not know it is being cached or audited.

In ASP.NET Core DI, you can wire this up using the Scrutor library or manually:

builder.Services.AddScoped<SqlOrderRepository>();
builder.Services.AddScoped<IOrderRepository>(sp =>
{
    var sql = sp.GetRequiredService<SqlOrderRepository>();
    var cache = sp.GetRequiredService<IMemoryCache>();
    var cacheLogger = sp.GetRequiredService<ILogger<CachedOrderRepository>>();
    var cached = new CachedOrderRepository(sql, cache, cacheLogger);
    var auditLog = sp.GetRequiredService<IAuditLog>();
    return new AuditedOrderRepository(cached, auditLog);
});

Template Method Pattern

The Template Method pattern defines the skeleton of an algorithm in a base class and lets subclasses override specific steps. This is one of the few places where Meyer's original inheritance-based OCP still shines.

public abstract class ReportGenerator
{
    // The template method — defines the algorithm's structure
    public string Generate(ReportData data)
    {
        var sb = new StringBuilder();
        sb.AppendLine(CreateHeader(data));
        sb.AppendLine(CreateBody(data));
        sb.AppendLine(CreateFooter(data));
        return sb.ToString();
    }

    protected abstract string CreateHeader(ReportData data);
    protected abstract string CreateBody(ReportData data);

    // A default implementation that subclasses can override if needed
    protected virtual string CreateFooter(ReportData data)
        => $"Generated on {DateTime.UtcNow:yyyy-MM-dd HH:mm} UTC";
}

public class HtmlReportGenerator : ReportGenerator
{
    protected override string CreateHeader(ReportData data)
        => $"<html><head><title>{data.Title}</title></head><body><h1>{data.Title}</h1>";

    protected override string CreateBody(ReportData data)
    {
        var sb = new StringBuilder("<table>");
        foreach (var row in data.Rows)
        {
            sb.Append("<tr>");
            foreach (var cell in row)
            {
                sb.Append($"<td>{cell}</td>");
            }
            sb.Append("</tr>");
        }
        sb.Append("</table>");
        return sb.ToString();
    }

    protected override string CreateFooter(ReportData data)
        => $"<footer>Generated on {DateTime.UtcNow:yyyy-MM-dd HH:mm} UTC</footer></body></html>";
}

public class CsvReportGenerator : ReportGenerator
{
    protected override string CreateHeader(ReportData data)
        => string.Join(",", data.ColumnNames);

    protected override string CreateBody(ReportData data)
    {
        var sb = new StringBuilder();
        foreach (var row in data.Rows)
        {
            sb.AppendLine(string.Join(",", row.Select(EscapeCsv)));
        }
        return sb.ToString();
    }

    private static string EscapeCsv(string value)
        => value.Contains(',') || value.Contains('"')
            ? $"\"{value.Replace("\"", "\"\"")}\""
            : value;
}

The Generate() method in ReportGenerator is closed for modification. The individual steps (CreateHeader, CreateBody, CreateFooter) are open for extension via subclassing.

Factory Method Pattern

The Factory Method pattern delegates object creation to subclasses or to factory methods, so you can introduce new product types without modifying the code that consumes them.

public interface INotification
{
    Task SendAsync(string recipient, string message);
}

public class EmailNotification : INotification
{
    private readonly IEmailClient _emailClient;

    public EmailNotification(IEmailClient emailClient) => _emailClient = emailClient;

    public async Task SendAsync(string recipient, string message)
        => await _emailClient.SendAsync(recipient, "Notification", message);
}

public class SmsNotification : INotification
{
    private readonly ISmsGateway _gateway;

    public SmsNotification(ISmsGateway gateway) => _gateway = gateway;

    public async Task SendAsync(string recipient, string message)
        => await _gateway.SendTextAsync(recipient, message);
}

public class PushNotification : INotification
{
    private readonly IPushService _pushService;

    public PushNotification(IPushService pushService) => _pushService = pushService;

    public async Task SendAsync(string recipient, string message)
        => await _pushService.PushAsync(recipient, message);
}

When the business says "we need Slack notifications too," you write a SlackNotification class, register it, and nothing else needs to change.

Observer Pattern (Events and Delegates)

C# has first-class support for the Observer pattern through events and delegates. This is OCP in action: the publisher defines an event, and any number of subscribers can attach to it without the publisher knowing or caring.

public class OrderService
{
    // The event — an extension point
    public event Func<Order, Task>? OrderPlaced;

    public async Task PlaceOrderAsync(Order order)
    {
        // Core business logic
        order.Status = OrderStatus.Placed;
        order.PlacedAt = DateTime.UtcNow;
        await _repository.SaveAsync(order);

        // Notify all subscribers — OrderService does not know who they are
        if (OrderPlaced is not null)
        {
            foreach (var handler in OrderPlaced.GetInvocationList().Cast<Func<Order, Task>>())
            {
                await handler(order);
            }
        }
    }
}

Subscribers attach from outside:

orderService.OrderPlaced += async order =>
    await emailService.SendOrderConfirmationAsync(order);

orderService.OrderPlaced += async order =>
    await inventoryService.ReserveStockAsync(order);

orderService.OrderPlaced += async order =>
    await analyticsService.TrackOrderAsync(order);

Adding a new side effect to order placement does not require modifying OrderService. That is the OCP.

Part 6: The OCP in ASP.NET Core

ASP.NET Core is one of the best examples of OCP-friendly architecture in the .NET ecosystem. Several of its core abstractions are explicitly designed so you can extend behavior without modifying framework code.

The Middleware Pipeline

The ASP.NET Core request pipeline is a chain of middleware components. Each middleware processes the request, optionally calls the next middleware in the chain, and then processes the response on the way back out. The pipeline itself is closed for modification — the WebApplication class does not need to change when you add a new middleware. But it is open for extension — you can insert new middleware at any point in the chain.

var app = builder.Build();

// Each of these extends the pipeline without modifying any existing middleware
app.UseExceptionHandler("/Error");
app.UseHsts();
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

// Your custom middleware — open for extension
app.UseMiddleware<RequestTimingMiddleware>();
app.UseMiddleware<TenantResolutionMiddleware>();

app.MapControllers();
app.Run();

Writing a custom middleware is adding new behavior without modifying any existing code:

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

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

    public async Task InvokeAsync(HttpContext context)
    {
        var stopwatch = Stopwatch.StartNew();

        await _next(context);

        stopwatch.Stop();
        _logger.LogInformation(
            "Request {Method} {Path} completed in {ElapsedMs}ms with status {StatusCode}",
            context.Request.Method,
            context.Request.Path,
            stopwatch.ElapsedMilliseconds,
            context.Response.StatusCode);
    }
}

Dependency Injection and Service Registration

The DI container in ASP.NET Core is itself an OCP-friendly system. You register services against interfaces, and consumers depend on those interfaces. When you need to swap an implementation — say, replacing an in-memory cache with Redis — you change the registration, not the consumer.

// Development: use in-memory
if (builder.Environment.IsDevelopment())
{
    builder.Services.AddSingleton<ICacheService, InMemoryCacheService>();
}
else
{
    // Production: use Redis — no consumer code changes
    builder.Services.AddSingleton<ICacheService, RedisCacheService>();
}

Configuration and Options Pattern

The Options pattern (IOptions<T>, IOptionsSnapshot<T>, IOptionsMonitor<T>) lets you extend application behavior through configuration without modifying code. Feature flags are a natural expression of the OCP:

public class FeatureFlags
{
    public bool EnableNewCheckoutFlow { get; set; }
    public bool EnableRecommendationEngine { get; set; }
    public bool EnableBetaDashboard { get; set; }
}

// In Program.cs
builder.Services.Configure<FeatureFlags>(
    builder.Configuration.GetSection("Features"));

// In a controller or service
public class CheckoutController : ControllerBase
{
    private readonly IOptionsSnapshot<FeatureFlags> _features;

    public CheckoutController(IOptionsSnapshot<FeatureFlags> features)
        => _features = features;

    [HttpPost]
    public async Task<IActionResult> Checkout(CheckoutRequest request)
    {
        if (_features.Value.EnableNewCheckoutFlow)
        {
            return await NewCheckoutFlowAsync(request);
        }

        return await LegacyCheckoutFlowAsync(request);
    }
}

The if statement here might look like an OCP violation, but it is not — this is feature toggling, a controlled, temporary branching mechanism. The key distinction is that the toggle will be removed once the new flow is validated and the old flow is deleted. It is not a permanent, ever-growing branching mechanism like the switch statement in Part 3.

Minimal APIs and Endpoint Filters

Minimal APIs in ASP.NET Core support endpoint filters, which are another expression of the OCP. You can attach cross-cutting behavior to endpoints without modifying the endpoint handler itself:

app.MapPost("/api/orders", async (CreateOrderRequest request, IOrderService service) =>
{
    var order = await service.CreateAsync(request);
    return Results.Created($"/api/orders/{order.Id}", order);
})
.AddEndpointFilter<ValidationFilter<CreateOrderRequest>>()
.AddEndpointFilter<AuditLogFilter>()
.RequireAuthorization("OrderCreator");

Each filter extends the endpoint's behavior. The handler itself does not know about validation, audit logging, or authorization. Those concerns are composed from outside.

Part 7: The OCP with Modern C# Features

C# has evolved significantly since the OCP was first formulated. Several modern language features make it easier to follow the principle — and a few can tempt you into violating it.

Generics

Generics are a powerful tool for building OCP-compliant abstractions. A generic interface or class can work with types that do not exist yet when the generic is written.

public interface IRepository<T> where T : class, IEntity
{
    Task<T?> GetByIdAsync(int id);
    Task<IReadOnlyList<T>> GetAllAsync();
    Task AddAsync(T entity);
    Task UpdateAsync(T entity);
    Task DeleteAsync(int id);
}

public class EfRepository<T> : IRepository<T> where T : class, IEntity
{
    private readonly AppDbContext _context;

    public EfRepository(AppDbContext context) => _context = context;

    public async Task<T?> GetByIdAsync(int id)
        => await _context.Set<T>().FindAsync(id);

    public async Task<IReadOnlyList<T>> GetAllAsync()
        => await _context.Set<T>().ToListAsync();

    public async Task AddAsync(T entity)
    {
        await _context.Set<T>().AddAsync(entity);
        await _context.SaveChangesAsync();
    }

    public async Task UpdateAsync(T entity)
    {
        _context.Set<T>().Update(entity);
        await _context.SaveChangesAsync();
    }

    public async Task DeleteAsync(int id)
    {
        var entity = await GetByIdAsync(id);
        if (entity is not null)
        {
            _context.Set<T>().Remove(entity);
            await _context.SaveChangesAsync();
        }
    }
}

When you add a new entity type (Invoice, Customer, Product), you do not modify EfRepository<T>. You just use it with the new type. That is OCP through generics.

Delegates and Func/Action

You do not always need a full interface to achieve OCP. Sometimes a delegate is enough. Delegates are the smallest possible abstraction — a single method signature.

public class RetryHandler
{
    public async Task<T> ExecuteWithRetryAsync<T>(
        Func<Task<T>> operation,
        int maxRetries = 3,
        TimeSpan? delay = null)
    {
        var retryDelay = delay ?? TimeSpan.FromSeconds(1);

        for (int attempt = 1; attempt <= maxRetries; attempt++)
        {
            try
            {
                return await operation();
            }
            catch (Exception ex) when (attempt < maxRetries)
            {
                await Task.Delay(retryDelay * attempt);
            }
        }

        return await operation(); // Final attempt — let it throw
    }
}

This class can retry any async operation without knowing what that operation does. It is closed for modification. You extend it by passing in different Func<Task<T>> delegates — which is open for extension.

Extension Methods

Extension methods let you add behavior to existing types without modifying them. This is literally the OCP at the language level.

public static class StringExtensions
{
    public static string Truncate(this string value, int maxLength)
    {
        if (string.IsNullOrEmpty(value)) return value;
        return value.Length <= maxLength
            ? value
            : value[..maxLength] + "…";
    }

    public static string ToSlug(this string value)
    {
        var slug = value.ToLowerInvariant();
        slug = Regex.Replace(slug, @"[^a-z0-9\s-]", "");
        slug = Regex.Replace(slug, @"\s+", "-");
        slug = Regex.Replace(slug, @"-+", "-");
        return slug.Trim('-');
    }
}

The string class is closed for modification (you cannot change it — it is in the BCL). But it is open for extension via extension methods.

A Word of Caution: Pattern Matching and Switch Expressions

C# has made pattern matching and switch expressions beautifully concise. This can actually make OCP violations more attractive, because they look so clean:

public decimal CalculateTax(Address address) => address.State switch
{
    "CA" => address.SubTotal * 0.0725m,
    "TX" => address.SubTotal * 0.0625m,
    "NY" => address.SubTotal * 0.08m,
    "OR" => 0m, // No sales tax
    _ => address.SubTotal * 0.05m
};

This is elegant, readable, and a clear OCP violation. Every time a state's tax rate changes or a new state is added, you modify this method. Whether that matters depends on context. If tax rates change frequently and the calculation is complex (considering county taxes, exemptions, thresholds), you should extract a strategy. If the rates are stable and the calculation is trivial, the switch expression might be perfectly fine. The OCP is a guide, not a religion.

Part 8: The OCP and Testability

One of the most practical benefits of following the OCP is that it makes your code dramatically easier to test. When behavior is hidden behind abstractions, you can substitute test doubles (mocks, stubs, fakes) without any ceremony.

Testing OCP-Compliant Code

Consider the InvoicePrinter from Part 4. Testing it is trivial because it depends on IInvoiceFormatter, not on concrete implementations:

public class InvoicePrinterTests
{
    [Fact]
    public void Print_UsesCorrectFormatterForInvoiceType()
    {
        // Arrange
        var invoice = new Invoice
        {
            Type = InvoiceType.Standard,
            Number = "INV-001",
            CustomerName = "Acme Corp",
            Lines = [new InvoiceLine("Widget", 99.99m)],
            Total = 99.99m
        };

        var mockFormatter = new TestInvoiceFormatter(
            InvoiceType.Standard,
            "FORMATTED OUTPUT");

        var printer = new InvoicePrinter([mockFormatter]);

        // Act
        var result = printer.Print(invoice);

        // Assert
        Assert.Equal("FORMATTED OUTPUT", result);
    }

    [Fact]
    public void Print_ThrowsForUnregisteredInvoiceType()
    {
        // Arrange
        var invoice = new Invoice { Type = InvoiceType.CreditNote };
        var printer = new InvoicePrinter([]); // No formatters registered

        // Act & Assert
        Assert.Throws<NotSupportedException>(() => printer.Print(invoice));
    }

    private class TestInvoiceFormatter : IInvoiceFormatter
    {
        private readonly string _output;
        public InvoiceType SupportedType { get; }

        public TestInvoiceFormatter(InvoiceType type, string output)
        {
            SupportedType = type;
            _output = output;
        }

        public string Format(Invoice invoice) => _output;
    }
}

Notice how the test does not need to know anything about how standard invoices are actually formatted. It tests the printer's behavior (routing to the correct formatter) in isolation. The formatter's behavior is tested separately, in StandardInvoiceFormatterTests.

Testing Without OCP

Compare this to testing the original switch-based InvoicePrinter. You would need to construct a real invoice, call Print(), and assert against the actual formatted output. If the formatting logic changes, the test breaks. If you want to test the routing logic separately from the formatting logic, you cannot — they are entangled in the same method.

The OCP Makes Mocking Unnecessary (Sometimes)

When your abstractions are simple enough, you do not even need a mocking framework. The TestInvoiceFormatter above is a hand-written fake — it took four lines of code. This is often clearer than using Moq or NSubstitute, because the fake's behavior is explicit and visible in the test.

For more complex interactions, mocking frameworks still have their place. But the OCP ensures that the seams where you inject mocks are well-defined and stable.

Part 9: When NOT to Follow the OCP

The OCP is a tool, not a commandment. There are legitimate situations where following it would make your code worse, not better.

When the Axis of Change Is Unknown

The OCP requires you to predict where change will happen so you can place an abstraction there. If you guess wrong, you end up with an abstraction that no one ever extends, and a codebase full of interfaces with exactly one implementation. This is sometimes called "speculative generality" — one of Martin Fowler's code smells.

Do not pre-abstract everything on the off chance it might change someday. Instead, follow the "Rule of Three": the first time you encounter a new variation, handle it inline. The second time, note the pattern. The third time, refactor to an abstraction. By the third occurrence, you have enough data to know what the actual axis of change is.

When the Cost of Abstraction Exceeds the Cost of Modification

Every abstraction has a cost. It adds a file, an interface, a registration, and a level of indirection that the next developer must understand. If your switch statement has three cases and has not changed in two years, the OCP refactoring is not "better" — it is just more code.

Ask yourself: "What is the cost of modifying this code when the next case arrives?" If the answer is "five minutes and a recompile," the switch statement is fine. If the answer is "two hours of careful surgery in a 400-line method with 15 tests to update," it is time to refactor.

When You Are Doing a Planned Refactoring

Following the OCP slavishly can prevent healthy refactoring. If you discover that your abstraction was wrong — that the interface is too broad, or the responsibilities are divided along the wrong axis — you need to modify the existing code. That is not a violation of the OCP. That is software development.

The OCP guides the steady-state evolution of a system: how you add new features to a stable codebase. It does not mean "never change existing code ever again." Refactoring, fixing bugs, updating dependencies, and redesigning modules are all legitimate reasons to modify existing code.

When Performance Matters

Virtual dispatch (calling a method through an interface) has a small cost compared to a direct call. In most applications, this cost is negligible. But in hot paths — tight loops processing millions of items, real-time game physics, high-frequency trading — the overhead of abstraction can matter. In these cases, a well-optimized switch statement or even a lookup table might be the right choice.

Modern .NET has narrowed this gap considerably. The JIT compiler can devirtualize calls in many cases, and the performance difference between a virtual call and a direct call is often just a few nanoseconds. But if you are in a domain where nanoseconds matter, measure before abstracting.

The Pragmatic Middle Ground

The best developers do not follow the OCP blindly, and they do not ignore it either. They develop an intuition for when an abstraction will pay for itself and when it will not. That intuition comes from experience — from seeing which switch statements grew out of control and which ones stayed stable for years.

A useful mental model: think of the OCP as insurance. You pay a small upfront cost (the abstraction) to protect against a future cost (modifying existing code). Like real insurance, it is not worth paying for unlikely risks. But for likely risks — a payment processor that will definitely need new payment methods, a notification system that will definitely need new channels — the premium is well worth it.

Part 10: Common Criticisms and Misconceptions

The OCP has its share of critics, and some of their points are valid. Let us address the most common ones.

"You Cannot Predict the Future"

This is the strongest criticism. The OCP asks you to design extension points, but you can only place them where you think change will happen. If you are wrong, the extension points are useless, and the change you did not anticipate requires modifying the code anyway.

The counterargument is that you do not need to predict the future perfectly. You just need to observe the past. If your payment processor has had three new payment methods added in the last year, it is a safe bet that a fourth is coming. If your report generator has had exactly one format for five years, it probably does not need an abstraction.

"It Leads to Too Many Classes"

A strict application of the OCP can produce a proliferation of small classes: one interface, one implementation per case, one factory, one registration. For a system with twenty payment methods, that is at least twenty-two classes (the interface, the twenty implementations, and the service that uses them) instead of one class with a twenty-case switch.

This is a real trade-off. More classes means more files to navigate, more registrations to maintain, and more cognitive load for developers new to the codebase. The mitigation is to use consistent naming conventions (so the classes are predictable) and to keep each class small and focused (so they are easy to understand in isolation).

"Interfaces With One Implementation Are a Waste"

If you have IShippingCalculator and ShippingCalculator, and no other implementations exist or are planned, the interface is just ceremony. Some developers (and some style guides) argue that you should not introduce an interface until you need a second implementation.

This is a reasonable position. The counterarguments are: (1) the interface makes the class testable via mocking, even if there is only one production implementation, and (2) the interface documents the contract, making it explicit what the class promises to do. Whether those benefits justify the extra file is a judgment call.

"Martin's OCP Is Not Meyer's OCP"

This is historically accurate. Robert C. Martin's reformulation of the OCP using interfaces and polymorphism is substantially different from Bertrand Meyer's original formulation using implementation inheritance. Some purists argue that Martin co-opted the term and changed its meaning.

This is an interesting debate for historians of software engineering, but it is not very useful for working developers. Both formulations share the same core insight: systems are more maintainable when new behavior can be added without modifying existing code. The mechanism differs, but the goal is identical.

Part 11: Real-World OCP — A Complete Example

Let us build a complete, realistic example that ties together everything we have discussed. Imagine you are building a document export service for a SaaS application. Users can export their data in various formats, and you expect the list of formats to grow over time.

The Domain

public record ExportRequest(
    string UserId,
    string DocumentId,
    string Format,
    ExportOptions Options);

public record ExportOptions(
    bool IncludeMetadata = true,
    bool IncludeComments = false,
    string? WatermarkText = null);

public record ExportResult(
    string FileName,
    string ContentType,
    byte[] Content);

The Abstraction

public interface IDocumentExporter
{
    /// <summary>
    /// The format identifier this exporter handles (e.g., "pdf", "docx", "csv").
    /// </summary>
    string Format { get; }

    /// <summary>
    /// Exports a document in this exporter's format.
    /// </summary>
    Task<ExportResult> ExportAsync(Document document, ExportOptions options);
}

The Implementations

public class PdfExporter : IDocumentExporter
{
    private readonly ILogger<PdfExporter> _logger;

    public PdfExporter(ILogger<PdfExporter> logger) => _logger = logger;

    public string Format => "pdf";

    public async Task<ExportResult> ExportAsync(Document document, ExportOptions options)
    {
        _logger.LogInformation("Exporting document {DocumentId} as PDF", document.Id);

        // In a real app, you would use a library like QuestPDF or iText
        var pdfBytes = await GeneratePdfAsync(document, options);

        return new ExportResult(
            FileName: $"{document.Title.ToSlug()}.pdf",
            ContentType: "application/pdf",
            Content: pdfBytes);
    }

    private Task<byte[]> GeneratePdfAsync(Document document, ExportOptions options)
    {
        // PDF generation logic here
        // This is where QuestPDF, iText, or similar would be used
        throw new NotImplementedException("PDF generation not shown for brevity");
    }
}

public class CsvExporter : IDocumentExporter
{
    public string Format => "csv";

    public Task<ExportResult> ExportAsync(Document document, ExportOptions options)
    {
        var sb = new StringBuilder();

        if (options.IncludeMetadata)
        {
            sb.AppendLine($"# Title: {document.Title}");
            sb.AppendLine($"# Author: {document.Author}");
            sb.AppendLine($"# Created: {document.CreatedAt:O}");
            sb.AppendLine();
        }

        sb.AppendLine("Section,Content");
        foreach (var section in document.Sections)
        {
            var escapedContent = section.Content.Replace("\"", "\"\"");
            sb.AppendLine($"\"{section.Title}\",\"{escapedContent}\"");
        }

        var bytes = Encoding.UTF8.GetBytes(sb.ToString());

        return Task.FromResult(new ExportResult(
            FileName: $"{document.Title.ToSlug()}.csv",
            ContentType: "text/csv",
            Content: bytes));
    }
}

public class MarkdownExporter : IDocumentExporter
{
    public string Format => "md";

    public Task<ExportResult> ExportAsync(Document document, ExportOptions options)
    {
        var sb = new StringBuilder();

        sb.AppendLine($"# {document.Title}");
        sb.AppendLine();

        if (options.IncludeMetadata)
        {
            sb.AppendLine($"*Author: {document.Author}*");
            sb.AppendLine($"*Created: {document.CreatedAt:yyyy-MM-dd}*");
            sb.AppendLine();
        }

        foreach (var section in document.Sections)
        {
            sb.AppendLine($"## {section.Title}");
            sb.AppendLine();
            sb.AppendLine(section.Content);
            sb.AppendLine();

            if (options.IncludeComments && section.Comments.Count > 0)
            {
                sb.AppendLine("### Comments");
                sb.AppendLine();
                foreach (var comment in section.Comments)
                {
                    sb.AppendLine($"> **{comment.Author}** ({comment.Date:yyyy-MM-dd}): {comment.Text}");
                    sb.AppendLine();
                }
            }
        }

        if (options.WatermarkText is not null)
        {
            sb.AppendLine("---");
            sb.AppendLine($"*{options.WatermarkText}*");
        }

        var bytes = Encoding.UTF8.GetBytes(sb.ToString());

        return Task.FromResult(new ExportResult(
            FileName: $"{document.Title.ToSlug()}.md",
            ContentType: "text/markdown",
            Content: bytes));
    }
}

The Service

public class DocumentExportService
{
    private readonly IReadOnlyDictionary<string, IDocumentExporter> _exporters;
    private readonly IDocumentRepository _documents;
    private readonly ILogger<DocumentExportService> _logger;

    public DocumentExportService(
        IEnumerable<IDocumentExporter> exporters,
        IDocumentRepository documents,
        ILogger<DocumentExportService> logger)
    {
        _exporters = exporters.ToDictionary(
            e => e.Format,
            StringComparer.OrdinalIgnoreCase);
        _documents = documents;
        _logger = logger;
    }

    public IReadOnlyCollection<string> SupportedFormats => _exporters.Keys.ToList();

    public async Task<ExportResult> ExportAsync(ExportRequest request)
    {
        if (!_exporters.TryGetValue(request.Format, out var exporter))
        {
            throw new NotSupportedException(
                $"Export format '{request.Format}' is not supported. " +
                $"Supported formats: {string.Join(", ", SupportedFormats)}");
        }

        var document = await _documents.GetByIdAsync(request.DocumentId)
            ?? throw new InvalidOperationException(
                $"Document '{request.DocumentId}' not found.");

        _logger.LogInformation(
            "User {UserId} exporting document {DocumentId} as {Format}",
            request.UserId,
            request.DocumentId,
            request.Format);

        return await exporter.ExportAsync(document, request.Options);
    }
}

The API Endpoint

app.MapGet("/api/export/formats", (DocumentExportService service) =>
    Results.Ok(service.SupportedFormats));

app.MapPost("/api/export", async (ExportRequest request, DocumentExportService service) =>
{
    var result = await service.ExportAsync(request);
    return Results.File(result.Content, result.ContentType, result.FileName);
})
.RequireAuthorization();

The DI Registration

builder.Services.AddSingleton<IDocumentExporter, PdfExporter>();
builder.Services.AddSingleton<IDocumentExporter, CsvExporter>();
builder.Services.AddSingleton<IDocumentExporter, MarkdownExporter>();
builder.Services.AddScoped<DocumentExportService>();

Adding a New Format

Six months from now, a customer asks for JSON export. Here is the entire change:

public class JsonExporter : IDocumentExporter
{
    public string Format => "json";

    public Task<ExportResult> ExportAsync(Document document, ExportOptions options)
    {
        var exportData = new
        {
            document.Title,
            document.Author,
            CreatedAt = document.CreatedAt.ToString("O"),
            Sections = document.Sections.Select(s => new
            {
                s.Title,
                s.Content,
                Comments = options.IncludeComments
                    ? s.Comments.Select(c => new { c.Author, c.Date, c.Text })
                    : null
            }),
            Watermark = options.WatermarkText
        };

        var json = JsonSerializer.Serialize(exportData, new JsonSerializerOptions
        {
            WriteIndented = true,
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
        });

        var bytes = Encoding.UTF8.GetBytes(json);

        return Task.FromResult(new ExportResult(
            FileName: $"{document.Title.ToSlug()}.json",
            ContentType: "application/json",
            Content: bytes));
    }
}

And one line in DI registration:

builder.Services.AddSingleton<IDocumentExporter, JsonExporter>();

That is it. The DocumentExportService was not modified. The API endpoints were not modified. The existing exporters were not modified. No existing tests were broken. The only new code is the JsonExporter class, its unit tests, and one line of registration.

This is the Open/Closed Principle at work.

Part 12: OCP Beyond Object-Oriented Programming

The OCP is usually discussed in the context of OOP, but the underlying idea — new behavior via new code, not by modifying old code — applies to other paradigms as well.

Functional Approaches

In functional programming, the OCP manifests through higher-order functions, pattern matching on discriminated unions, and composition.

// A pipeline of transformations — each function extends behavior
// without modifying the others
public static class TextPipeline
{
    public static string Process(
        string input,
        params Func<string, string>[] transforms)
    {
        return transforms.Aggregate(input, (current, transform) => transform(current));
    }
}

// Usage — adding a new transform is just passing another function
var result = TextPipeline.Process(
    rawText,
    text => text.Trim(),
    text => text.ToLowerInvariant(),
    text => Regex.Replace(text, @"\s+", " "),
    text => text.Replace("colour", "color") // New transformation — nothing modified
);

The Process method is closed for modification. You extend it by passing in additional functions.

Event-Driven and Message-Based Systems

In event-driven architectures, the OCP appears naturally. A message broker (like RabbitMQ, Azure Service Bus, or even an in-process MediatR pipeline) routes messages to handlers. Adding a new handler for an existing message type, or adding a handler for a new message type, does not require modifying any existing handler or the broker itself.

// MediatR example — each handler is independent
public record OrderPlacedEvent(int OrderId, string CustomerId, decimal Total)
    : INotification;

// Handler 1 — sends confirmation email
public class SendOrderConfirmationHandler
    : INotificationHandler<OrderPlacedEvent>
{
    public async Task Handle(
        OrderPlacedEvent notification,
        CancellationToken cancellationToken)
    {
        // Send email
    }
}

// Handler 2 — reserves inventory
public class ReserveInventoryHandler
    : INotificationHandler<OrderPlacedEvent>
{
    public async Task Handle(
        OrderPlacedEvent notification,
        CancellationToken cancellationToken)
    {
        // Reserve stock
    }
}

// Handler 3 — added six months later, no existing code modified
public class UpdateAnalyticsDashboardHandler
    : INotificationHandler<OrderPlacedEvent>
{
    public async Task Handle(
        OrderPlacedEvent notification,
        CancellationToken cancellationToken)
    {
        // Push to analytics
    }
}

Plugin Architectures

Plugin systems are, as Robert C. Martin himself wrote, the ultimate expression of the OCP. The host application defines extension points (interfaces, events, hooks), and plugins implement them. The host is closed for modification. Plugins provide extension.

Think of Visual Studio extensions, browser extensions, WordPress plugins, or even NuGet packages. When you install a NuGet package that adds a new middleware to your ASP.NET Core pipeline, you are experiencing the OCP. The ASP.NET Core framework did not need to be modified to support that middleware.

Part 13: A Checklist for Applying the OCP

When you are designing a new feature or refactoring existing code, run through this checklist:

1. Identify the axis of change. What is likely to change in this part of the system? New payment methods? New report formats? New validation rules? New notification channels? The answer tells you where to place your abstraction.

2. Define the abstraction. Create an interface (or abstract class, or delegate) that captures the varying behavior. Keep it as small as possible — the Interface Segregation Principle is your friend here.

3. Implement the abstraction for existing cases. Extract each case from the switch/if-else chain into its own class that implements the interface.

4. Compose via the abstraction. The consuming class should depend only on the interface, receive implementations via dependency injection, and dispatch to the correct one.

5. Register in DI. Wire up the implementations in your composition root (Program.cs in ASP.NET Core).

6. Write tests. Test each implementation in isolation. Test the consuming class with fake implementations. Verify that adding a new implementation does not break existing tests.

7. Resist premature abstraction. If you only have one or two cases and no clear evidence of more coming, consider waiting. The Rule of Three is your friend.

8. Delete dead abstractions. If an interface has had one implementation for three years and there is no realistic prospect of a second, consider inlining it. Abstractions that do not earn their keep are clutter.

Part 14: Resources and Further Reading

Here are authoritative resources for deepening your understanding of the Open/Closed Principle and SOLID design:

• Robert C. Martin, "The Open-Closed Principle" (1996) — The seminal article that reformulated the OCP for the age of interfaces and polymorphism. Available in Martin's book Agile Software Development, Principles, Patterns, and Practices (Prentice Hall, 2003).

• Robert C. Martin, Clean Architecture: A Craftsman's Guide to Software Structure and Design (2017) — Chapter 8 covers the OCP in the context of software architecture, including the concept of protecting higher-level policies from changes in lower-level details.

• Bertrand Meyer, Object-Oriented Software Construction, 2nd Edition (1997) — The original source of the OCP. The second edition (1997) is more accessible than the first (1988), though both are dense. Available from Prentice Hall.

• Robert C. Martin's Clean Coder Blog — Martin's post "The Open-Closed Principle" (May 2014) discusses plugin architectures as the "apotheosis" of the OCP: blog.cleancoder.com/uncle-bob/2014/05/12/TheOpenClosedPrinciple.html

• Martin Fowler, Refactoring: Improving the Design of Existing Code, 2nd Edition (2018) — Covers "Replace Conditional with Polymorphism" and other refactorings that move code toward OCP compliance.

• The SOLID Wikipedia article — A concise overview of all five principles with references: en.wikipedia.org/wiki/SOLID

• Microsoft's ASP.NET Core documentation on Middleware — A real-world example of OCP-compliant architecture: learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware

• Microsoft's ASP.NET Core documentation on Dependency Injection — The DI container is the mechanism that makes OCP practical in .NET: learn.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection

• Design Patterns: Elements of Reusable Object-Oriented Software (1994) — The Gang of Four book. Strategy, Decorator, Template Method, Observer, and Factory Method patterns are all expressions of the OCP.

Conclusion

The Open/Closed Principle is not about never modifying code. It is about designing your code so that the most common kind of change — adding a new variation of something that already exists — can be accomplished by writing new code rather than modifying old code.

The principle was born in 1988 when Bertrand Meyer observed that libraries were hard to evolve without breaking their clients. It was refined in 1996 when Robert C. Martin replaced inheritance with interfaces as the primary mechanism. And it is alive today in every ASP.NET Core middleware you write, every IRepository<T> you inject, and every strategy pattern you implement.

The key insight is not the technique. The technique — interfaces, dependency injection, polymorphism — is just mechanics. The key insight is the question: "If I add a new case to this system, how much existing code do I have to change?" If the answer is "none," you have followed the OCP. If the answer is "one file that I own and understand," you are probably fine. If the answer is "twelve files across three projects," you have a design problem.

Build your systems like camera bodies and lenses. The body defines the mount — the interface, the extension point. Lenses (implementations) can be swapped without rewiring the body. Some photographers never buy more than two lenses, and that is fine. But when the day comes that they need a telephoto, they do not need to buy a new camera.

Write code that does not need to be rewritten when the next requirement arrives. That is the Open/Closed Principle. And on your next Thursday afternoon, when the product owner walks over with a new carrier, a new format, or a new payment method, you will be ready.

This article traces SRP from its intellectual roots in the 1970s through its final formulation in 2017. Along the way, we will look at dozens of C# code examples — from obvious violations to subtle ones — and build practical intuition for applying SRP in everyday .NET development. We will also examine the tension between SRP and pragmatism, because blindly splitting every class into the smallest possible pieces creates its own problems.

Part 1: Where the Single Responsibility Principle Came From

Cohesion: The Idea Before the Name

Long before Robert C. Martin coined the term "Single Responsibility Principle," software engineers were grappling with the same underlying concept under a different name: cohesion.

In 1978, Tom DeMarco published Structured Analysis and System Specification, a book about decomposing systems into modules using data flow diagrams. DeMarco argued that a well-designed module should have a clear, focused purpose. When a module's internal elements were all related to the same concern, DeMarco called it "cohesive." When a module mixed unrelated concerns, it was said to have low cohesion — and low cohesion led to fragile, hard-to-change systems.

Around the same time, Meilir Page-Jones wrote The Practical Guide to Structured Systems Design (1980), which formalized a spectrum of cohesion types ranging from "coincidental cohesion" (the worst — elements thrown together for no reason) through "functional cohesion" (the best — every element contributes to a single, well-defined task).

Larry Constantine and Edward Yourdon had introduced these ideas even earlier in Structured Design (1975), identifying seven levels of cohesion. The insight was always the same: modules that group related things together are easier to understand, easier to test, and easier to change.

Robert C. Martin and the Birth of SRP

Robert C. Martin — widely known as "Uncle Bob" — synthesized these ideas into a single, memorable principle in the late 1990s. He introduced the term "Single Responsibility Principle" in his article The Principles of OOD and later included it as the first of the five SOLID principles in his 2003 book Agile Software Development, Principles, Patterns, and Practices.

Martin's original formulation was:

A class should have only one reason to change.

This was elegant and quotable, but it turned out to be ambiguous. What counts as a "reason to change"? Is a bug fix a reason to change? Is a refactoring a reason to change? Is a new business requirement a reason to change? Developers argued endlessly about where to draw the line.

The 2014 Clarification

In May 2014, Martin published a blog post titled "The Single Responsibility Principle" on his Clean Coder blog. In it, he acknowledged the confusion around "reason to change" and tried to clarify. The key insight was that "reasons to change" map to people — specifically, to the different stakeholders or user groups whose needs drive changes to the software.

Martin used the example of an Employee class with three methods: calculatePay(), reportHours(), and save(). Each method serves a different stakeholder: the CFO's organization cares about pay calculation, the COO's organization cares about hour reporting, and the CTO's organization cares about database persistence. Three stakeholders, three reasons to change — and therefore three responsibilities that should live in separate classes or modules.

He also offered an alternative phrasing: "Gather together the things that change for the same reasons. Separate those things that change for different reasons." This is really just another way of describing cohesion and coupling — maximize cohesion within a module, minimize coupling between modules.

The Final Definition in Clean Architecture

In his 2017 book Clean Architecture: A Craftsman's Guide to Software Structure and Design, Martin gave what he considers the definitive formulation of SRP:

A module should be responsible to one, and only one, actor.

Here, "module" means a source file (or, in object-oriented languages, a class). And "actor" means a group of stakeholders or users who want the system to change in the same way. This is the most precise version of the principle because it eliminates the ambiguity of "reason to change" — it is not about the number of methods, or the number of lines of code, or even the number of conceptual "things" a class does. It is about the number of different groups of people who might ask you to change that class.

This matters because when two different actors drive changes to the same module, those changes can collide. A change requested by the accounting department might accidentally break something the operations department depends on. SRP exists to prevent that collision.

Part 2: What SRP Is Not

Before we go further, let us clear up the most common misconceptions. These misunderstandings cause real harm — they lead developers to either ignore the principle entirely or apply it so aggressively that their codebase becomes an unnavigable sea of tiny classes.

Misconception 1: "A Class Should Do Only One Thing"

This is the most widespread misunderstanding. It reduces SRP to a vague platitude: what counts as "one thing"? A UserService that creates users, validates them, and sends welcome emails — is that one thing ("user management") or three things? A StringBuilder that appends characters, inserts strings, and converts to output — is that one thing or many?

The "do one thing" interpretation leads to two failure modes. Developers who interpret "one thing" broadly end up with God classes that do everything related to a concept. Developers who interpret "one thing" narrowly end up with anemic classes that each contain a single method and accomplish nothing on their own.

SRP is not about the number of things a class does. It is about the number of actors it serves. A StringBuilder does many things, but they all serve the same actor — the developer who needs to build strings. There is no scenario where the accounting department wants StringBuilder.Append() to work differently than the operations department does. One actor, one responsibility, no violation.

Misconception 2: "A Class Should Have Only One Method"

This is the extreme version of misconception one. Some developers, upon learning SRP, immediately start breaking every class into single-method classes. This is not what the principle asks for. A class can have dozens of methods and still follow SRP, as long as all those methods serve the same actor's needs.

Consider the .NET List<T> class. It has methods for adding, removing, sorting, searching, enumerating, copying, reversing, and converting. That is a lot of methods. But they all serve the same purpose — managing an in-memory collection — and they all change for the same reasons. Nobody from the sales department is going to ask you to change how List<T>.Sort() works while someone from the warehouse team asks you to change how List<T>.Add() works. One actor, one responsibility.

Misconception 3: "SRP Means Small Classes"

Class size is a consequence of good design, not a goal in itself. Sometimes following SRP produces small classes. Sometimes it produces large ones. A well-designed repository class might have twenty methods — one for each query the application needs — and still follow SRP if all those queries serve the same actor.

The danger of fetishizing small classes is that it leads to class explosion — a codebase with hundreds of tiny classes, each containing a single method, connected by a web of interfaces and dependency injection registrations. This kind of codebase is hard to navigate, hard to understand, and hard to change — the exact problems SRP was supposed to solve.

Misconception 4: "SRP Only Applies to Classes"

Martin's final formulation uses the word "module," which he clarifies to mean a source file. But the principle applies at every level of abstraction: methods, classes, namespaces, assemblies, services, and even entire systems. A microservice that handles both user authentication and order processing is violating SRP at the service level, just as surely as a class that mixes business logic and database access violates it at the class level.

In fact, some of the most impactful SRP violations occur at the architectural level. We will explore this in Part 10.

Part 3: Recognizing SRP Violations in C# Code

Now let us get practical. How do you spot SRP violations in a real codebase? Here are the most reliable indicators.

Indicator 1: The Class Has Multiple Reasons to Change

This is the classic test. Look at a class and ask: "What might cause me to change this class?" If you can identify multiple independent axes of change, you have a likely SRP violation.

public class InvoiceService
{
    private readonly IDbConnection _db;
    private readonly IEmailSender _email;

    public InvoiceService(IDbConnection db, IEmailSender email)
    {
        _db = db;
        _email = email;
    }

    public Invoice CreateInvoice(Order order)
    {
        // Business logic: calculate line items, apply tax rules, compute totals
        var invoice = new Invoice
        {
            OrderId = order.Id,
            LineItems = order.Items.Select(i => new InvoiceLineItem
            {
                Description = i.ProductName,
                Quantity = i.Quantity,
                UnitPrice = i.UnitPrice,
                Total = i.Quantity * i.UnitPrice
            }).ToList()
        };

        invoice.Subtotal = invoice.LineItems.Sum(li => li.Total);
        invoice.Tax = invoice.Subtotal * 0.08m; // Tax rate
        invoice.Total = invoice.Subtotal + invoice.Tax;

        return invoice;
    }

    public void SaveInvoice(Invoice invoice)
    {
        // Persistence logic: insert into database
        _db.Execute(
            "INSERT INTO Invoices (OrderId, Subtotal, Tax, Total) VALUES (@OrderId, @Subtotal, @Tax, @Total)",
            invoice);

        foreach (var lineItem in invoice.LineItems)
        {
            _db.Execute(
                "INSERT INTO InvoiceLineItems (InvoiceId, Description, Quantity, UnitPrice, Total) VALUES (@InvoiceId, @Description, @Quantity, @UnitPrice, @Total)",
                new { InvoiceId = invoice.Id, lineItem.Description, lineItem.Quantity, lineItem.UnitPrice, lineItem.Total });
        }
    }

    public void SendInvoiceEmail(Invoice invoice, string recipientEmail)
    {
        // Presentation logic: format the invoice as HTML for email
        var html = $"""
            <h1>Invoice #{invoice.Id}</h1>
            <table>
                <tr><th>Item</th><th>Qty</th><th>Price</th><th>Total</th></tr>
                {string.Join("", invoice.LineItems.Select(li =>
                    $"<tr><td>{li.Description}</td><td>{li.Quantity}</td><td>{li.UnitPrice:C}</td><td>{li.Total:C}</td></tr>"))}
            </table>
            <p><strong>Subtotal:</strong> {invoice.Subtotal:C}</p>
            <p><strong>Tax:</strong> {invoice.Tax:C}</p>
            <p><strong>Total:</strong> {invoice.Total:C}</p>
            """;

        _email.Send(recipientEmail, $"Invoice #{invoice.Id}", html);
    }
}

This class has three independent axes of change. The accounting team might ask you to change how tax is calculated. The DBA might ask you to change the database schema. The marketing team might ask you to change how the invoice email looks. Three actors, three responsibilities, one class — a clear SRP violation.

Indicator 2: Unrelated Dependencies in the Constructor

When a class's constructor requires a grab-bag of unrelated dependencies, that is a strong signal. The InvoiceService above depends on both IDbConnection (persistence infrastructure) and IEmailSender (communication infrastructure). These have nothing to do with each other.

A useful heuristic: if you can draw a line through your constructor parameters that divides them into two groups with no relationship, you probably have two responsibilities.

Indicator 3: Methods That Do Not Use the Same Fields

In a well-designed class, most methods operate on the same internal state. When you see methods that use completely disjoint sets of fields or dependencies, those methods probably belong in separate classes.

public class ReportGenerator
{
    private readonly IDbConnection _db;       // Used by data methods
    private readonly IPdfRenderer _renderer;   // Used by rendering methods
    private readonly IFileStorage _storage;    // Used by storage methods

    public DataTable FetchReportData(DateTime from, DateTime to)
    {
        // Uses _db only
        return _db.QueryDataTable("SELECT * FROM Sales WHERE Date BETWEEN @from AND @to",
            new { from, to });
    }

    public byte[] RenderToPdf(DataTable data, string title)
    {
        // Uses _renderer only
        return _renderer.Render(data, title);
    }

    public void SaveReport(byte[] pdf, string fileName)
    {
        // Uses _storage only
        _storage.Upload(pdf, fileName);
    }
}

Each method uses exactly one dependency and ignores the others. This is a sign that ReportGenerator is really three classes wearing a trench coat.

Indicator 4: The God Class

Sometimes the violation is not subtle at all. You open a file and it is 3,000 lines long, with fifty methods, twenty fields, and a name like ApplicationManager or Utilities or Helper. This is the God Class — a class that has accumulated every responsibility nobody knew where else to put.

God classes are the ultimate SRP violation, but they are also the easiest to recognize. The harder violations are the ones that look reasonable at first glance.

Indicator 5: Merge Conflicts in the Same File

This is a process-level indicator. If two developers working on unrelated features keep getting merge conflicts in the same file, that file probably has multiple responsibilities. Developer A is changing the tax calculation logic while Developer B is changing the email template, and they are both editing InvoiceService.cs. This is exactly the collision that SRP is designed to prevent.

Part 4: Refactoring Toward SRP — A Step-by-Step Example

Let us take the InvoiceService from Part 3 and refactor it properly. The goal is not to create the maximum number of classes — it is to separate the responsibilities along actor boundaries.

Step 1: Identify the Actors

Who are the stakeholders for this code?

1. The finance team cares about how invoices are calculated — tax rules, discounts, rounding behavior.
2. The infrastructure team (or DBA) cares about how invoices are stored — database schema, query performance, transactions.
3. The communications team (or marketing) cares about how invoices are presented — email templates, formatting, branding.

Three actors, three classes.

Step 2: Extract the Business Logic

public class InvoiceCalculator
{
    private readonly TaxRateProvider _taxRateProvider;

    public InvoiceCalculator(TaxRateProvider taxRateProvider)
    {
        _taxRateProvider = taxRateProvider;
    }

    public Invoice CreateInvoice(Order order)
    {
        var invoice = new Invoice
        {
            OrderId = order.Id,
            LineItems = order.Items.Select(i => new InvoiceLineItem
            {
                Description = i.ProductName,
                Quantity = i.Quantity,
                UnitPrice = i.UnitPrice,
                Total = i.Quantity * i.UnitPrice
            }).ToList()
        };

        invoice.Subtotal = invoice.LineItems.Sum(li => li.Total);
        invoice.Tax = invoice.Subtotal * _taxRateProvider.GetRate(order.ShippingAddress);
        invoice.Total = invoice.Subtotal + invoice.Tax;

        return invoice;
    }
}

This class has one actor: the finance team. The only reason to change it is if the business rules for calculating invoices change.

Notice that we also extracted the hard-coded tax rate into a TaxRateProvider. The magic number 0.08m was a code smell — it mixed configuration with logic. Now the tax rate can vary by jurisdiction without touching the calculator.

Step 3: Extract the Persistence Logic

public class InvoiceRepository
{
    private readonly IDbConnection _db;

    public InvoiceRepository(IDbConnection db)
    {
        _db = db;
    }

    public void Save(Invoice invoice)
    {
        using var transaction = _db.BeginTransaction();
        try
        {
            _db.Execute(
                """
                INSERT INTO Invoices (OrderId, Subtotal, Tax, Total, CreatedAt)
                VALUES (@OrderId, @Subtotal, @Tax, @Total, @CreatedAt)
                """,
                new { invoice.OrderId, invoice.Subtotal, invoice.Tax, invoice.Total, CreatedAt = DateTime.UtcNow },
                transaction);

            var invoiceId = _db.QuerySingle<int>("SELECT SCOPE_IDENTITY()", transaction: transaction);

            foreach (var lineItem in invoice.LineItems)
            {
                _db.Execute(
                    """
                    INSERT INTO InvoiceLineItems (InvoiceId, Description, Quantity, UnitPrice, Total)
                    VALUES (@InvoiceId, @Description, @Quantity, @UnitPrice, @Total)
                    """,
                    new { InvoiceId = invoiceId, lineItem.Description, lineItem.Quantity, lineItem.UnitPrice, lineItem.Total },
                    transaction);
            }

            transaction.Commit();
        }
        catch
        {
            transaction.Rollback();
            throw;
        }
    }

    public Invoice? GetById(int id)
    {
        return _db.QuerySingleOrDefault<Invoice>(
            "SELECT * FROM Invoices WHERE Id = @Id", new { Id = id });
    }
}

This class has one actor: the infrastructure team. The only reason to change it is if the database schema changes or if you need to optimize queries.

Notice we also added a transaction — something the original InvoiceService was missing. When responsibilities are separated, it becomes easier to get the details right for each one.

Step 4: Extract the Presentation Logic

public class InvoiceEmailSender
{
    private readonly IEmailSender _email;

    public InvoiceEmailSender(IEmailSender email)
    {
        _email = email;
    }

    public async Task SendAsync(Invoice invoice, string recipientEmail)
    {
        var html = BuildEmailHtml(invoice);
        await _email.SendAsync(recipientEmail, $"Invoice #{invoice.Id}", html);
    }

    private static string BuildEmailHtml(Invoice invoice)
    {
        var rows = string.Join("", invoice.LineItems.Select(li =>
            $"<tr><td>{li.Description}</td><td>{li.Quantity}</td><td>{li.UnitPrice:C}</td><td>{li.Total:C}</td></tr>"));

        return $"""
            <!DOCTYPE html>
            <html>
            <body style="font-family: Arial, sans-serif;">
                <h1>Invoice #{invoice.Id}</h1>
                <table border="1" cellpadding="8" cellspacing="0">
                    <thead>
                        <tr><th>Item</th><th>Qty</th><th>Price</th><th>Total</th></tr>
                    </thead>
                    <tbody>{rows}</tbody>
                </table>
                <p><strong>Subtotal:</strong> {invoice.Subtotal:C}</p>
                <p><strong>Tax:</strong> {invoice.Tax:C}</p>
                <p><strong>Total:</strong> {invoice.Total:C}</p>
            </body>
            </html>
            """;
    }
}

One actor: the communications/marketing team. The only reason to change this class is if the email format or branding changes.

Step 5: Compose Them Together

Now we need something to orchestrate these three classes. This is a legitimate responsibility of its own — coordinating the workflow of creating, saving, and sending an invoice.

public class InvoiceWorkflow
{
    private readonly InvoiceCalculator _calculator;
    private readonly InvoiceRepository _repository;
    private readonly InvoiceEmailSender _emailSender;
    private readonly ILogger<InvoiceWorkflow> _logger;

    public InvoiceWorkflow(
        InvoiceCalculator calculator,
        InvoiceRepository repository,
        InvoiceEmailSender emailSender,
        ILogger<InvoiceWorkflow> logger)
    {
        _calculator = calculator;
        _repository = repository;
        _emailSender = emailSender;
        _logger = logger;
    }

    public async Task ProcessOrderAsync(Order order, string customerEmail)
    {
        _logger.LogInformation("Creating invoice for order {OrderId}", order.Id);

        var invoice = _calculator.CreateInvoice(order);
        _repository.Save(invoice);

        _logger.LogInformation("Invoice {InvoiceId} saved for order {OrderId}", invoice.Id, order.Id);

        await _emailSender.SendAsync(invoice, customerEmail);

        _logger.LogInformation("Invoice email sent to {Email}", customerEmail);
    }
}

Is this class violating SRP? It depends on three other classes, after all. But look at what it does — it simply calls the three collaborators in sequence. It contains no business logic, no persistence logic, and no presentation logic. Its single responsibility is orchestration, and it serves a single actor: whoever owns the business process of invoicing. If the sequence of steps changes (maybe invoices need approval before sending), this is the only class that changes.

The Result

We went from one class with three responsibilities to four classes, each with one:

Each class can change independently. The finance team can add discount logic to InvoiceCalculator without touching the email template. The DBA can migrate from SQL Server to PostgreSQL by changing only InvoiceRepository. The marketing team can redesign the email in InvoiceEmailSender without risking a broken tax calculation.

Part 5: SRP at the Method Level

SRP does not only apply to classes. It applies to methods too, and this is often where the most impactful improvements can be made.

The "And" Test

Read the name of a method. If you have to use the word "and" to describe what it does, it probably has multiple responsibilities.

// Bad: this method validates AND saves AND notifies
public async Task ValidateAndSaveAndNotifyAsync(User user)
{
    // Validation
    if (string.IsNullOrWhiteSpace(user.Email))
        throw new ValidationException("Email is required");
    if (user.Email.Length > 255)
        throw new ValidationException("Email too long");
    if (!user.Email.Contains('@'))
        throw new ValidationException("Invalid email format");

    // Persistence
    await _db.ExecuteAsync("INSERT INTO Users (Email, Name) VALUES (@Email, @Name)", user);

    // Notification
    await _emailSender.SendAsync(user.Email, "Welcome!", "Thanks for signing up!");
}

Better:

public async Task RegisterUserAsync(User user)
{
    ValidateUser(user);
    await SaveUserAsync(user);
    await SendWelcomeEmailAsync(user);
}

private static void ValidateUser(User user)
{
    if (string.IsNullOrWhiteSpace(user.Email))
        throw new ValidationException("Email is required");
    if (user.Email.Length > 255)
        throw new ValidationException("Email too long");
    if (!user.Email.Contains('@'))
        throw new ValidationException("Invalid email format");
}

private async Task SaveUserAsync(User user)
{
    await _db.ExecuteAsync("INSERT INTO Users (Email, Name) VALUES (@Email, @Name)", user);
}

private async Task SendWelcomeEmailAsync(User user)
{
    await _emailSender.SendAsync(user.Email, "Welcome!", "Thanks for signing up!");
}

Each private method does one thing. The public method composes them. The code reads like a story.

The Abstraction Level Test

A method should operate at a single level of abstraction. When a method mixes high-level orchestration with low-level details, it becomes harder to understand and harder to change.

// Bad: mixes high-level workflow with low-level string manipulation
public async Task<string> GenerateReportAsync(int year, int quarter)
{
    var data = await _repository.GetSalesDataAsync(year, quarter);

    // Suddenly we're doing low-level CSV formatting
    var sb = new StringBuilder();
    sb.AppendLine("Product,Revenue,Units,AvgPrice");
    foreach (var row in data)
    {
        sb.Append(row.Product.Replace(",", "\\,"));
        sb.Append(',');
        sb.Append(row.Revenue.ToString("F2", CultureInfo.InvariantCulture));
        sb.Append(',');
        sb.Append(row.Units);
        sb.Append(',');
        sb.AppendLine((row.Revenue / row.Units).ToString("F2", CultureInfo.InvariantCulture));
    }

    var fileName = $"sales-{year}-Q{quarter}.csv";
    await _storage.UploadAsync(fileName, Encoding.UTF8.GetBytes(sb.ToString()));

    return fileName;
}

Better:

public async Task<string> GenerateReportAsync(int year, int quarter)
{
    var data = await _repository.GetSalesDataAsync(year, quarter);
    var csv = FormatAsCsv(data);
    var fileName = $"sales-{year}-Q{quarter}.csv";
    await _storage.UploadAsync(fileName, Encoding.UTF8.GetBytes(csv));
    return fileName;
}

private static string FormatAsCsv(IReadOnlyList<SalesRow> data)
{
    var sb = new StringBuilder();
    sb.AppendLine("Product,Revenue,Units,AvgPrice");
    foreach (var row in data)
    {
        sb.Append(EscapeCsvField(row.Product));
        sb.Append(',');
        sb.Append(row.Revenue.ToString("F2", CultureInfo.InvariantCulture));
        sb.Append(',');
        sb.Append(row.Units);
        sb.Append(',');
        sb.AppendLine((row.Revenue / row.Units).ToString("F2", CultureInfo.InvariantCulture));
    }
    return sb.ToString();
}

private static string EscapeCsvField(string field)
{
    if (field.Contains(',') || field.Contains('"') || field.Contains('\n'))
        return $"\"{field.Replace("\"", "\"\"")}\"";
    return field;
}

Now the public method reads at one level of abstraction — fetch, format, upload, return — and the details are pushed into focused helper methods.

Part 6: SRP in ASP.NET Core — Controllers, Services, and Middleware

ASP.NET Core gives you a layered architecture out of the box: controllers (or minimal API endpoints) handle HTTP, services handle business logic, and middleware handles cross-cutting concerns. This layering naturally supports SRP — if you use it correctly.

Fat Controllers: The Most Common ASP.NET SRP Violation

A "fat controller" is a controller that contains business logic, validation, database access, and HTTP response formatting all in one action method. This is extremely common, especially in tutorials and quick prototypes that never get cleaned up.

// Bad: fat controller action
[HttpPost("orders")]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
{
    // Validation
    if (request.Items == null || request.Items.Count == 0)
        return BadRequest("Order must have at least one item");

    foreach (var item in request.Items)
    {
        if (item.Quantity <= 0)
            return BadRequest($"Invalid quantity for {item.ProductId}");
    }

    // Business logic: check inventory
    foreach (var item in request.Items)
    {
        var product = await _db.Products.FindAsync(item.ProductId);
        if (product == null)
            return NotFound($"Product {item.ProductId} not found");
        if (product.Stock < item.Quantity)
            return Conflict($"Insufficient stock for {product.Name}");
    }

    // More business logic: calculate total
    decimal total = 0;
    var orderItems = new List<OrderItem>();
    foreach (var item in request.Items)
    {
        var product = await _db.Products.FindAsync(item.ProductId);
        var orderItem = new OrderItem
        {
            ProductId = item.ProductId,
            Quantity = item.Quantity,
            UnitPrice = product!.Price,
            Total = item.Quantity * product.Price
        };
        orderItems.Add(orderItem);
        total += orderItem.Total;

        // Side effect: decrement stock
        product.Stock -= item.Quantity;
    }

    // Persistence
    var order = new Order
    {
        CustomerId = request.CustomerId,
        Items = orderItems,
        Total = total,
        CreatedAt = DateTime.UtcNow
    };
    _db.Orders.Add(order);
    await _db.SaveChangesAsync();

    // Notification
    await _emailSender.SendAsync(request.CustomerEmail,
        "Order Confirmation",
        $"Your order #{order.Id} for {total:C} has been placed.");

    return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
}

This single action method handles: HTTP request validation, business rule validation (inventory check), price calculation, stock management, database persistence, email notification, and HTTP response formatting. That is at least five responsibilities.

The Refactored Version

// Controller: only HTTP concerns
[HttpPost("orders")]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
{
    var result = await _orderService.PlaceOrderAsync(request);

    return result.Match<IActionResult>(
        success: order => CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order),
        validationError: errors => BadRequest(errors),
        notFound: message => NotFound(message),
        conflict: message => Conflict(message));
}

// Service: business logic orchestration
public class OrderService
{
    private readonly IOrderValidator _validator;
    private readonly IInventoryService _inventory;
    private readonly IPricingService _pricing;
    private readonly IOrderRepository _repository;
    private readonly IOrderNotifier _notifier;
    private readonly ILogger<OrderService> _logger;

    public OrderService(
        IOrderValidator validator,
        IInventoryService inventory,
        IPricingService pricing,
        IOrderRepository repository,
        IOrderNotifier notifier,
        ILogger<OrderService> logger)
    {
        _validator = validator;
        _inventory = inventory;
        _pricing = pricing;
        _repository = repository;
        _notifier = notifier;
        _logger = logger;
    }

    public async Task<OrderResult> PlaceOrderAsync(CreateOrderRequest request)
    {
        var validationResult = _validator.Validate(request);
        if (!validationResult.IsValid)
            return OrderResult.ValidationError(validationResult.Errors);

        var availabilityResult = await _inventory.CheckAvailabilityAsync(request.Items);
        if (!availabilityResult.IsAvailable)
            return OrderResult.Conflict(availabilityResult.Message);

        var pricedItems = await _pricing.CalculateAsync(request.Items);
        var order = await _repository.CreateAsync(request.CustomerId, pricedItems);
        await _inventory.ReserveStockAsync(order.Items);

        _logger.LogInformation("Order {OrderId} placed for customer {CustomerId}",
            order.Id, request.CustomerId);

        // Fire-and-forget notification (or use a message queue)
        _ = _notifier.SendConfirmationAsync(order, request.CustomerEmail);

        return OrderResult.Success(order);
    }
}

Now the controller knows nothing about business rules. The OrderService orchestrates the workflow but delegates each responsibility to a focused collaborator. The validator, inventory service, pricing service, repository, and notifier each have a single responsibility.

Minimal APIs and SRP

With .NET minimal APIs, the temptation to put everything in a lambda is even stronger:

// Bad: everything in a lambda
app.MapPost("/orders", async (CreateOrderRequest request, AppDbContext db, IEmailSender email) =>
{
    // 50 lines of mixed concerns...
});

The fix is the same — extract a service:

app.MapPost("/orders", async (CreateOrderRequest request, OrderService service) =>
{
    var result = await service.PlaceOrderAsync(request);
    return result.Match(
        success: order => Results.Created($"/orders/{order.Id}", order),
        validationError: errors => Results.BadRequest(errors),
        notFound: message => Results.NotFound(message),
        conflict: message => Results.Conflict(message));
});

Middleware and Cross-Cutting Concerns

ASP.NET Core middleware is a natural home for cross-cutting concerns that should not leak into controllers or services. Each middleware should handle exactly one concern:

// Good: each middleware has a single responsibility
app.UseExceptionHandler("/error");   // Error handling
app.UseHttpsRedirection();           // Transport security
app.UseAuthentication();             // Identity verification
app.UseAuthorization();              // Access control
app.UseRateLimiting();               // Traffic management
app.UseResponseCaching();            // Performance optimization

If you find yourself writing a single middleware that handles both logging and authentication, split it in two. The middleware pipeline is designed for composition.

Part 7: SRP and Dependency Injection

Dependency injection and SRP are natural allies. When each class has a single responsibility, its dependencies are few, focused, and easy to mock. When SRP is violated, dependencies multiply and testing becomes painful.

The Constructor Over-Injection Smell

If a class requires more than four or five constructor dependencies, that is a strong signal of an SRP violation. The cure is not to use a service locator or property injection — it is to split the class.

// Smells like an SRP violation
public class OrderProcessor
{
    public OrderProcessor(
        IOrderValidator validator,
        IInventoryChecker inventory,
        IPricingEngine pricing,
        IDiscountCalculator discounts,
        ITaxCalculator tax,
        IShippingCalculator shipping,
        IPaymentGateway payment,
        IOrderRepository repository,
        IEmailSender email,
        ISmsNotifier sms,
        IAuditLogger audit,
        IAnalyticsTracker analytics)
    {
        // 12 dependencies = multiple responsibilities
    }
}

Twelve dependencies means this class is doing too much. Some natural groupings emerge: pricing (pricing + discounts + tax + shipping), payment processing, persistence, and notification (email + SMS). Each group should be its own class.

DI Registration as Documentation

Your Program.cs (or wherever you register services) is a map of your application's responsibilities. When it is well-organized, you can read it and understand the architecture:

// Each section registers classes for one responsibility area
// --- Business Logic ---
builder.Services.AddScoped<InvoiceCalculator>();
builder.Services.AddScoped<TaxRateProvider>();
builder.Services.AddScoped<DiscountEngine>();

// --- Persistence ---
builder.Services.AddScoped<IInvoiceRepository, SqlInvoiceRepository>();
builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();

// --- Notifications ---
builder.Services.AddScoped<IEmailSender, SmtpEmailSender>();
builder.Services.AddScoped<InvoiceEmailSender>();

// --- Orchestration ---
builder.Services.AddScoped<InvoiceWorkflow>();
builder.Services.AddScoped<OrderService>();

If you cannot organize your registrations into coherent groups, your classes probably do not have coherent responsibilities.

Part 8: SRP and Testing

Perhaps the most practical argument for SRP is that it makes testing dramatically easier. When a class has one responsibility, it has one reason to test. Its test setup is simple, its assertions are focused, and its test suite is easy to maintain.

Testing a Class with Multiple Responsibilities

Consider testing the original InvoiceService from Part 3. To test the CreateInvoice method (business logic), you need to set up an IDbConnection and an IEmailSender — even though the method does not use them. This is a sign that the class has dependencies it should not have.

// Painful: unnecessary mocking
[Fact]
public void CreateInvoice_CalculatesCorrectTotal()
{
    // We have to create these even though CreateInvoice doesn't use them
    var mockDb = new Mock<IDbConnection>();
    var mockEmail = new Mock<IEmailSender>();

    var service = new InvoiceService(mockDb.Object, mockEmail.Object);

    var order = new Order
    {
        Id = 1,
        Items =
        [
            new OrderItem { ProductName = "Widget", Quantity = 3, UnitPrice = 10.00m }
        ]
    };

    var invoice = service.CreateInvoice(order);

    Assert.Equal(30.00m, invoice.Subtotal);
    Assert.Equal(2.40m, invoice.Tax);
    Assert.Equal(32.40m, invoice.Total);
}

Testing After Refactoring

After splitting into InvoiceCalculator, the test is clean:

[Fact]
public void CreateInvoice_CalculatesCorrectTotal()
{
    var taxProvider = new FakeTaxRateProvider(rate: 0.08m);
    var calculator = new InvoiceCalculator(taxProvider);

    var order = new Order
    {
        Id = 1,
        Items =
        [
            new OrderItem { ProductName = "Widget", Quantity = 3, UnitPrice = 10.00m }
        ]
    };

    var invoice = calculator.CreateInvoice(order);

    Assert.Equal(30.00m, invoice.Subtotal);
    Assert.Equal(2.40m, invoice.Tax);
    Assert.Equal(32.40m, invoice.Total);
}

No mock database. No mock email sender. Just the class under test and its actual dependency. The test is shorter, more readable, and more resilient to changes in unrelated parts of the system.

Testing the Repository in Isolation

[Fact]
public async Task Save_InsertsInvoiceAndLineItems()
{
    using var connection = new SqliteConnection("Data Source=:memory:");
    await connection.OpenAsync();
    await CreateTablesAsync(connection);

    var repository = new InvoiceRepository(connection);
    var invoice = new Invoice
    {
        OrderId = 42,
        Subtotal = 100m,
        Tax = 8m,
        Total = 108m,
        LineItems =
        [
            new InvoiceLineItem
            {
                Description = "Widget",
                Quantity = 10,
                UnitPrice = 10m,
                Total = 100m
            }
        ]
    };

    repository.Save(invoice);

    var saved = await connection.QuerySingleAsync<int>("SELECT COUNT(*) FROM Invoices");
    Assert.Equal(1, saved);

    var lineItems = await connection.QuerySingleAsync<int>("SELECT COUNT(*) FROM InvoiceLineItems");
    Assert.Equal(1, lineItems);
}

This test exercises only persistence logic. It does not need to worry about tax rates or email templates. If the test fails, you know the problem is in the persistence code.

Testing the Email Sender in Isolation

[Fact]
public async Task SendAsync_FormatsInvoiceAsHtml()
{
    var mockEmail = new Mock<IEmailSender>();
    string? capturedBody = null;
    mockEmail
        .Setup(e => e.SendAsync(It.IsAny<string>(), It.IsAny<string>(), It.IsAny<string>()))
        .Callback<string, string, string>((to, subject, body) => capturedBody = body)
        .Returns(Task.CompletedTask);

    var sender = new InvoiceEmailSender(mockEmail.Object);
    var invoice = new Invoice
    {
        Id = 99,
        Subtotal = 50m,
        Tax = 4m,
        Total = 54m,
        LineItems = [new InvoiceLineItem { Description = "Gadget", Quantity = 5, UnitPrice = 10m, Total = 50m }]
    };

    await sender.SendAsync(invoice, "customer@example.com");

    Assert.NotNull(capturedBody);
    Assert.Contains("Invoice #99", capturedBody);
    Assert.Contains("Gadget", capturedBody);
}

Clean, focused, fast.

The Testing Pyramid and SRP

SRP aligns naturally with the testing pyramid. When responsibilities are separated:

• Unit tests cover individual classes (business logic, formatting, validation) with zero infrastructure dependencies. These are fast and numerous.
• Integration tests cover collaborations between classes (repository + real database, email sender + SMTP stub). These are slower but fewer.
• End-to-end tests cover complete workflows (place an order, verify the email). These are slowest and fewest.

Without SRP, every test becomes an integration test because you cannot isolate any single concern. The testing pyramid collapses into a testing rectangle — slow, expensive, and brittle.

Part 9: SRP in Real-World .NET Patterns

Let us examine how SRP manifests in several patterns you encounter daily in .NET development.

The Repository Pattern

The repository pattern is a direct application of SRP: separate data access from business logic. A repository is responsible to one actor — whoever manages the data store.

public interface IProductRepository
{
    Task<Product?> GetByIdAsync(int id);
    Task<IReadOnlyList<Product>> GetByCategoryAsync(string category);
    Task<IReadOnlyList<Product>> SearchAsync(string query, int skip, int take);
    Task AddAsync(Product product);
    Task UpdateAsync(Product product);
    Task DeleteAsync(int id);
}

All methods in this interface relate to the same concern: storing and retrieving products. The interface does not include methods for calculating prices, generating reports, or sending notifications. Those belong elsewhere.

A common SRP violation in repositories is adding query methods that serve different actors:

// Bad: the repository is serving too many actors
public interface IProductRepository
{
    // Used by the catalog service (customer-facing)
    Task<IReadOnlyList<Product>> GetActiveByCategoryAsync(string category);

    // Used by the admin dashboard (internal)
    Task<IReadOnlyList<Product>> GetAllIncludingDeletedAsync();

    // Used by the analytics service (reporting)
    Task<ProductSalesReport> GetSalesReportAsync(DateTime from, DateTime to);

    // Used by the inventory service (operations)
    Task<IReadOnlyList<Product>> GetLowStockAsync(int threshold);
}

The GetSalesReportAsync method does not belong here — it serves the analytics/reporting actor, not the data access actor. It should live in a separate IProductReportingRepository or a dedicated reporting service.

The MediatR / CQRS Pattern

The MediatR library and the Command Query Responsibility Segregation (CQRS) pattern are built on SRP. Each command handler has exactly one responsibility: handling one specific command.

public record CreateOrderCommand(int CustomerId, List<OrderItemDto> Items) : IRequest<OrderResult>;

public class CreateOrderHandler : IRequestHandler<CreateOrderCommand, OrderResult>
{
    private readonly IOrderRepository _repository;
    private readonly IPricingService _pricing;
    private readonly ILogger<CreateOrderHandler> _logger;

    public CreateOrderHandler(
        IOrderRepository repository,
        IPricingService pricing,
        ILogger<CreateOrderHandler> logger)
    {
        _repository = repository;
        _pricing = pricing;
        _logger = logger;
    }

    public async Task<OrderResult> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
    {
        var pricedItems = await _pricing.CalculateAsync(request.Items);
        var order = await _repository.CreateAsync(request.CustomerId, pricedItems);

        _logger.LogInformation("Order {OrderId} created", order.Id);

        return OrderResult.Success(order);
    }
}

Each handler is a small, focused class with a single responsibility. You can test it in isolation, reason about it in isolation, and change it without affecting other handlers.

CQRS takes this further by separating the read side (queries) from the write side (commands). The read model can be optimized for fast queries while the write model is optimized for business rule enforcement — two different actors with two different needs.

The Options Pattern

ASP.NET Core's Options pattern (IOptions<T>) is an SRP-friendly way to manage configuration. Instead of one giant configuration object, you create focused configuration classes:

public class SmtpSettings
{
    public string Host { get; set; } = "";
    public int Port { get; set; } = 587;
    public string Username { get; set; } = "";
    public string Password { get; set; } = "";
    public bool UseSsl { get; set; } = true;
}

public class InvoiceSettings
{
    public decimal DefaultTaxRate { get; set; } = 0.08m;
    public int PaymentTermDays { get; set; } = 30;
    public string CompanyName { get; set; } = "";
}

Each settings class is responsible to one actor. The IT team manages SMTP settings. The finance team manages invoice settings. Changes to email configuration never accidentally affect invoice configuration.

The Specification Pattern

The Specification pattern separates query criteria from query execution:

public class ActiveProductsInCategorySpec : Specification<Product>
{
    public ActiveProductsInCategorySpec(string category)
    {
        Where(p => p.IsActive && p.Category == category);
        OrderBy(p => p.Name);
        Take(50);
    }
}

public class LowStockProductsSpec : Specification<Product>
{
    public LowStockProductsSpec(int threshold)
    {
        Where(p => p.Stock < threshold);
        OrderByDescending(p => p.Stock);
    }
}

Each specification has a single responsibility: defining one set of query criteria. The repository handles execution. This keeps the repository from becoming a dumping ground for query methods.

Part 10: SRP at the Architectural Level

SRP applies beyond individual classes. At the architectural level, it guides how you structure assemblies, projects, and services.

Project Structure

A common .NET project structure reflects SRP at the assembly level:

src/
  MyApp.Domain/           # Business entities, value objects, domain events
  MyApp.Application/      # Use cases, commands, queries, interfaces
  MyApp.Infrastructure/   # Database access, file system, external APIs
  MyApp.Web/              # HTTP endpoints, view models, middleware

Each project has one responsibility. Domain knows nothing about databases. Infrastructure knows nothing about HTTP. Web knows nothing about SQL. Changes to the database schema affect only Infrastructure. Changes to the API contract affect only Web.

Microservices and SRP

Each microservice should have a single responsibility — serving one bounded context. A UserService that handles authentication, profile management, and recommendation engines is violating SRP at the service level.

The cost of splitting too aggressively at the microservice level is high — distributed systems are complex. But the cost of a monolithic service that multiple teams need to deploy independently is higher. SRP helps you find the right boundaries.

The Vertical Slice Architecture

Vertical slice architecture, popularized by Jimmy Bogard, organizes code by feature rather than by layer. Each "slice" contains everything needed for one use case: the endpoint, the handler, the validator, and even the data access.

Features/
  CreateOrder/
    CreateOrderEndpoint.cs
    CreateOrderHandler.cs
    CreateOrderValidator.cs
    CreateOrderRequest.cs
  GetOrderById/
    GetOrderByIdEndpoint.cs
    GetOrderByIdHandler.cs
    GetOrderByIdResponse.cs

This is SRP applied at the feature level. Each folder is responsible to one use case — one actor's need. Changes to order creation never touch order retrieval. It is a different organizational principle than the traditional layered architecture, but it serves the same SRP goal: isolating the things that change for different reasons.

Part 11: When SRP Goes Wrong — Over-Engineering and Class Explosion

Every principle, taken to its extreme, becomes a vice. SRP is no exception.

The One-Method-Per-Class Trap

Some developers, upon learning SRP, start creating classes like:

public class UserEmailValidator
{
    public bool Validate(string email) => email.Contains('@');
}

public class UserNameValidator
{
    public bool Validate(string name) => !string.IsNullOrWhiteSpace(name);
}

public class UserAgeValidator
{
    public bool Validate(int age) => age >= 18;
}

public class UserPasswordValidator
{
    public bool Validate(string password) => password.Length >= 8;
}

Four classes for what should be one UserValidator class. All four serve the same actor (whoever defines the user validation rules), and all four change for the same reason (when validation rules change). Splitting them is not SRP — it is fragmentation.

The correct application of SRP groups them together:

public class UserValidator
{
    public ValidationResult Validate(User user)
    {
        var errors = new List<string>();

        if (string.IsNullOrWhiteSpace(user.Name))
            errors.Add("Name is required");

        if (!user.Email.Contains('@'))
            errors.Add("Invalid email format");

        if (user.Age < 18)
            errors.Add("Must be at least 18 years old");

        if (user.Password.Length < 8)
            errors.Add("Password must be at least 8 characters");

        return new ValidationResult(errors);
    }
}

One class, one responsibility: validating users. The fact that it checks multiple fields does not make it multi-responsible.

The Interface Explosion Problem

Over-zealous SRP can also lead to an explosion of interfaces:

public interface IUserCreator { Task CreateAsync(User user); }
public interface IUserUpdater { Task UpdateAsync(User user); }
public interface IUserDeleter { Task DeleteAsync(int id); }
public interface IUserFinder { Task<User?> FindAsync(int id); }
public interface IUserSearcher { Task<List<User>> SearchAsync(string query); }

Five interfaces for what should be one IUserRepository. Again, all five serve the same actor and change for the same reason. The Interface Segregation Principle (ISP) says clients should not depend on methods they do not use — but that does not mean every method gets its own interface. It means you split along client boundaries, not along method boundaries.

Finding the Right Granularity

The right level of granularity depends on your actual actors. Ask these questions:

1. Who will ask me to change this class? If the answer is one person or one team, it is probably fine.
2. When I change one method, do I risk breaking the others? If the methods are independent and non-interacting, they might belong in separate classes. If they share state and logic, they probably belong together.
3. Can I test this class without complex setup? If you need ten mocks in your test constructor, the class is doing too much. If you need zero dependencies, you might have split too aggressively and lost the ability to verify meaningful behavior.
4. Would a new team member understand this class in five minutes? If the class is 30 lines and does one obvious thing, great. If it is 30 lines spread across five files in three folders, you have traded one kind of complexity for another.

Part 12: SRP and Related Principles

SRP does not exist in isolation. It interacts with the other SOLID principles and with broader design principles.

SRP and the Open/Closed Principle (OCP)

OCP says that software entities should be open for extension but closed for modification. SRP makes OCP easier to achieve. When a class has a single responsibility, you can extend its behavior by creating a new class rather than modifying the existing one.

For example, if InvoiceCalculator only handles standard tax calculation, you can create a DiscountedInvoiceCalculator that extends it (via inheritance or composition) rather than adding discount logic to the existing class. SRP keeps each class focused enough that extension points are clear.

SRP and the Liskov Substitution Principle (LSP)

LSP says that subtypes must be substitutable for their base types. SRP violations often lead to LSP violations. When a base class has multiple responsibilities, subtypes may need to override some behavior while leaving others unchanged — and the overrides can break expectations.

Consider a base class Notification with methods Send() and Log(). An SmsNotification subclass might override Send() but need a completely different Log() implementation because SMS logging has different requirements. The two responsibilities (sending and logging) should have been separate from the start.

SRP and the Interface Segregation Principle (ISP)

ISP is SRP applied to interfaces. A "fat" interface that serves multiple actors should be split into smaller, focused interfaces — each serving one actor.

// Fat interface serving multiple actors
public interface IUserService
{
    Task<User> GetByIdAsync(int id);        // Read by many
    Task CreateAsync(User user);             // Write by admin
    Task DeactivateAsync(int id);            // Write by compliance
    Task<UserReport> GenerateReportAsync();   // Read by analytics
}

// Split by actor
public interface IUserReader
{
    Task<User> GetByIdAsync(int id);
}

public interface IUserAdmin
{
    Task CreateAsync(User user);
    Task DeactivateAsync(int id);
}

public interface IUserReporting
{
    Task<UserReport> GenerateReportAsync();
}

SRP and the Dependency Inversion Principle (DIP)

DIP says that high-level modules should not depend on low-level modules — both should depend on abstractions. SRP makes this practical. When each class has a single responsibility, the abstractions (interfaces) it exposes are small and focused. A IInvoiceCalculator interface with two methods is easy to mock and easy to implement. A IInvoiceService interface with fifteen methods spanning three responsibilities is a pain point.

SRP and Separation of Concerns

Separation of Concerns is the broader principle from which SRP derives. While SRP focuses on the class level and defines "concern" as "an actor's needs," Separation of Concerns applies at every level — from the lines within a method to the services in a distributed system.

The MVC pattern is Separation of Concerns at the UI level: Model (data), View (presentation), Controller (user input). The layered architecture is Separation of Concerns at the application level: presentation, business logic, data access. SRP provides a specific, testable criterion for evaluating whether concerns are adequately separated.

Part 13: Applying SRP in Blazor WebAssembly

Since Observer Magazine is built on Blazor WebAssembly, let us look at how SRP applies specifically to Blazor components and services.

Components Should Not Contain Business Logic

A Blazor component's responsibility is rendering UI and handling user interactions. Business logic — calculations, validations, data transformations — belongs in services.

// Bad: business logic in the component
@code {
    private List<CartItem> _items = new();

    private decimal CalculateTotal()
    {
        var subtotal = _items.Sum(i => i.Price * i.Quantity);
        var discount = subtotal > 100 ? subtotal * 0.10m : 0;
        var tax = (subtotal - discount) * 0.08m;
        return subtotal - discount + tax;
    }

    private bool CanCheckout()
    {
        return _items.Count > 0
            && _items.All(i => i.Quantity > 0)
            && _items.Sum(i => i.Price * i.Quantity) >= 5.00m;
    }
}

// Good: component delegates to a service
@inject ICartService CartService

@code {
    private List<CartItem> _items = new();
    private decimal _total;
    private bool _canCheckout;

    private async Task RefreshAsync()
    {
        _total = CartService.CalculateTotal(_items);
        _canCheckout = CartService.CanCheckout(_items);
    }
}

The component renders and delegates. The service calculates and validates. Each can be tested independently.

Separate Data Fetching from Data Presentation

A common pattern in Blazor is to fetch data in OnInitializedAsync and render it in the markup. When the fetch logic becomes complex (caching, error handling, retry logic), extract it into a service.

// The component focuses on UI state management
@inject IBlogService BlogService

@if (_loading)
{
    <p>Loading...</p>
}
else if (_error is not null)
{
    <p class="error">@_error</p>
}
else
{
    @foreach (var post in _posts)
    {
        <BlogCard Post="post" />
    }
}

@code {
    private BlogPostMetadata[] _posts = [];
    private bool _loading = true;
    private string? _error;

    protected override async Task OnInitializedAsync()
    {
        try
        {
            _posts = await BlogService.GetPostsAsync();
        }
        catch (Exception ex)
        {
            _error = "Failed to load blog posts. Please try again later.";
        }
        finally
        {
            _loading = false;
        }
    }
}

The component handles UI states (loading, error, success). The BlogService handles HTTP calls, caching, and deserialization. The component does not know or care where the data comes from.

CSS Isolation and SRP

Blazor's component-scoped CSS (.razor.css files) is an application of SRP to styles. Each component owns its own styles. Changes to the BlogCard component's appearance do not affect ProductCard. This eliminates the "CSS blast radius" problem where a global style change breaks unrelated pages.

/* BlogCard.razor.css — only affects BlogCard */
.blog-card {
    border: 1px solid var(--border-color);
    padding: 1rem;
    border-radius: 8px;
    margin-bottom: 1rem;
}

.blog-card h3 {
    margin-top: 0;
}

This is exactly the same principle as SRP for classes — scope the concern so that changes in one area do not ripple into others.

Part 14: A Checklist for Evaluating SRP

Here is a practical checklist you can apply to any class, module, or service in your codebase. Not every "yes" answer means you have a violation — these are signals, not rules. But if you answer "yes" to three or more, it is worth investigating.

Actor Analysis:

• Can you identify more than one stakeholder or team who might request changes to this class?
• Have you received change requests from different sources that both touched this class?
• Does this class appear in merge conflicts between developers working on unrelated features?

Dependency Analysis:

• Does the constructor take more than four or five dependencies?
• Are any dependencies completely unused by some methods?
• Can you group the dependencies into two or more unrelated clusters?

Method Analysis:

• Do some methods operate on a completely different subset of fields than others?
• Would you need the word "and" to describe what this class does?
• Does the class mix different levels of abstraction (e.g., business logic and SQL strings)?

Testing Analysis:

• Do you need complex test setup that includes mock objects the test never actually exercises?
• Is it hard to name your test class because the class under test does not have a clear, single purpose?
• Do tests for one concern break when you change code related to a different concern?

Naming Analysis:

• Does the class name include words like "Manager," "Processor," "Handler," "Service," or "Utility" without further qualification? (These are often catch-all names for multi-responsibility classes.)
• Would adding a more specific suffix improve clarity? For example, OrderProcessor could be split into OrderValidator, OrderPricer, and OrderPersister.

Part 15: SRP in Practice — A Decision Framework

Theory is important, but daily development requires practical decisions. Here is a framework for deciding when and how to apply SRP.

When to Split

Split a class when:

1. Different actors need different changes. This is the textbook case. If the finance team wants to change how discounts work and the marketing team wants to change how promotions display, and both changes touch the same class, split it.

2. Testing is painful. If you need ten mocks to test one method, the class is doing too much. Split it so each piece can be tested with minimal setup.

3. The class is growing without bound. If a class keeps accumulating methods every sprint, it is probably a dumping ground. New methods should make you ask: "Does this belong here, or does it need a new home?"

4. Merge conflicts are frequent. If two developers keep stepping on each other in the same file, the file has too many responsibilities.

When NOT to Split

Do not split when:

1. All methods serve the same actor. A class with ten methods that all serve the same actor's needs is not violating SRP, even if it feels large.

2. Splitting would scatter related logic. If understanding one concern requires jumping between five files in three folders, you have gone too far. Cohesion matters.

3. The "violation" is purely theoretical. If a class technically serves two actors but one of them has not changed in three years and is unlikely to ever change, the violation is harmless. Refactor when the pain is real, not when the principle is theoretically violated.

4. You are writing a prototype or spike. SRP matters most in code that will be maintained. If you are writing a throwaway prototype to test an idea, do not spend hours on perfect separation. Just make it work. If the prototype succeeds and becomes production code, then refactor.

The Refactoring Trigger

The best time to apply SRP is not during initial development — it is when you feel the pain of a violation. The second time you need to change a class for an unrelated reason, that is your signal. The first time might be coincidence. The second time is a pattern. Refactor on the second occurrence.

This aligns with the "Rule of Three" from Martin Fowler: the first time you do something, just do it. The second time, wince. The third time, refactor.

Part 16: Common SRP Violations in the Wild

Let us catalog the SRP violations you are most likely to encounter in real .NET codebases.

The God Controller

We covered this in Part 6, but it bears repeating because it is everywhere. A controller that validates input, applies business rules, accesses the database, and formats the response is the most common SRP violation in ASP.NET applications.

The Entity with Behavior

Domain-driven design (DDD) encourages putting behavior on entities. But there is a line between "behavior that belongs to this concept" and "behavior that belongs to a different actor."

// The entity has crossed the line
public class Order
{
    public int Id { get; set; }
    public List<OrderItem> Items { get; set; } = new();
    public decimal Total => Items.Sum(i => i.Total);

    // Fine: domain behavior
    public void AddItem(Product product, int quantity)
    {
        Items.Add(new OrderItem(product, quantity));
    }

    // Questionable: persistence concern
    public void SaveToDatabase(IDbConnection db)
    {
        db.Execute("INSERT INTO Orders ...", this);
    }

    // Violation: presentation concern
    public string ToEmailHtml()
    {
        return $"<h1>Order #{Id}</h1>...";
    }

    // Violation: external API concern
    public async Task SyncToErpAsync(IErpClient client)
    {
        await client.PostOrderAsync(this);
    }
}

The AddItem method is legitimate domain behavior — it enforces business rules about what can be added to an order. But SaveToDatabase, ToEmailHtml, and SyncToErpAsync serve completely different actors and belong in separate classes.

The Utility Class

public static class Helpers
{
    public static string FormatCurrency(decimal amount) { ... }
    public static bool IsValidEmail(string email) { ... }
    public static byte[] CompressGzip(byte[] data) { ... }
    public static DateTime ParseFlexibleDate(string input) { ... }
    public static string Slugify(string title) { ... }
    public static int LevenshteinDistance(string a, string b) { ... }
}

This class is a textbook example of coincidental cohesion — the lowest form. These methods have nothing in common except that someone did not know where else to put them. They should be in separate, well-named static classes: CurrencyFormatter, EmailValidator, CompressionHelper, DateParser, SlugGenerator, StringDistance.

The Configuration Dumping Ground

public class AppSettings
{
    public string DatabaseConnectionString { get; set; } = "";
    public string SmtpHost { get; set; } = "";
    public int SmtpPort { get; set; } = 587;
    public string JwtSecret { get; set; } = "";
    public int JwtExpirationMinutes { get; set; } = 60;
    public string StorageBucket { get; set; } = "";
    public decimal DefaultTaxRate { get; set; } = 0.08m;
    public int MaxLoginAttempts { get; set; } = 5;
    public string SupportEmail { get; set; } = "";
}

Every class in the system depends on AppSettings, but each class only uses one or two properties. Use the Options pattern to split this into focused configuration classes. We covered this in Part 9.

Part 17: SRP Across the Software Development Lifecycle

SRP is not just a coding principle. It applies to processes, teams, and tooling.

SRP in Source Control

Each commit should have a single responsibility — one logical change. A commit that "adds discount feature, fixes email bug, and updates NuGet packages" is the source control equivalent of a God class. It is harder to review, harder to revert, and harder to bisect.

# Bad: one commit doing three things
git commit -m "Add discount feature, fix email bug, update packages"

# Good: three focused commits
git commit -m "feat: add percentage-based discount calculation"
git commit -m "fix: correct email template encoding for special characters"
git commit -m "chore: update NuGet packages to latest stable versions"

SRP in CI/CD Pipelines

Each stage in your pipeline should have a single responsibility:

jobs:
  build:        # Compile the code
  test:         # Run the tests
  analyze:      # Run static analysis
  package:      # Create deployment artifacts
  deploy-staging: # Deploy to staging
  deploy-prod:  # Deploy to production

Mixing build and test in a single stage makes failures harder to diagnose. Mixing deploy with test makes rollbacks harder to orchestrate.

SRP in Documentation

Each documentation file should cover one topic. A single README that explains installation, architecture, API reference, deployment, and troubleshooting is a God document. Split it:

docs/
  getting-started.md
  architecture.md
  api-reference.md
  deployment.md
  troubleshooting.md

SRP in Team Organization

Conway's Law says that organizations design systems that mirror their communication structures. If one team owns both the billing system and the notification system, those systems will tend to be coupled. SRP at the team level means giving each team ownership of one area of the business — and the code boundaries should follow.

Part 18: Summary and Key Takeaways

The Single Responsibility Principle, correctly understood, is not about class size, method count, or even the number of "things" a class does. It is about the number of actors — the groups of stakeholders whose needs drive changes to your code.

Here are the key takeaways:

The definition: A module should be responsible to one, and only one, actor.

The purpose: To prevent changes requested by one actor from accidentally breaking functionality used by another actor.

The mechanism: Group together the things that change for the same reasons. Separate the things that change for different reasons.

The balance: SRP is a guideline, not a law. Applying it dogmatically leads to class explosion and unnecessary complexity. Ignoring it leads to fragile, untestable, conflict-prone code. The sweet spot is somewhere in between, guided by real pain points rather than theoretical purity.

The practice: You do not need to get SRP right on the first pass. Write the code, feel the pain, then refactor. The second time you change a class for an unrelated reason is your signal to split.

The test: If you can test a class with simple setup and focused assertions, SRP is probably in good shape. If testing requires a Christmas tree of mock objects, something needs splitting.

Resources

• Martin, Robert C. Agile Software Development, Principles, Patterns, and Practices. Pearson, 2003. The book where SRP was first formalized as part of the SOLID principles.
• Martin, Robert C. "The Single Responsibility Principle." blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html. The 2014 blog post clarifying the "reason to change" definition.
• Martin, Robert C. Clean Architecture: A Craftsman's Guide to Software Structure and Design. Pearson, 2017. Contains the final formulation of SRP with the "actor" definition.
• DeMarco, Tom. Structured Analysis and System Specification. Yourdon Press, 1978. The origin of the cohesion concept that SRP builds upon.
• Page-Jones, Meilir. The Practical Guide to Structured Systems Design. Yourdon Press, 1980. Formalizes the spectrum of cohesion types.
• Fowler, Martin. Refactoring: Improving the Design of Existing Code. 2nd ed. Addison-Wesley, 2018. Practical techniques for refactoring toward better responsibility separation. refactoring.com
• Microsoft. "Dependency injection in ASP.NET Core." learn.microsoft.com/aspnet/core/fundamentals/dependency-injection. Official documentation on DI, which works hand-in-hand with SRP.
• Microsoft. "ASP.NET Core Blazor component-scoped CSS." learn.microsoft.com/aspnet/core/blazor/components/css-isolation. CSS isolation as SRP applied to component styles.
• Bogard, Jimmy. "Vertical Slice Architecture." jimmybogard.com/vertical-slice-architecture. An alternative to layered architecture that applies SRP at the feature level.
• DigitalOcean. "SOLID: The First Five Principles of Object-Oriented Design." digitalocean.com/community/conceptual-articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design. A thorough walkthrough of all five SOLID principles with code examples.

Now let me verify the key historical facts about the Liskov Substitution Principle before writing.I have all the historical facts verified. Now let me write the comprehensive article.Here's your complete blog article. Save it as:

content/blog/2026-03-27-liskov-substitution-principle.md

Then commit and push — GitHub Actions will handle the rest.

The article covers 16 parts spanning roughly 7,000+ words, including:

• Barbara Liskov's full history (Stanford PhD 1968, CLU, OOPSLA 1987 keynote, 1994 paper with Wing, 2008 Turing Award)
• The principle in plain language with a vending machine analogy
• All five formal rules: precondition contravariance, postcondition covariance, invariant preservation, the history constraint, and exception compatibility — each with C# code examples
• Five classic violations: Rectangle/Square, read-only collections inheriting List<T>, NotImplementedException, ignored parameters, temporal coupling
• LSP in the .NET framework itself (Stream, ICollection<T> vs IReadOnlyCollection<T>, array covariance)
• Design patterns that help (Strategy, Template Method, Decorator) and patterns that risk violations (Adapter, Null Object)
• LSP + dependency injection in ASP.NET Core with contract test patterns
• Generics variance (covariance, contravariance, invariance)
• Detection techniques (grep for NotImplementedException, type checks, contract tests, Roslyn analyzers)
• Interaction with the other SOLID principles
• A practical checklist
• Resources and further reading

The SOLID principles are a set of five design guidelines that exist precisely to fight that decay. They are not a silver bullet, nor are they a rigid checklist that you must follow dogmatically in every file you write. They are, however, among the most battle-tested heuristics in object-oriented programming for keeping code maintainable, testable, and extensible over the life of a project.

In this article, we will work through all five principles in full detail: where they came from, what they mean in precise terms, how to apply them in C# and .NET, how to spot violations, and what tradeoffs to keep in mind. Every principle gets real, compilable code examples — not toy pseudocode, but scenarios you might encounter in a production system.

Part 1: History and Context — Where SOLID Came From

The Origins

The five principles that compose the SOLID acronym were not all invented by the same person at the same time. They emerged over roughly a decade of thought by several computer scientists and were unified under a single banner by Robert C. Martin — universally known as "Uncle Bob."

Robert C. Martin first collected and articulated these principles in his 2000 paper Design Principles and Design Patterns, where he described the symptoms of rotting software (rigidity, fragility, immobility, viscosity) and proposed a set of principles to combat them. The actual acronym "SOLID" was coined around 2004 by Michael Feathers, who rearranged the initial letters of the five principles into a memorable word.

But the individual principles have deeper roots:

• Single Responsibility Principle (SRP): Articulated by Robert C. Martin, drawing on ideas about cohesion that go back to Tom DeMarco and Meilir Page-Jones in the 1970s and 1980s.
• Open/Closed Principle (OCP): First defined by Bertrand Meyer in his 1988 book Object-Oriented Software Construction. Meyer's original formulation relied on implementation inheritance; Martin later reinterpreted it using polymorphism and abstraction.
• Liskov Substitution Principle (LSP): Introduced by Barbara Liskov in her 1987 keynote Data Abstraction and Hierarchy, and formalized in a 1994 paper with Jeannette Wing. It draws on Bertrand Meyer's Design by Contract concepts.
• Interface Segregation Principle (ISP): Articulated by Robert C. Martin while consulting for Xerox in the 1990s. The principle arose from a real problem with a large, monolithic interface in a printer system.
• Dependency Inversion Principle (DIP): Formulated by Robert C. Martin, building on the broader idea that high-level policy should not depend on low-level detail.

Martin later expanded on all five in his 2003 book Agile Software Development: Principles, Patterns, and Practices and its 2006 C# edition with Micah Martin.

Why SOLID Still Matters in 2026

You might wonder whether principles conceived in the late 1980s through the early 2000s are still relevant in an era of microservices, serverless functions, functional programming, and AI-assisted code generation. The answer is a firm yes — though with some nuance.

The underlying problems that SOLID addresses — managing dependencies, isolating change, reducing coupling, enabling testability — are universal to software engineering regardless of paradigm or architecture. A microservice with tangled internal dependencies is just as painful to maintain as a monolithic class with too many responsibilities. A serverless function that depends on concrete implementations is just as hard to test as a desktop application with the same problem.

What has changed is the scale at which these principles apply. In 2000, SOLID was primarily discussed in the context of classes within a single application. Today, the same ideas apply at the level of modules, packages, services, and even entire systems. The Single Responsibility Principle can be applied to a function, a class, a NuGet package, or a microservice. Dependency Inversion shows up in hexagonal architecture, clean architecture, and any system that uses ports and adapters.

Let us now work through each principle in detail.

Part 2: The Single Responsibility Principle (SRP)

The Definition

Robert C. Martin's original formulation of the Single Responsibility Principle is:

A class should have one, and only one, reason to change.

The key phrase is "reason to change." A "reason to change" corresponds to a stakeholder or an actor — a person or group of people who might request a change to the software. If a class serves multiple actors, changes requested by one actor might break the code that serves another.

Martin later refined this definition in his 2018 book Clean Architecture:

A module should be responsible to one, and only one, actor.

This is a subtle but important shift. It is not about the class doing "only one thing" in the most literal sense — a class can have multiple methods and still have a single responsibility. The question is whether those methods all serve the same actor or the same axis of change.

A Violation in the Wild

Imagine you are building an employee management system. You write a class like this:

public class Employee
{
    public string Name { get; set; } = "";
    public decimal Salary { get; set; }
    public string Department { get; set; } = "";

    // Used by the HR department to calculate pay
    public decimal CalculatePay()
    {
        // Complex payroll logic: overtime, benefits, deductions
        return Salary * 1.0m; // simplified
    }

    // Used by the reporting team to generate reports
    public string GeneratePerformanceReport()
    {
        return $"Performance report for {Name} in {Department}";
    }

    // Used by the DBA team to persist data
    public void SaveToDatabase(string connectionString)
    {
        // ADO.NET or EF Core logic to save the employee
        Console.WriteLine($"Saving {Name} to database...");
    }
}

This class has three reasons to change:

1. The HR department changes the payroll calculation rules.
2. The reporting team changes the report format.
3. The DBA team changes the database schema or persistence strategy.

Each of these changes serves a different actor. If the reporting team asks for a new column in the performance report, you modify the Employee class — and now the payroll calculation code and the persistence code must be recompiled, retested, and redeployed, even though they did not change.

Applying SRP

The fix is to separate these responsibilities into distinct classes:

// The Employee class is now a pure data model
public class Employee
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public decimal Salary { get; set; }
    public string Department { get; set; } = "";
}

// Responsibility: payroll calculations (serves the HR actor)
public class PayrollCalculator
{
    public decimal CalculatePay(Employee employee)
    {
        // All the complex payroll logic lives here
        var basePay = employee.Salary;
        var deductions = basePay * 0.08m; // example: 8% deductions
        return basePay - deductions;
    }
}

// Responsibility: generating reports (serves the reporting actor)
public class PerformanceReportGenerator
{
    public string Generate(Employee employee)
    {
        var sb = new StringBuilder();
        sb.AppendLine($"Performance Report: {employee.Name}");
        sb.AppendLine($"Department: {employee.Department}");
        sb.AppendLine($"Generated: {DateTime.UtcNow:yyyy-MM-dd}");
        return sb.ToString();
    }
}

// Responsibility: persistence (serves the DBA/infrastructure actor)
public class EmployeeRepository
{
    private readonly string _connectionString;

    public EmployeeRepository(string connectionString)
    {
        _connectionString = connectionString;
    }

    public void Save(Employee employee)
    {
        // EF Core, Dapper, ADO.NET — whatever the persistence strategy is
        Console.WriteLine($"Saving employee {employee.Id} to database...");
    }

    public Employee? GetById(int id)
    {
        // Retrieve from database
        Console.WriteLine($"Loading employee {id} from database...");
        return null; // simplified
    }
}

Now each class has one reason to change. The PayrollCalculator changes only when payroll rules change. The PerformanceReportGenerator changes only when the report format changes. The EmployeeRepository changes only when the persistence strategy changes. The Employee class itself changes only when the data model changes.

SRP in ASP.NET and Blazor

In the ASP.NET world, SRP shows up frequently in controller and service design. A common violation is the "god controller" that handles authentication, business logic, validation, and response formatting all in one class:

// Violation: this controller does too much
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly DbContext _db;

    public OrdersController(DbContext db) => _db = db;

    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        // Validation logic (should be in a validator)
        if (string.IsNullOrEmpty(request.CustomerEmail))
            return BadRequest("Email is required");

        // Business rules (should be in a service)
        var discount = request.Total > 100 ? 0.1m : 0m;
        var finalTotal = request.Total * (1 - discount);

        // Persistence (should be in a repository)
        var order = new Order { Total = finalTotal, Email = request.CustomerEmail };
        _db.Orders.Add(order);
        await _db.SaveChangesAsync();

        // Notification (should be in a notification service)
        await SendEmailAsync(request.CustomerEmail, "Order Confirmed", $"Total: {finalTotal}");

        return Ok(order);
    }

    private Task SendEmailAsync(string to, string subject, string body)
    {
        Console.WriteLine($"Sending email to {to}: {subject}");
        return Task.CompletedTask;
    }
}

A cleaner approach separates each concern:

// The controller only orchestrates — it delegates to specialized services
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;

    public OrdersController(IOrderService orderService) => _orderService = orderService;

    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        var result = await _orderService.PlaceOrderAsync(request);
        return result.IsSuccess ? Ok(result.Order) : BadRequest(result.Error);
    }
}

// The service handles orchestration of business rules
public class OrderService : IOrderService
{
    private readonly IOrderRepository _repository;
    private readonly IDiscountCalculator _discountCalculator;
    private readonly INotificationService _notificationService;

    public OrderService(
        IOrderRepository repository,
        IDiscountCalculator discountCalculator,
        INotificationService notificationService)
    {
        _repository = repository;
        _discountCalculator = discountCalculator;
        _notificationService = notificationService;
    }

    public async Task<OrderResult> PlaceOrderAsync(CreateOrderRequest request)
    {
        var discount = _discountCalculator.Calculate(request.Total);
        var finalTotal = request.Total * (1 - discount);

        var order = new Order { Total = finalTotal, Email = request.CustomerEmail };
        await _repository.SaveAsync(order);

        await _notificationService.SendOrderConfirmationAsync(order);

        return new OrderResult { IsSuccess = true, Order = order };
    }
}

Common SRP Mistakes

Mistake 1: Taking it too far. Creating a class for every single method leads to an explosion of tiny classes that are individually simple but collectively hard to navigate. The principle is about cohesion — grouping things that change together — not about minimizing the number of methods per class.

Mistake 2: Confusing "one thing" with "one responsibility." A UserValidator class might have methods for validating email format, password strength, and username length. These are all part of one responsibility: validation of user input. They change for the same reason (validation rules change) and serve the same actor. This is a single responsibility, even though it involves multiple methods.

Mistake 3: Ignoring SRP in Blazor components. A Blazor component that fetches data, transforms it, renders it, and handles multiple types of user interaction is doing too much. Extract data fetching into services, transformation into utility classes, and complex interaction logic into separate components.

Part 3: The Open/Closed Principle (OCP)

The Definition

Bertrand Meyer first articulated this principle in his 1988 book Object-Oriented Software Construction:

Software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification.

"Open for extension" means you can add new behavior. "Closed for modification" means you do not need to change existing, working code to add that new behavior.

Meyer's original interpretation relied on implementation inheritance: you extend a class by inheriting from it and overriding methods, without modifying the base class. Robert C. Martin later reinterpreted the principle to emphasize polymorphism through abstractions (interfaces and abstract classes) rather than concrete inheritance.

Why It Matters

Every time you modify existing code, you risk introducing bugs into functionality that was previously working. If you can add new features by writing new code rather than changing old code, you dramatically reduce the surface area for regressions.

Consider a payment processing system:

// Violation: adding a new payment method requires modifying this class
public class PaymentProcessor
{
    public void ProcessPayment(string paymentType, decimal amount)
    {
        if (paymentType == "CreditCard")
        {
            Console.WriteLine($"Processing credit card payment of {amount:C}");
            // Credit card specific logic
        }
        else if (paymentType == "PayPal")
        {
            Console.WriteLine($"Processing PayPal payment of {amount:C}");
            // PayPal specific logic
        }
        else if (paymentType == "BankTransfer")
        {
            Console.WriteLine($"Processing bank transfer of {amount:C}");
            // Bank transfer specific logic
        }
        else
        {
            throw new ArgumentException($"Unknown payment type: {paymentType}");
        }
    }
}

This class violates OCP because every time the business adds a new payment method — cryptocurrency, Apple Pay, buy-now-pay-later — you must open this class and add another else if branch. Each modification risks breaking the existing branches.

Applying OCP with Polymorphism

The standard solution is to define an abstraction and let each payment method implement it:

public interface IPaymentMethod
{
    string Name { get; }
    Task<PaymentResult> ProcessAsync(decimal amount);
}

public class CreditCardPayment : IPaymentMethod
{
    public string Name => "CreditCard";

    public Task<PaymentResult> ProcessAsync(decimal amount)
    {
        Console.WriteLine($"Charging credit card: {amount:C}");
        // Real implementation: call Stripe, Square, etc.
        return Task.FromResult(new PaymentResult { Success = true, TransactionId = Guid.NewGuid().ToString() });
    }
}

public class PayPalPayment : IPaymentMethod
{
    public string Name => "PayPal";

    public Task<PaymentResult> ProcessAsync(decimal amount)
    {
        Console.WriteLine($"Processing PayPal payment: {amount:C}");
        return Task.FromResult(new PaymentResult { Success = true, TransactionId = Guid.NewGuid().ToString() });
    }
}

public class BankTransferPayment : IPaymentMethod
{
    public string Name => "BankTransfer";

    public Task<PaymentResult> ProcessAsync(decimal amount)
    {
        Console.WriteLine($"Initiating bank transfer: {amount:C}");
        return Task.FromResult(new PaymentResult { Success = true, TransactionId = Guid.NewGuid().ToString() });
    }
}

public record PaymentResult
{
    public bool Success { get; init; }
    public string TransactionId { get; init; } = "";
    public string? ErrorMessage { get; init; }
}

Now the processor is closed for modification:

public class PaymentProcessor
{
    private readonly IEnumerable<IPaymentMethod> _paymentMethods;

    public PaymentProcessor(IEnumerable<IPaymentMethod> paymentMethods)
    {
        _paymentMethods = paymentMethods;
    }

    public async Task<PaymentResult> ProcessPaymentAsync(string paymentType, decimal amount)
    {
        var method = _paymentMethods.FirstOrDefault(m =>
            m.Name.Equals(paymentType, StringComparison.OrdinalIgnoreCase));

        if (method is null)
            return new PaymentResult { Success = false, ErrorMessage = $"Unknown payment type: {paymentType}" };

        return await method.ProcessAsync(amount);
    }
}

When a new payment method is needed — say, cryptocurrency — you simply write a new class:

public class CryptoPayment : IPaymentMethod
{
    public string Name => "Crypto";

    public Task<PaymentResult> ProcessAsync(decimal amount)
    {
        Console.WriteLine($"Processing crypto payment: {amount:C}");
        return Task.FromResult(new PaymentResult { Success = true, TransactionId = Guid.NewGuid().ToString() });
    }
}

And register it in your DI container:

builder.Services.AddTransient<IPaymentMethod, CreditCardPayment>();
builder.Services.AddTransient<IPaymentMethod, PayPalPayment>();
builder.Services.AddTransient<IPaymentMethod, BankTransferPayment>();
builder.Services.AddTransient<IPaymentMethod, CryptoPayment>(); // new — no existing code changed

The PaymentProcessor class was never modified. The existing payment method classes were never modified. You added new behavior solely by writing new code.

OCP with the Strategy Pattern

The Strategy pattern is one of the most natural ways to apply OCP. Here is a sorting example that allows pluggable comparison strategies:

public interface ISortStrategy<T>
{
    IEnumerable<T> Sort(IEnumerable<T> items);
}

public class AlphabeticalSortStrategy : ISortStrategy<string>
{
    public IEnumerable<string> Sort(IEnumerable<string> items) =>
        items.OrderBy(x => x, StringComparer.OrdinalIgnoreCase);
}

public class LengthSortStrategy : ISortStrategy<string>
{
    public IEnumerable<string> Sort(IEnumerable<string> items) =>
        items.OrderBy(x => x.Length);
}

public class ReverseSortStrategy : ISortStrategy<string>
{
    public IEnumerable<string> Sort(IEnumerable<string> items) =>
        items.OrderByDescending(x => x, StringComparer.OrdinalIgnoreCase);
}

// The sorter is closed for modification — new strategies can be added without changing this class
public class ItemSorter<T>
{
    private readonly ISortStrategy<T> _strategy;

    public ItemSorter(ISortStrategy<T> strategy)
    {
        _strategy = strategy;
    }

    public IEnumerable<T> Sort(IEnumerable<T> items) => _strategy.Sort(items);
}

OCP in ASP.NET Middleware

ASP.NET Core's middleware pipeline is a beautiful example of OCP in action. The pipeline itself is closed for modification — you do not change the framework source code. But it is open for extension — you add new middleware components:

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

// Each of these extends the pipeline without modifying existing middleware
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

// Your custom middleware — extends the pipeline, modifies nothing
app.Use(async (context, next) =>
{
    var stopwatch = Stopwatch.StartNew();
    await next(context);
    stopwatch.Stop();
    context.Response.Headers["X-Response-Time"] = $"{stopwatch.ElapsedMilliseconds}ms";
});

app.MapControllers();
app.Run();

Common OCP Mistakes

Mistake 1: Premature abstraction. Do not create interfaces and abstract classes for everything "just in case" you might need to extend it later. Apply OCP when you have evidence that a particular axis of change is real or likely. The first time you need a second implementation is usually the right time to extract an interface.

Mistake 2: Thinking OCP means you can never edit a file. The principle is about design, not a literal prohibition on modifying source files. Bug fixes, refactoring for clarity, and performance improvements are all valid reasons to modify existing code. OCP is about designing your system so that adding new features does not require modifying code that already works.

Mistake 3: Switch statements are not always violations. A switch statement over a small, stable set of values (like days of the week, or a finite set of known enum values) is not necessarily an OCP violation. The principle applies when the set of cases is expected to grow over time.

Part 4: The Liskov Substitution Principle (LSP)

The Definition

Barbara Liskov introduced this principle in her 1987 keynote Data Abstraction and Hierarchy. In a 1994 paper with Jeannette Wing, she formalized it as:

Let φ(x) be a property provable about objects x of type T. Then φ(y) should be true for objects y of type S where S is a subtype of T.

Robert C. Martin restated it more accessibly:

Subtypes must be substitutable for their base types.

In practical terms: if your code works with a reference to a base class or interface, it should continue to work correctly when you substitute any derived class or implementation — without the calling code needing to know or care about the specific subtype.

The Classic Violation: Rectangle and Square

This is the most famous example of an LSP violation. In geometry, a square "is a" rectangle — it is a rectangle with equal sides. So you might model this with inheritance:

public class Rectangle
{
    public virtual int Width { get; set; }
    public virtual int Height { get; set; }

    public int CalculateArea() => Width * Height;
}

public class Square : Rectangle
{
    public override int Width
    {
        get => base.Width;
        set
        {
            base.Width = value;
            base.Height = value; // Keep sides equal
        }
    }

    public override int Height
    {
        get => base.Height;
        set
        {
            base.Height = value;
            base.Width = value; // Keep sides equal
        }
    }
}

This compiles and even seems to work. But consider a function that operates on rectangles:

public void ResizeRectangle(Rectangle rect)
{
    rect.Width = 10;
    rect.Height = 5;

    // For any Rectangle, we expect the area to be 10 * 5 = 50
    Debug.Assert(rect.CalculateArea() == 50);
}

Pass a Rectangle and the assertion holds. Pass a Square and it fails — because setting Height = 5 also sets Width = 5, so the area is 25, not 50.

The Square class cannot be substituted for Rectangle without breaking the program's correctness. This is an LSP violation.

The Fix

The solution is to rethink the inheritance hierarchy. In terms of behavior, a square is not a rectangle because it does not honor the rectangle's contract that width and height can be set independently. A better design uses composition or separate types:

public interface IShape
{
    int CalculateArea();
}

public class Rectangle : IShape
{
    public int Width { get; }
    public int Height { get; }

    public Rectangle(int width, int height)
    {
        Width = width;
        Height = height;
    }

    public int CalculateArea() => Width * Height;
}

public class Square : IShape
{
    public int Side { get; }

    public Square(int side)
    {
        Side = side;
    }

    public int CalculateArea() => Side * Side;
}

Now Rectangle and Square are siblings under IShape, not parent and child. No code that works with IShape will be surprised by either implementation because neither makes promises it cannot keep.

LSP and Design by Contract

The Liskov Substitution Principle is closely related to Bertrand Meyer's Design by Contract, which he introduced in his 1988 book Object-Oriented Software Construction and implemented in the Eiffel language. The rules are:

1. Preconditions cannot be strengthened in a subtype. If the base class accepts any positive integer, the subtype cannot demand only even numbers.
2. Postconditions cannot be weakened in a subtype. If the base class guarantees the result is non-null, the subtype cannot return null.
3. Invariants must be preserved. If the base class guarantees that a balance is never negative, the subtype must maintain that guarantee.

Here is a practical C# example:

public abstract class Account
{
    public decimal Balance { get; protected set; }

    // Precondition: amount > 0
    // Postcondition: Balance decreases by amount
    // Invariant: Balance >= 0
    public virtual void Withdraw(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentException("Amount must be positive");

        if (Balance - amount < 0)
            throw new InvalidOperationException("Insufficient funds");

        Balance -= amount;
    }
}

public class SavingsAccount : Account
{
    // CORRECT: Does not strengthen the precondition.
    // Adds a postcondition (minimum balance check) that is stricter,
    // which is allowed because it does not weaken the base class guarantee.
    public override void Withdraw(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentException("Amount must be positive");

        if (Balance - amount < 100) // Minimum balance of 100
            throw new InvalidOperationException("Must maintain minimum balance of 100");

        Balance -= amount;
    }
}

public class FixedDepositAccount : Account
{
    // VIOLATION: This strengthens the precondition by adding a maturity date check.
    // Code that works with Account.Withdraw() will be surprised when this throws
    // for a reason it did not expect.
    public DateTime MaturityDate { get; set; }

    public override void Withdraw(decimal amount)
    {
        if (DateTime.UtcNow < MaturityDate)
            throw new InvalidOperationException("Cannot withdraw before maturity");

        base.Withdraw(amount);
    }
}

The FixedDepositAccount violates LSP because it introduces a new precondition — the current date must be past the maturity date — that callers working with the base Account type do not expect. A better design would either not inherit from Account or use a separate interface that explicitly models the maturity constraint.

Real-World LSP Violations in .NET

Violating LSP with collections: A common trap is returning a ReadOnlyCollection<T> from a property typed as IList<T>. The IList<T> interface includes Add, Remove, and Insert methods, but ReadOnlyCollection<T> throws NotSupportedException when you call them. Code that expects an IList<T> to support mutation will break.

// Violation: IList<T> promises mutation, but this implementation does not deliver
public class UserService
{
    private readonly List<string> _roles = ["admin", "editor", "viewer"];

    // This return type promises mutability but delivers read-only
    public IList<string> GetRoles() => _roles.AsReadOnly();
}

// Better: use a type that accurately describes the contract
public class UserServiceFixed
{
    private readonly List<string> _roles = ["admin", "editor", "viewer"];

    public IReadOnlyList<string> GetRoles() => _roles.AsReadOnly();
}

Violating LSP with exceptions: If a base class method does not document that it throws a specific exception, a derived class should not introduce that exception. Callers who are not prepared to catch it will be surprised.

public interface IFileReader
{
    string ReadAll(string path);
}

// Good: throws IOException, which is expected for file operations
public class LocalFileReader : IFileReader
{
    public string ReadAll(string path) => File.ReadAllText(path);
}

// Problematic: throws HttpRequestException, which callers of IFileReader do not expect
public class RemoteFileReader : IFileReader
{
    private readonly HttpClient _http;

    public RemoteFileReader(HttpClient http) => _http = http;

    public string ReadAll(string path)
    {
        // This can throw HttpRequestException — a surprise for callers expecting file I/O errors
        return _http.GetStringAsync(path).GetAwaiter().GetResult();
    }
}

The fix is to catch the transport-specific exceptions and wrap them in something the caller expects:

public class RemoteFileReaderFixed : IFileReader
{
    private readonly HttpClient _http;

    public RemoteFileReaderFixed(HttpClient http) => _http = http;

    public string ReadAll(string path)
    {
        try
        {
            return _http.GetStringAsync(path).GetAwaiter().GetResult();
        }
        catch (HttpRequestException ex)
        {
            throw new IOException($"Failed to read remote file: {path}", ex);
        }
    }
}

How to Test for LSP Compliance

Write tests that exercise the base type contract, then run those same tests against every subtype:

public abstract class ShapeTests<T> where T : IShape
{
    protected abstract T CreateShape();

    [Fact]
    public void Area_ShouldBeNonNegative()
    {
        var shape = CreateShape();
        Assert.True(shape.CalculateArea() >= 0);
    }
}

public class RectangleTests : ShapeTests<Rectangle>
{
    protected override Rectangle CreateShape() => new(5, 3);

    [Fact]
    public void Area_ShouldBeWidthTimesHeight()
    {
        var rect = new Rectangle(5, 3);
        Assert.Equal(15, rect.CalculateArea());
    }
}

public class SquareTests : ShapeTests<Square>
{
    protected override Square CreateShape() => new(4);

    [Fact]
    public void Area_ShouldBeSideSquared()
    {
        var square = new Square(4);
        Assert.Equal(16, square.CalculateArea());
    }
}

If any derived class fails a test written for the base type, you have an LSP violation.

Part 5: The Interface Segregation Principle (ISP)

The Definition

Clients should not be forced to depend upon interfaces that they do not use.

Robert C. Martin developed this principle while consulting for Xerox. The Xerox printer system had a single "Job" interface with methods for printing, stapling, collating, faxing, and scanning. Every client — even one that only needed to print — was forced to depend on the entire interface. Changes to the faxing methods forced recompilation of printing clients, even though they had nothing to do with faxing.

A Violation

Consider a worker interface in a factory management system:

public interface IWorker
{
    void Work();
    void Eat();
    void Sleep();
    void AttendMeeting();
    void WriteReport();
}

public class HumanWorker : IWorker
{
    public void Work() => Console.WriteLine("Working...");
    public void Eat() => Console.WriteLine("Eating lunch...");
    public void Sleep() => Console.WriteLine("Sleeping...");
    public void AttendMeeting() => Console.WriteLine("In a meeting...");
    public void WriteReport() => Console.WriteLine("Writing report...");
}

public class RobotWorker : IWorker
{
    public void Work() => Console.WriteLine("Robot working...");

    // Robots do not eat
    public void Eat() => throw new NotSupportedException("Robots don't eat");

    // Robots do not sleep
    public void Sleep() => throw new NotSupportedException("Robots don't sleep");

    // Robots do not attend meetings
    public void AttendMeeting() => throw new NotSupportedException("Robots don't attend meetings");

    // Robots do not write reports
    public void WriteReport() => throw new NotSupportedException("Robots don't write reports");
}

The RobotWorker class is forced to implement five methods, four of which it does not support. This is an ISP violation — and it is also an LSP violation, since substituting a RobotWorker for a HumanWorker will throw exceptions that callers do not expect.

Applying ISP

Split the interface into smaller, focused interfaces that each describe a single capability:

public interface IWorkable
{
    void Work();
}

public interface IFeedable
{
    void Eat();
}

public interface ISleepable
{
    void Sleep();
}

public interface IMeetingAttendee
{
    void AttendMeeting();
}

public interface IReportWriter
{
    void WriteReport();
}

public class HumanWorker : IWorkable, IFeedable, ISleepable, IMeetingAttendee, IReportWriter
{
    public void Work() => Console.WriteLine("Working...");
    public void Eat() => Console.WriteLine("Eating lunch...");
    public void Sleep() => Console.WriteLine("Sleeping...");
    public void AttendMeeting() => Console.WriteLine("In a meeting...");
    public void WriteReport() => Console.WriteLine("Writing report...");
}

public class RobotWorker : IWorkable
{
    public void Work() => Console.WriteLine("Robot working efficiently...");
}

Now RobotWorker only implements what it actually supports. Code that only needs a worker can accept IWorkable. Code that needs meeting attendance can accept IMeetingAttendee. No client is forced to depend on capabilities it does not use.

A Realistic .NET Example: Repository Interfaces

A common ISP violation in .NET projects is the "god repository" interface:

// Violation: every consumer depends on all methods, even if they only need one
public interface IRepository<T>
{
    Task<T?> GetByIdAsync(int id);
    Task<IReadOnlyList<T>> GetAllAsync();
    Task<IReadOnlyList<T>> FindAsync(Expression<Func<T, bool>> predicate);
    Task AddAsync(T entity);
    Task UpdateAsync(T entity);
    Task DeleteAsync(int id);
    Task<int> CountAsync();
    Task<bool> ExistsAsync(int id);
    Task BulkInsertAsync(IEnumerable<T> entities);
    Task ExecuteRawSqlAsync(string sql);
}

A read-only reporting service should not need to depend on AddAsync, DeleteAsync, or ExecuteRawSqlAsync. Split it:

public interface IReadRepository<T>
{
    Task<T?> GetByIdAsync(int id);
    Task<IReadOnlyList<T>> GetAllAsync();
    Task<IReadOnlyList<T>> FindAsync(Expression<Func<T, bool>> predicate);
    Task<int> CountAsync();
    Task<bool> ExistsAsync(int id);
}

public interface IWriteRepository<T>
{
    Task AddAsync(T entity);
    Task UpdateAsync(T entity);
    Task DeleteAsync(int id);
}

public interface IBulkRepository<T>
{
    Task BulkInsertAsync(IEnumerable<T> entities);
}

public interface IRawSqlRepository
{
    Task ExecuteRawSqlAsync(string sql);
}

// The full repository composes all the interfaces
public class ProductRepository : IReadRepository<Product>, IWriteRepository<Product>, IBulkRepository<Product>
{
    // Implementation using EF Core, Dapper, or raw ADO.NET
    public Task<Product?> GetByIdAsync(int id) => throw new NotImplementedException();
    public Task<IReadOnlyList<Product>> GetAllAsync() => throw new NotImplementedException();
    public Task<IReadOnlyList<Product>> FindAsync(Expression<Func<Product, bool>> predicate) => throw new NotImplementedException();
    public Task<int> CountAsync() => throw new NotImplementedException();
    public Task<bool> ExistsAsync(int id) => throw new NotImplementedException();
    public Task AddAsync(Product entity) => throw new NotImplementedException();
    public Task UpdateAsync(Product entity) => throw new NotImplementedException();
    public Task DeleteAsync(int id) => throw new NotImplementedException();
    public Task BulkInsertAsync(IEnumerable<Product> entities) => throw new NotImplementedException();
}

// A reporting service only depends on what it needs
public class ProductReportService
{
    private readonly IReadRepository<Product> _repository;

    public ProductReportService(IReadRepository<Product> repository)
    {
        _repository = repository;
    }

    public async Task<int> GetProductCountAsync()
    {
        return await _repository.CountAsync();
    }
}

ISP in Blazor Components

ISP also applies to the parameters and services that Blazor components depend on. A component that accepts a massive parameter object when it only needs a few fields is violating ISP at the component level:

// Violation: the component depends on the entire Order object
// but only displays the customer name and total
@code {
    [Parameter] public Order FullOrder { get; set; } = default!;
}

<p>Customer: @FullOrder.Customer.FullName</p>
<p>Total: @FullOrder.Total.ToString("C")</p>

Better: pass only what the component needs, or define a focused view model:

@code {
    [Parameter] public string CustomerName { get; set; } = "";
    [Parameter] public decimal Total { get; set; }
}

<p>Customer: @CustomerName</p>
<p>Total: @Total.ToString("C")</p>

Common ISP Mistakes

Mistake 1: Going too granular. An interface with a single method is sometimes appropriate (think IDisposable, IComparable<T>), but splitting every interface down to one method per interface can make the system harder to understand. Group methods that are almost always used together.

Mistake 2: Marker interfaces with no methods. An empty interface used only for type identification (public interface IEntity { }) is not necessarily an ISP violation — it is a different pattern entirely — but be cautious about using them for anything beyond tagging.

Mistake 3: Ignoring ISP in DI registration. Even if you split your interfaces correctly, registering them all as the same concrete type in DI means that any consumer can resolve the full implementation. Use specific interface registrations.

Part 6: The Dependency Inversion Principle (DIP)

The Definition

Robert C. Martin stated the Dependency Inversion Principle as two rules:

1. High-level modules should not depend on low-level modules. Both should depend on abstractions.
2. Abstractions should not depend on details. Details should depend on abstractions.

"High-level modules" are the parts of your system that embody business rules and policy. "Low-level modules" are the implementation details — file I/O, database access, HTTP clients, third-party APIs. The principle says that the direction of dependency should be inverted: instead of high-level code depending on low-level code, both should depend on an abstraction that lives alongside the high-level code.

Why "Inversion"?

In traditional procedural programming, the dependency structure follows the call graph: high-level code calls low-level code, and therefore depends on it. If the database layer changes, the business logic layer must change too.

Dependency Inversion flips this. The high-level module defines an interface that describes what it needs. The low-level module implements that interface. The dependency arrow now points from the low-level module toward the high-level module's abstraction, not the other way around.

A Violation

// High-level module directly depends on low-level module
public class OrderProcessor
{
    private readonly SqlServerDatabase _database;
    private readonly SmtpEmailSender _emailSender;
    private readonly FileSystemLogger _logger;

    public OrderProcessor()
    {
        _database = new SqlServerDatabase("Server=localhost;Database=Orders;...");
        _emailSender = new SmtpEmailSender("smtp.company.com", 587);
        _logger = new FileSystemLogger("/var/log/orders.log");
    }

    public void Process(Order order)
    {
        _logger.Log($"Processing order {order.Id}");
        _database.Save(order);
        _emailSender.Send(order.CustomerEmail, "Order Confirmed", $"Order {order.Id} is confirmed");
        _logger.Log($"Order {order.Id} processed");
    }
}

This code has several problems:

• OrderProcessor directly instantiates its dependencies, making it impossible to unit test without a real SQL Server, SMTP server, and file system.
• Switching from SQL Server to PostgreSQL requires modifying OrderProcessor.
• Switching from SMTP to a queue-based email service requires modifying OrderProcessor.
• The high-level business logic is tightly coupled to low-level infrastructure.

Applying DIP

Define abstractions for each dependency:

// Abstractions — these live alongside the high-level module
public interface IOrderRepository
{
    Task SaveAsync(Order order);
    Task<Order?> GetByIdAsync(int id);
}

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

public interface IAppLogger
{
    void LogInformation(string message);
    void LogError(string message, Exception? ex = null);
}

The high-level module depends only on abstractions:

public class OrderProcessor
{
    private readonly IOrderRepository _repository;
    private readonly INotificationService _notifications;
    private readonly IAppLogger _logger;

    public OrderProcessor(
        IOrderRepository repository,
        INotificationService notifications,
        IAppLogger logger)
    {
        _repository = repository;
        _notifications = notifications;
        _logger = logger;
    }

    public async Task ProcessAsync(Order order)
    {
        _logger.LogInformation($"Processing order {order.Id}");

        await _repository.SaveAsync(order);
        await _notifications.SendAsync(
            order.CustomerEmail,
            "Order Confirmed",
            $"Your order {order.Id} has been confirmed.");

        _logger.LogInformation($"Order {order.Id} processed successfully");
    }
}

Low-level modules implement the abstractions:

// Low-level module: SQL Server implementation
public class SqlServerOrderRepository : IOrderRepository
{
    private readonly string _connectionString;

    public SqlServerOrderRepository(string connectionString)
    {
        _connectionString = connectionString;
    }

    public async Task SaveAsync(Order order)
    {
        // Use EF Core, Dapper, or ADO.NET to save
        await Task.CompletedTask;
    }

    public async Task<Order?> GetByIdAsync(int id)
    {
        await Task.CompletedTask;
        return null; // simplified
    }
}

// Low-level module: PostgreSQL implementation
public class PostgresOrderRepository : IOrderRepository
{
    private readonly string _connectionString;

    public PostgresOrderRepository(string connectionString)
    {
        _connectionString = connectionString;
    }

    public async Task SaveAsync(Order order)
    {
        // Npgsql-based implementation
        await Task.CompletedTask;
    }

    public async Task<Order?> GetByIdAsync(int id)
    {
        await Task.CompletedTask;
        return null;
    }
}

// Low-level module: SMTP email
public class SmtpNotificationService : INotificationService
{
    private readonly string _smtpHost;
    private readonly int _port;

    public SmtpNotificationService(string smtpHost, int port)
    {
        _smtpHost = smtpHost;
        _port = port;
    }

    public async Task SendAsync(string to, string subject, string body)
    {
        Console.WriteLine($"Sending email via SMTP to {to}: {subject}");
        await Task.CompletedTask;
    }
}

// Low-level module: Queue-based notifications
public class QueueNotificationService : INotificationService
{
    public async Task SendAsync(string to, string subject, string body)
    {
        Console.WriteLine($"Queuing notification for {to}: {subject}");
        await Task.CompletedTask;
    }
}

Wire it up in the DI container:

// In Program.cs or Startup.cs
builder.Services.AddScoped<IOrderRepository, PostgresOrderRepository>(
    sp => new PostgresOrderRepository(builder.Configuration.GetConnectionString("Orders")!));
builder.Services.AddScoped<INotificationService, QueueNotificationService>();
builder.Services.AddScoped<IAppLogger, SerilogAppLogger>();
builder.Services.AddScoped<OrderProcessor>();

Switching from SQL Server to PostgreSQL is now a one-line change in DI registration. No business logic code is modified.

DIP and Testability

The single greatest practical benefit of DIP is testability. With abstractions injected, you can substitute test doubles:

public class OrderProcessorTests
{
    [Fact]
    public async Task ProcessAsync_SavesOrderAndSendsNotification()
    {
        // Arrange
        var savedOrders = new List<Order>();
        var sentNotifications = new List<(string To, string Subject, string Body)>();

        var mockRepo = new InMemoryOrderRepository(savedOrders);
        var mockNotifier = new FakeNotificationService(sentNotifications);
        var mockLogger = new NullAppLogger();

        var processor = new OrderProcessor(mockRepo, mockNotifier, mockLogger);
        var order = new Order { Id = 1, CustomerEmail = "test@example.com" };

        // Act
        await processor.ProcessAsync(order);

        // Assert
        Assert.Single(savedOrders);
        Assert.Equal(1, savedOrders[0].Id);
        Assert.Single(sentNotifications);
        Assert.Equal("test@example.com", sentNotifications[0].To);
    }
}

// Simple test doubles — no mocking framework needed
public class InMemoryOrderRepository : IOrderRepository
{
    private readonly List<Order> _orders;

    public InMemoryOrderRepository(List<Order> orders) => _orders = orders;

    public Task SaveAsync(Order order)
    {
        _orders.Add(order);
        return Task.CompletedTask;
    }

    public Task<Order?> GetByIdAsync(int id) =>
        Task.FromResult(_orders.FirstOrDefault(o => o.Id == id));
}

public class FakeNotificationService : INotificationService
{
    private readonly List<(string To, string Subject, string Body)> _sent;

    public FakeNotificationService(List<(string To, string Subject, string Body)> sent) => _sent = sent;

    public Task SendAsync(string to, string subject, string body)
    {
        _sent.Add((to, subject, body));
        return Task.CompletedTask;
    }
}

public class NullAppLogger : IAppLogger
{
    public void LogInformation(string message) { }
    public void LogError(string message, Exception? ex = null) { }
}

These tests run in milliseconds, require no infrastructure, and will never fail because a database is down or an SMTP server is unreachable.

DIP in Blazor WebAssembly

In Blazor WebAssembly, DIP is essential for components that consume services:

// The Blazor component depends on an abstraction
@inject IBlogService BlogService
@inject ILogger<Blog> Logger

@code {
    private BlogPostMetadata[]? posts;

    protected override async Task OnInitializedAsync()
    {
        posts = await BlogService.GetPostsAsync();
    }
}

The concrete BlogService (which uses HttpClient to fetch JSON) is registered in DI. During testing, you register a different implementation that returns canned data. The component never knows the difference.

DIP vs. Dependency Injection

A common confusion: Dependency Inversion is a design principle about the direction of dependencies. Dependency Injection is a technique for providing dependencies to a class (typically through constructor parameters). DI frameworks (like ASP.NET Core's built-in container) are tools that automate dependency injection.

You can apply Dependency Inversion without a DI container — just pass interfaces through constructors manually. And you can use a DI container without actually inverting dependencies (by injecting concrete classes instead of abstractions). They are related but distinct concepts:

• Dependency Inversion: A principle about which direction dependencies should point.
• Dependency Injection: A pattern for supplying dependencies from outside a class.
• IoC Container: A framework that automates dependency injection.

Common DIP Mistakes

Mistake 1: Abstracting everything. Not every class needs an interface. If a class is a simple data container (record Product(string Name, decimal Price)), wrapping it in an interface adds complexity with no benefit. Apply DIP to the boundaries — the seams where high-level policy meets low-level infrastructure.

Mistake 2: Leaky abstractions. An interface that mirrors the API of a specific implementation (like ISqlServerDatabase with methods named ExecuteStoredProcedure and UseTempTable) is not a real abstraction. It is just an indirection. True abstractions describe what the high-level module needs, not how the low-level module works.

Mistake 3: Putting abstractions in the wrong project. The interface should live in the same project or layer as the high-level module that depends on it, not alongside the low-level implementation. If IOrderRepository lives in your data access project, the dependency arrow still points from business logic down to data access — even though you are coding against an interface.

Part 7: How SOLID Principles Interact

The five principles are not independent — they reinforce each other. Understanding their interactions helps you apply them holistically rather than as isolated rules.

SRP + OCP

If a class has a single responsibility, it is easier to keep it closed for modification. A class that does one thing has fewer reasons to change. When new behavior is needed, you add a new class rather than modifying the existing one.

OCP + DIP

Dependency Inversion is often the mechanism by which you achieve OCP. By depending on abstractions (DIP), you can substitute different concrete implementations (OCP) without modifying the code that depends on the abstraction. The PaymentProcessor example from Part 3 works precisely because it depends on IPaymentMethod (DIP) rather than concrete payment classes.

LSP + ISP

Interface Segregation helps prevent LSP violations. When interfaces are small and focused, implementations are less likely to throw NotSupportedException or exhibit degenerate behavior. The RobotWorker that threw exceptions was both an ISP violation (fat interface) and an LSP violation (could not be substituted for IWorker without breaking things).

All Five Together: A Complete Example

Let us design a notification system that demonstrates all five principles working in concert:

// ISP: Small, focused interfaces for different capabilities
public interface INotificationSender
{
    string Channel { get; } // "email", "sms", "push"
    Task SendAsync(NotificationMessage message);
}

public interface INotificationTemplateEngine
{
    string Render(string templateName, Dictionary<string, string> variables);
}

public interface INotificationLogger
{
    Task LogAsync(NotificationMessage message, bool success, string? errorMessage = null);
}

// SRP: Each class has one reason to change
public record NotificationMessage(
    string Recipient,
    string Subject,
    string Body,
    string Channel);

public class EmailSender : INotificationSender
{
    public string Channel => "email";

    public async Task SendAsync(NotificationMessage message)
    {
        Console.WriteLine($"Sending email to {message.Recipient}: {message.Subject}");
        await Task.CompletedTask;
    }
}

public class SmsSender : INotificationSender
{
    public string Channel => "sms";

    public async Task SendAsync(NotificationMessage message)
    {
        Console.WriteLine($"Sending SMS to {message.Recipient}: {message.Body}");
        await Task.CompletedTask;
    }
}

public class PushNotificationSender : INotificationSender
{
    public string Channel => "push";

    public async Task SendAsync(NotificationMessage message)
    {
        Console.WriteLine($"Sending push notification to {message.Recipient}: {message.Subject}");
        await Task.CompletedTask;
    }
}

// OCP: Adding a new channel requires writing a new class, not modifying existing ones
// LSP: Every INotificationSender implementation is fully substitutable
// DIP: NotificationService depends on abstractions, not concrete senders

public class NotificationService
{
    private readonly IEnumerable<INotificationSender> _senders;
    private readonly INotificationTemplateEngine _templateEngine;
    private readonly INotificationLogger _logger;

    public NotificationService(
        IEnumerable<INotificationSender> senders,
        INotificationTemplateEngine templateEngine,
        INotificationLogger logger)
    {
        _senders = senders;
        _templateEngine = templateEngine;
        _logger = logger;
    }

    public async Task NotifyAsync(
        string recipient,
        string channel,
        string templateName,
        Dictionary<string, string> variables)
    {
        var body = _templateEngine.Render(templateName, variables);
        var message = new NotificationMessage(recipient, templateName, body, channel);

        var sender = _senders.FirstOrDefault(s =>
            s.Channel.Equals(channel, StringComparison.OrdinalIgnoreCase));

        if (sender is null)
        {
            await _logger.LogAsync(message, false, $"No sender found for channel: {channel}");
            return;
        }

        try
        {
            await sender.SendAsync(message);
            await _logger.LogAsync(message, true);
        }
        catch (Exception ex)
        {
            await _logger.LogAsync(message, false, ex.Message);
            throw;
        }
    }
}

Registration in DI:

builder.Services.AddTransient<INotificationSender, EmailSender>();
builder.Services.AddTransient<INotificationSender, SmsSender>();
builder.Services.AddTransient<INotificationSender, PushNotificationSender>();
builder.Services.AddTransient<INotificationTemplateEngine, HandlebarsTemplateEngine>();
builder.Services.AddTransient<INotificationLogger, DatabaseNotificationLogger>();
builder.Services.AddTransient<NotificationService>();

Adding a new channel (say, Slack):

public class SlackSender : INotificationSender
{
    public string Channel => "slack";

    public async Task SendAsync(NotificationMessage message)
    {
        Console.WriteLine($"Posting to Slack for {message.Recipient}: {message.Body}");
        await Task.CompletedTask;
    }
}

// One line added to DI — nothing else changes
builder.Services.AddTransient<INotificationSender, SlackSender>();

Part 8: Common Pitfalls and Anti-Patterns

Over-Engineering: SOLID as a Hammer

The most common pitfall is applying SOLID reflexively to every class, regardless of whether the complexity is warranted. If you have a utility class that formats dates and it will never need to be extended or substituted, wrapping it in an interface and injecting it through DI is unnecessary ceremony.

Guideline: Apply SOLID at the boundaries — where your application logic meets external systems (databases, APIs, file systems, message queues). For internal utility code that is unlikely to change, prefer simplicity.

The "Interface Per Class" Anti-Pattern

Creating an interface for every class, even when only one implementation will ever exist, leads to what some developers call "interface pollution." You end up with pairs of files — IFooService.cs and FooService.cs — where the interface is an exact copy of the class's public surface.

Guideline: Create an interface when you need polymorphism — when you will have multiple implementations, or when you need to substitute a test double. If neither applies, a concrete class is fine.

Anemic Domain Models

Overly zealous application of SRP can lead to anemic domain models — classes that are pure data containers with no behavior, while all the behavior lives in service classes. This is not inherently wrong, but it can result in procedural code dressed up in object-oriented clothing.

Guideline: Some behavior naturally belongs on the domain entity itself. A Money class that knows how to add and subtract currencies is not violating SRP — arithmetic on money is that class's single responsibility.

Circular Dependencies

Applying DIP incorrectly can create circular dependencies. If module A defines an interface that module B implements, but module B also defines an interface that module A implements, you have a cycle.

Guideline: Identify which module is the higher-level one (the one with the policy) and let that module own the abstractions. The lower-level module depends on the higher-level module's abstractions, never the reverse.

Analysis Paralysis

SOLID can lead to analysis paralysis — spending more time designing abstractions than writing code that solves the actual problem. Remember that these are principles, not laws. They exist to serve your codebase, not the other way around.

Guideline: Start simple. Write the straightforward solution. When you feel the pain of a SOLID violation — a class that keeps growing, a change that breaks unrelated tests, a type that cannot be substituted — refactor then. This approach is sometimes called "refactoring toward SOLID."

Part 9: SOLID in the Context of Modern .NET

Records and Value Objects

C# record types naturally support SRP by encouraging small, focused data structures:

// Each record has one responsibility: representing a specific concept
public record Money(decimal Amount, string Currency);
public record Address(string Street, string City, string PostalCode, string Country);
public record CustomerName(string First, string Last)
{
    public string FullName => $"{First} {Last}";
}

Pattern Matching and OCP

C# pattern matching can sometimes replace polymorphism for simple cases, but be cautious — a switch expression over a discriminated union is fine for a closed set of types, but if the set of types grows over time, polymorphism is more maintainable:

// This is fine for a small, stable set of shapes
public decimal CalculateArea(Shape shape) => shape switch
{
    Circle c => Math.PI * c.Radius * c.Radius,
    Rectangle r => r.Width * r.Height,
    Triangle t => 0.5m * t.Base * t.Height,
    _ => throw new ArgumentException($"Unknown shape: {shape.GetType().Name}")
};

// But if new shapes are added frequently, prefer an interface with a method:
public interface IShape
{
    decimal CalculateArea();
}

Minimal APIs and DIP

.NET minimal APIs work naturally with DIP:

var builder = WebApplication.CreateBuilder(args);

// Register abstractions
builder.Services.AddScoped<IOrderRepository, PostgresOrderRepository>();
builder.Services.AddScoped<IOrderService, OrderService>();

var app = builder.Build();

// Endpoints depend on abstractions injected by the framework
app.MapPost("/orders", async (CreateOrderRequest request, IOrderService orderService) =>
{
    var result = await orderService.CreateAsync(request);
    return result.IsSuccess ? Results.Created($"/orders/{result.Order!.Id}", result.Order) : Results.BadRequest(result.Error);
});

app.Run();

Source Generators and ISP

Source generators in modern .NET can auto-implement interfaces, reducing the boilerplate of ISP. Libraries like Refit generate HTTP client implementations from interfaces, and EF Core generates much of the repository plumbing. These tools make ISP cheaper to apply in practice.

Primary Constructors

C# 12 primary constructors reduce the boilerplate of DIP by eliminating explicit field declarations:

// Before C# 12
public class OrderService
{
    private readonly IOrderRepository _repository;
    private readonly INotificationService _notifications;
    private readonly ILogger<OrderService> _logger;

    public OrderService(
        IOrderRepository repository,
        INotificationService notifications,
        ILogger<OrderService> logger)
    {
        _repository = repository;
        _notifications = notifications;
        _logger = logger;
    }

    public async Task ProcessAsync(Order order)
    {
        _logger.LogInformation("Processing order {OrderId}", order.Id);
        await _repository.SaveAsync(order);
        await _notifications.SendAsync(order.CustomerEmail, "Confirmed", "...");
    }
}

// C# 12+ with primary constructors
public class OrderService(
    IOrderRepository repository,
    INotificationService notifications,
    ILogger<OrderService> logger) : IOrderService
{
    public async Task ProcessAsync(Order order)
    {
        logger.LogInformation("Processing order {OrderId}", order.Id);
        await repository.SaveAsync(order);
        await notifications.SendAsync(order.CustomerEmail, "Confirmed", "...");
    }
}

Primary constructors make DIP feel almost effortless. The dependency injection boilerplate shrinks dramatically while preserving all the benefits of abstraction and testability.

Part 10: Practical Recommendations

Here is a distilled set of actionable advice for applying SOLID in your day-to-day .NET development:

When to Apply Each Principle

SRP: Apply always. Every class, module, and function should have a clear, singular purpose. This is the easiest principle to apply and the one with the most immediate benefit.

OCP: Apply when you see a pattern of repeated modification to a class to support new variants. If a class has been opened and modified three times in the last three months to add a new case to a switch statement, it is time to apply OCP.

LSP: Apply whenever you use inheritance. Before creating a subclass, ask: "Can every function that works with the base type work correctly with this subclass?" If the answer is "not without special handling," reconsider the hierarchy.

ISP: Apply when you see classes implementing interfaces where some methods throw NotSupportedException, return dummy values, or are simply empty. Also apply when changing one method on an interface forces recompilation of clients that do not use that method.

DIP: Apply at architectural boundaries — where business logic meets infrastructure. Your domain logic should never directly reference SqlConnection, HttpClient, SmtpClient, or any other infrastructure class.

The Refactoring Approach

Rather than trying to design a perfectly SOLID system from scratch, follow this iterative approach:

1. Write the simple, obvious solution. Do not pre-abstract.
2. Watch for pain points. Classes growing too large (SRP). Frequent modifications to add new cases (OCP). Unexpected behavior from subclasses (LSP). Interfaces with methods nobody uses (ISP). Untestable code (DIP).
3. Refactor to address the specific pain. Extract a class. Extract an interface. Replace inheritance with composition.
4. Repeat. Good design is a living process, not a one-time activity.

Testing as a SOLID Litmus Test

If your code is hard to test, it almost certainly violates at least one SOLID principle:

• Hard to instantiate a class? It probably creates its own dependencies (DIP violation).
• Need to set up too much state? The class probably has too many responsibilities (SRP violation).
• Tests break when unrelated code changes? Coupling is too high, likely from fat interfaces (ISP violation) or missing abstractions (OCP violation).
• Mock behaves differently from real implementation? The inheritance hierarchy might have LSP issues.

Unit testing is both a beneficiary of SOLID design and a diagnostic tool for finding violations.

Part 11: SOLID Beyond Object-Oriented Programming

While SOLID was articulated for OOP, the underlying ideas transcend paradigm boundaries.

SRP in Functional Programming

Functions should do one thing. A function that both validates input and transforms data is harder to compose and test than two separate functions. Functional programmers achieve SRP through small, composable functions rather than small classes.

OCP via Higher-Order Functions

In functional programming, you achieve OCP by passing behavior as arguments (higher-order functions) rather than by subclassing:

// OCP via function parameters — the processing logic is open for extension
public static IEnumerable<T> Filter<T>(IEnumerable<T> items, Func<T, bool> predicate)
    => items.Where(predicate);

// Add new filtering behavior without modifying Filter
var expensiveItems = Filter(products, p => p.Price > 100);
var inStockItems = Filter(products, p => p.Stock > 0);
var featuredItems = Filter(products, p => p.IsFeatured);

DIP in Microservices

At the service level, DIP manifests as services depending on contracts (API schemas, message formats, event definitions) rather than on each other's implementations. If Service A publishes an event and Service B consumes it, both depend on the event schema (the abstraction), not on each other's internal code.

Part 12: Resources and Further Reading

If you want to go deeper into SOLID and related design topics, here are the most authoritative resources:

• Robert C. Martin, Agile Software Development: Principles, Patterns, and Practices (2003) — The definitive book on SOLID with C++ and Java examples. The 2006 C# edition (with Micah Martin) covers the same material with .NET examples.
• Robert C. Martin, Clean Architecture: A Craftsman's Guide to Software Structure and Design (2018) — Extends SOLID principles to architectural concerns, with updated thinking on SRP.
• Bertrand Meyer, Object-Oriented Software Construction, 2nd Edition (1997) — The source of the Open/Closed Principle and Design by Contract. Dense but foundational.
• Barbara Liskov and Jeannette Wing, A Behavioral Notion of Subtyping (1994) — The formal paper on the Liskov Substitution Principle. Available from Carnegie Mellon's technical reports.
• Robert C. Martin's original papers — Available at butunclebob.com. The original articles on OCP, LSP, DIP, and ISP are short, readable, and illuminating.
• Microsoft's .NET Architecture Guides — docs.microsoft.com/en-us/dotnet/architecture covers clean architecture patterns using SOLID principles with ASP.NET Core.
• Mark Seemann, Dependency Injection in .NET (2019, 2nd Edition) — Deep dive into DIP and DI patterns specifically in the .NET ecosystem.

Conclusion

The SOLID principles are not a checklist to be applied mechanically to every class in every project. They are a set of heuristics — mental tools — for recognizing and addressing design problems before they metastasize into unmaintainable code.

Single Responsibility keeps your classes small and focused. Open/Closed lets you add behavior without risking what already works. Liskov Substitution ensures that your inheritance hierarchies are sound and your polymorphism is trustworthy. Interface Segregation prevents your clients from depending on capabilities they do not need. Dependency Inversion decouples your business logic from infrastructure, making your code testable and adaptable.

None of these principles are free. Abstraction has a cost — in indirection, in the number of files to navigate, in the time spent designing interfaces. The art is in knowing when the cost is worth paying. For a throwaway script, it usually is not. For a production system that will be maintained for years, by multiple developers, through changing requirements, it almost always is.

Start simple. Write code that works. Feel the pain when it resists change. Then apply the principle that addresses that specific pain. Over time, this builds an instinct for design that no checklist can replace.

Imagine, for a moment, that nobody had a toilet at home.

Instead, every household subscribed to a managed restroom service. A gleaming porcelain throne, maintained by professionals, cleaned on a schedule, always stocked with the finest two-ply. You would never have to scrub a bowl again. You would never have to unclog a drain. You would never have to argue with your family about who left the seat up. The Toilet-as-a-Service provider would handle everything.

Sounds convenient, right? Almost too convenient. The marketing writes itself: "Focus on what matters. Let us handle the rest."

Now imagine it is 2 AM, you ate something questionable at dinner, and every single managed restroom in your availability zone is returning 503 Service Unavailable. The status page reads: "We are currently investigating elevated error rates in the Porcelain Pipeline. A fix is being implemented." You are standing in your hallway, crossing your legs, refreshing a dashboard on your phone, waiting for an incident to resolve.

You are, quite literally, out of luck.

This scenario sounds absurd because — for plumbing, at least — we collectively decided centuries ago that certain infrastructure is too critical to outsource entirely. You have a toilet at home. You have running water at home. You have electricity at home (and if you have been through enough storms, maybe a generator too). The cloud exists, but there is always a local fallback for the things that truly matter.

And yet, for AI-powered software tools — tools that developers, lawyers, designers, and medical professionals increasingly depend on for their daily work — we have somehow accepted a world with no toilet at home.

This Is Not a Hypothetical

If you are reading this article on March 30, 2026, you may have fresh memories of what happened this week. In fact, if you are an AI-assisted developer, you almost certainly do.

On March 25, Anthropic's Claude service experienced a sharp disruption that generated roughly 4,000 user reports on Downdetector at its peak. The chat interface, the mobile app, and Claude Code — the command-line developer tool — were all affected. Two days later, on March 27, elevated error rates returned on Claude Opus 4.6, with Sonnet 4.6 also showing issues before partially recovering. These were not isolated events. Earlier in March, Claude went down on March 2 and again on March 3. On March 17, free users were locked out. On March 18, Claude Code authentication broke for over eight hours. On March 21, both Opus and Sonnet models experienced elevated errors simultaneously.

Anthropic is not alone. A massive Cloudflare outage in November 2025 knocked out thousands of websites and services — including ChatGPT and OpenAI's Sora — affecting billions of users globally. ChatGPT itself suffered an extended outage exceeding 15 hours on June 10, 2025. And on this very day, March 27, 2026, Adobe is experiencing outages across Express, Photoshop, Acrobat, and other Creative Cloud services.

The pattern is clear. Cloud AI services go down. They go down often. They go down at the worst possible times. And when they go down, you cannot do your work.

The Real Cost of Cloud Dependency

Here is where the abstract becomes concrete. You are an ASP.NET developer working on a deadline. Your team uses Claude Code to refactor a legacy .NET Framework application to .NET 10. You use GitHub Copilot to scaffold tests. Your designer uses Adobe Firefly to generate assets. Your project manager uses ChatGPT to draft the release notes and client communications.

It is Thursday afternoon. The client demo is Friday morning. You try to ask Claude for help with a tricky middleware registration issue and see this:

Claude's response was interrupted. This can be caused by network problems or exceeding the maximum conversation length. Please contact support if the issue persists.

You switch to ChatGPT. It is sluggish and timing out. You try Copilot; it is returning garbage completions because the backing model is overloaded. Your designer messages you: "Firefly is broken, can't generate the hero image." Your PM says: "ChatGPT won't load, I'll just write the release notes myself."

Your entire team's productivity has been outsourced to infrastructure you do not control, cannot inspect, and cannot fix. You are waiting for someone else's incident to resolve so you can do your job.

Now scale that scenario up. You are not building a demo for a client. You are a hospital deploying AI-assisted diagnostic tools. You are a law firm using AI to review discovery documents for a case with a filing deadline. You are a financial institution using AI for real-time fraud detection. The service goes down, and real harm follows.

This is not a technology problem. It is an architecture problem. And architecture problems have architecture solutions.

The Resilience Pattern: Cloud-First, Local-Fallback

The solution is not to abandon cloud AI. Cloud-hosted models like Claude Opus 4.6, GPT-4o, and Gemini offer capabilities that are genuinely difficult to replicate locally. The solution is to stop treating cloud AI as a single point of failure.

As ASP.NET developers, we already understand this pattern. We do not build web applications with a single database server and no failover. We do not deploy to a single region with no disaster recovery plan. We use circuit breakers, retry policies, and graceful degradation. The same principles apply to AI integration.

Here is what the architecture looks like in practice.

The Interface

Start with an abstraction. Your application code should never call a specific AI provider directly. Instead, define a contract:

public interface IAiCompletionService
{
    Task<CompletionResult> CompleteAsync(
        CompletionRequest request,
        CancellationToken cancellationToken = default);
}

public sealed record CompletionRequest
{
    public required string Prompt { get; init; }
    public string? SystemMessage { get; init; }
    public int MaxTokens { get; init; } = 1024;
    public double Temperature { get; init; } = 0.7;
}

public sealed record CompletionResult
{
    public required string Text { get; init; }
    public required string Provider { get; init; }
    public TimeSpan Latency { get; init; }
    public bool IsFallback { get; init; }
}

This is not revolutionary software engineering. It is the same Dependency Inversion Principle you learned on day one of SOLID. But an astonishing number of codebases call the OpenAI SDK directly from their controllers. When that SDK cannot reach its server, the entire feature breaks with no alternative.

The Cloud Implementation

Your primary implementation calls your preferred cloud provider. Here is a simplified example using the Anthropic API:

public sealed class CloudAiService(
    HttpClient httpClient,
    ILogger<CloudAiService> logger) : IAiCompletionService
{
    public async Task<CompletionResult> CompleteAsync(
        CompletionRequest request,
        CancellationToken cancellationToken = default)
    {
        var stopwatch = Stopwatch.StartNew();

        var payload = new
        {
            model = "claude-sonnet-4-20250514",
            max_tokens = request.MaxTokens,
            messages = new[]
            {
                new { role = "user", content = request.Prompt }
            }
        };

        var response = await httpClient.PostAsJsonAsync(
            "https://api.anthropic.com/v1/messages",
            payload,
            cancellationToken);

        response.EnsureSuccessStatusCode();

        var result = await response.Content
            .ReadFromJsonAsync<AnthropicResponse>(cancellationToken);

        stopwatch.Stop();

        logger.LogInformation(
            "Cloud completion succeeded in {Latency}ms via {Provider}",
            stopwatch.ElapsedMilliseconds,
            "Anthropic");

        return new CompletionResult
        {
            Text = result?.Content?.FirstOrDefault()?.Text ?? "",
            Provider = "Anthropic Claude",
            Latency = stopwatch.Elapsed,
            IsFallback = false
        };
    }
}

The Local Fallback

Your fallback implementation runs entirely on-premises. In 2026, the local AI ecosystem is mature enough for this to be practical. Ollama — think of it as Docker for language models — lets you pull and run open-weight models with a single command. It exposes an OpenAI-compatible API on localhost:11434, which means your fallback implementation looks almost identical to your cloud implementation:

public sealed class LocalAiService(
    HttpClient httpClient,
    ILogger<LocalAiService> logger) : IAiCompletionService
{
    public async Task<CompletionResult> CompleteAsync(
        CompletionRequest request,
        CancellationToken cancellationToken = default)
    {
        var stopwatch = Stopwatch.StartNew();

        var payload = new
        {
            model = "llama4:8b",
            messages = new[]
            {
                new { role = "user", content = request.Prompt }
            }
        };

        var response = await httpClient.PostAsJsonAsync(
            "http://localhost:11434/v1/chat/completions",
            payload,
            cancellationToken);

        response.EnsureSuccessStatusCode();

        var result = await response.Content
            .ReadFromJsonAsync<OllamaResponse>(cancellationToken);

        stopwatch.Stop();

        logger.LogInformation(
            "Local completion succeeded in {Latency}ms via {Provider}",
            stopwatch.ElapsedMilliseconds,
            "Ollama/Llama4");

        return new CompletionResult
        {
            Text = result?.Choices?.FirstOrDefault()?.Message?.Content ?? "",
            Provider = "Local Ollama (Llama 4 8B)",
            Latency = stopwatch.Elapsed,
            IsFallback = true
        };
    }
}

The local model will not be as capable as Claude Opus or GPT-4o for complex reasoning tasks. That is fine. A less capable model that is available beats a more capable model that is not. When the cloud comes back, traffic automatically shifts to the primary provider. Your users never see an error page.

The Circuit Breaker

Now wire them together with a resilience layer. In ASP.NET, you can use Microsoft's built-in resilience libraries (formerly Polly) to create a circuit breaker that detects when the cloud provider is failing and automatically routes to the local fallback:

public sealed class ResilientAiService(
    CloudAiService cloudService,
    LocalAiService localService,
    ILogger<ResilientAiService> logger) : IAiCompletionService
{
    private readonly ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
        .AddCircuitBreaker(new CircuitBreakerStrategyOptions
        {
            FailureRatio = 0.5,
            SamplingDuration = TimeSpan.FromSeconds(30),
            MinimumThroughput = 3,
            BreakDuration = TimeSpan.FromMinutes(1)
        })
        .AddTimeout(TimeSpan.FromSeconds(30))
        .Build();

    public async Task<CompletionResult> CompleteAsync(
        CompletionRequest request,
        CancellationToken cancellationToken = default)
    {
        try
        {
            return await pipeline.ExecuteAsync(
                async ct => await cloudService.CompleteAsync(request, ct),
                cancellationToken);
        }
        catch (Exception ex) when (
            ex is BrokenCircuitException or
            TimeoutRejectedException or
            HttpRequestException)
        {
            logger.LogWarning(
                ex,
                "Cloud AI unavailable, falling back to local model");

            return await localService.CompleteAsync(request, cancellationToken);
        }
    }
}

This is the same pattern you would use for a database failover or a CDN fallback. The cloud provider is the primary. When it fails — whether due to network issues, rate limiting, or an outage — the circuit breaker opens and traffic routes to the local model. After the break duration expires, the circuit breaker lets a test request through to see if the cloud has recovered. If it has, traffic shifts back automatically.

Registration in Program.cs

Wire it all up in your ASP.NET application's dependency injection container:

// Cloud AI client
builder.Services.AddHttpClient<CloudAiService>(client =>
{
    client.DefaultRequestHeaders.Add("x-api-key", builder.Configuration["Anthropic:ApiKey"]!);
    client.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01");
});

// Local AI client (Ollama on localhost)
builder.Services.AddHttpClient<LocalAiService>(client =>
{
    client.BaseAddress = new Uri("http://localhost:11434");
});

// Register the resilient wrapper as the interface implementation
builder.Services.AddSingleton<CloudAiService>();
builder.Services.AddSingleton<LocalAiService>();
builder.Services.AddSingleton<IAiCompletionService, ResilientAiService>();

Any controller, service, or Razor component that injects IAiCompletionService now automatically gets the resilient version. They do not know or care whether the response came from Claude or from a local Llama model. They just get an answer.

Setting Up Your Local Fallback

If you have never run a local language model before, the barrier to entry is remarkably low in 2026.

Install Ollama

On Linux or macOS, it is a single command:

curl -fsSL https://ollama.com/install.sh | sh

On Windows, download the installer from ollama.com. Ollama runs as a background service and exposes its API on port 11434.

Pull a Model

Choose a model based on your hardware. For a developer workstation with 16 GB of RAM:

# General purpose — great balance of capability and speed
ollama pull llama4:8b

# Smaller and faster, good for code tasks
ollama pull qwen3:8b

# If you have 32+ GB RAM, the 70B models are impressively capable
ollama pull llama3.3:70b

The models download once and are cached locally. After the initial download, they load in seconds.

Verify It Works

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama4:8b",
    "messages": [
      {"role": "user", "content": "Write a C# record for a blog post with title, date, and tags."}
    ]
  }'

That is it. You now have a local AI endpoint that will never go down because of someone else's infrastructure problem. It will go down if your machine loses power, of course — but at that point you have bigger problems than AI availability.

Beyond AI: The Broader Cloud Dependency Problem

The toilet analogy extends beyond AI. Adobe Creative Cloud has experienced 258 incidents in the last 90 days — 89 of them classified as major outages, with a median resolution time of over two hours. On March 27, 2026 — the same day Claude was struggling with Opus 4.6 errors — Adobe Express, Photoshop, Acrobat, and several other services were simultaneously experiencing outages.

GitHub itself has had notable outages. When GitHub goes down, millions of developers cannot push code, review pull requests, or trigger CI/CD pipelines.

The pattern repeats across the industry. We have collectively moved critical workflows to cloud services — source control, CI/CD, design tools, communication, project management, AI assistance — and each one represents a potential single point of failure.

This does not mean cloud services are bad. They are extraordinarily useful. But the question every engineering team should ask is: "If this service goes down for four hours on a Friday afternoon before a Monday deadline, what is our plan?"

For many teams, the honest answer is: "We don't have one."

What ASP.NET Developers Can Do Today

Here are concrete steps you can take right now to reduce your exposure to cloud AI outages.

First, define your AI integration contract as an interface. If you are already calling the OpenAI or Anthropic SDK directly from your controllers, refactor it behind an abstraction. This takes an hour and pays dividends forever. Even if you never implement a local fallback, the interface makes it trivial to swap providers when pricing changes or a new model launches.

Second, install Ollama on your development machine. Pull a model. Run a few prompts. Get comfortable with the local inference API. The quality of open-weight models in 2026 is genuinely impressive — Llama 4, Qwen 3, DeepSeek V3, and Mistral Large 3 are all capable enough for many production tasks.

Third, add a health check for your AI dependencies. ASP.NET's health check middleware makes this straightforward:

builder.Services.AddHealthChecks()
    .AddUrlGroup(
        new Uri("https://api.anthropic.com/v1/models"),
        name: "anthropic-api",
        failureStatus: HealthStatus.Degraded)
    .AddUrlGroup(
        new Uri("http://localhost:11434/api/tags"),
        name: "ollama-local",
        failureStatus: HealthStatus.Degraded);

Now your monitoring dashboard shows you at a glance whether your primary and fallback AI providers are reachable. When the cloud provider turns red, you know your circuit breaker is routing traffic locally — and you can tell your team before they notice.

Fourth, implement the circuit breaker pattern. The code above is a starting point. In production, you will want to add metrics (how many requests are going to the fallback versus the primary?), alerts (notify the team when the circuit opens), and possibly a manual override (force-use the local model when you know the cloud is having issues but the circuit breaker has not tripped yet).

Fifth, consider what "good enough" means for your use case. Not every AI-powered feature needs the most capable model available. A local 8B parameter model is more than sufficient for code autocompletion, text summarization, data extraction, and many classification tasks. Reserve the cloud-hosted frontier models for tasks that genuinely require them: complex multi-step reasoning, long-context analysis, and creative generation. This is not just a resilience strategy — it also reduces your API costs.

The Bigger Picture

There is a philosophical dimension to this problem that goes beyond architecture patterns and circuit breakers.

When we moved from desktop software to web applications, we gained collaboration, automatic updates, and device independence. We lost the ability to work offline. When we moved from on-premises servers to the cloud, we gained elasticity, managed services, and global distribution. We lost direct control over our infrastructure.

Each transition involved a trade-off, and each time, the industry collectively decided the trade-off was worth it. But the trade-offs compound. A developer in 2026 who uses GitHub for source control, GitHub Actions for CI/CD, Vercel for hosting, Claude for coding assistance, Figma for design, Linear for project management, and Slack for communication has outsourced virtually every aspect of their workflow to services they do not control. If any one of them goes down, work slows. If two or three go down simultaneously — as happened this week — work stops.

The cloud toilet problem is not about any single service. It is about the aggregate risk of depending on many cloud services simultaneously, each with its own failure modes, each with its own incident response team, none of which you can influence.

The solution, as with plumbing, is not to reject the cloud entirely. Municipal water systems are wonderful. But you keep a few bottles of water in the pantry. You know where your shutoff valve is. You have a plunger next to the toilet.

The software equivalent is: keep your critical tools running locally. Have a fallback. Know where your shutoff valve is.

A Note on Legal and Contractual Risk

This article has focused on developer productivity, but the stakes can be much higher.

If you are building software under contract — and most of us are, whether we are consultants, agency developers, or in-house teams with SLAs — a cloud AI outage is not an excuse for a missed deadline. Your client does not care that Claude was down. Your client cares that the deliverable was due on Friday and it is not done.

Courts have not yet established clear precedent on whether a cloud service outage constitutes force majeure for downstream obligations. If your contract says you will deliver a working system by March 31 and your AI toolchain goes down on March 28, the legal question of who bears the risk is unsettled at best.

The prudent approach is to treat cloud AI the same way you treat any other external dependency: plan for it to fail. If your delivery timeline depends on a service with 99.5% uptime — which is roughly what most cloud AI providers achieve — that means you will experience roughly 44 hours of downtime per year. Almost two full days. Can your project schedule absorb that?

Open-Weight Models: Your Insurance Policy

The state of open-weight models in 2026 deserves its own discussion because it directly affects the viability of local fallbacks.

Meta's Llama 4 family includes an 8B parameter model that runs comfortably on a laptop with 16 GB of RAM. For code generation, instruction following, and general-purpose chat, it is shockingly good. It will not match Claude Opus on complex reasoning tasks, but for 90% of the prompts a working developer sends on an average day — "refactor this method," "write a unit test for this class," "explain this error message" — it is entirely adequate.

Qwen 3 from Alibaba includes specialized coding variants that rival much larger models on programming benchmarks. DeepSeek V3 excels at mathematical reasoning. Mistral Large 3 handles multilingual tasks well. OpenAI itself released gpt-oss, its first open-weight models since GPT-2, with a 120B parameter version that runs on a single 80 GB GPU.

The point is that "local AI" no longer means "toy AI." The gap between cloud-hosted frontier models and locally-runnable open-weight models has narrowed dramatically. For many practical tasks, the local model is good enough — and "good enough and available" always beats "excellent and unavailable."

Conclusion: Keep a Toilet at Home

The cloud is not going away, and it should not. Managed services are one of the great productivity multipliers of modern software development. But we have overcorrected. We have outsourced so much to the cloud that many of us literally cannot do our jobs when the cloud has a bad day.

The fix is not complicated. It is the same engineering discipline we apply to every other part of our systems: assume failure, build fallbacks, degrade gracefully.

Define your AI contracts as interfaces. Implement a cloud-primary, local-fallback architecture. Use circuit breakers to route traffic automatically. Install Ollama and pull a model. Test your fallback regularly.

And for everything that truly matters — keep a toilet at home.

Picture this. It is a Thursday afternoon. Your team has been shipping features at a pace that would have been unimaginable two years ago. The sprint review is tomorrow. CI is green. Code coverage is at 82 percent. Static analysis is clean. The tech lead has signed off on every pull request. Life is good.

Then the QA engineer sits down with the staging build, clicks four buttons in a specific sequence with roughly the right timing, and the application throws an unhandled exception. Every single time. Not a flaky test. Not a cosmic ray. A reproducible, deterministic crash that has been lurking in the codebase since Tuesday's merge.

Should this have been caught before a single line of code was written? Absolutely. Should the requirements document have specified the interaction between those four UI elements? Without question. Should a unit test have caught it? An integration test? An end-to-end test? A code review? Maybe — but none of them did. The only thing that caught it was a human being who thought like a user, explored the application like a user, and broke it like a user. That human being was a QA engineer.

This is not a hypothetical. Scenarios like this happen every week in teams across the industry, including ours. And as we barrel headlong into a world where AI generates an ever-growing share of our code, these scenarios are not becoming less common. They are becoming more common. The question is no longer whether your team needs QA. The question is whether your team can survive without it.

Part 1: The Utopian Vision (and Why It Falls Apart)

There is a beautiful vision of software development that has circulated through conference talks and management consulting decks for the better part of two decades. It goes something like this: if wishes were fishes, QA engineers would not need to exist as a separate discipline. Every team would be truly cross-functional. Every developer would write perfect tests. Every product manager would produce requirements so precise that ambiguity would be impossible. Every team member could do any work that might be needed, and anyone could take time off at any moment because the team has full coverage. The world would be a beautiful place.

This vision is not entirely wrong. Cross-functional teams are genuinely better than siloed ones. Developers who write tests produce better code than developers who do not. Shift-left testing — catching bugs earlier in the development lifecycle — is a real and valuable practice. These ideas have merit, and the best teams in the world incorporate all of them.

But the vision falls apart when it collides with reality. Here is why.

Human Cognition Has Limits

When a developer writes a feature and then writes the tests for that feature, they are testing their own mental model of how the feature works. This is valuable, but it is inherently limited. The developer knows what the code is supposed to do, and they write tests that verify the code does what they intended. What they rarely test is the space between their intention and the user's expectation.

This is not a character flaw. It is a well-documented cognitive bias called the "curse of knowledge." Once you know how something works internally, it becomes genuinely difficult to imagine how someone who does not know would interact with it. A QA engineer who did not write the code approaches the feature with fresh eyes, different assumptions, and — critically — a different mental model. They think about what happens when the user double-clicks instead of single-clicks. They think about what happens when the user navigates backward. They think about what happens when the user leaves the page open for 45 minutes and then tries to submit a form.

Cross-Functional Does Not Mean Interchangeable

The Agile manifesto encourages cross-functional teams, but cross-functional does not mean every person does every job. A cross-functional team has all the skills needed to deliver a feature. That includes development, design, testing, operations, and domain expertise. The idea that a developer can simply "also do QA" is as reductive as saying a QA engineer can "also write the backend." People have specializations for a reason. A senior QA engineer has spent years developing an intuition for where bugs hide, what edge cases matter, and how users actually behave. That intuition is not something you acquire by adding a few test cases to your pull request.

Coverage Numbers Lie

Here is a dirty secret about test coverage: 100 percent code coverage does not mean your application works. It means every line of code was executed during a test. It says nothing about whether the right assertions were made, whether the test inputs were meaningful, or whether the interactions between components were exercised. You can have 100 percent line coverage and still have a race condition that only manifests when two specific API calls arrive within three milliseconds of each other.

Consider this seemingly innocent ASP.NET controller action:

[HttpPost("transfer")]
public async Task<IActionResult> TransferFunds(TransferRequest request)
{
    var sourceAccount = await _db.Accounts
        .FirstOrDefaultAsync(a => a.Id == request.SourceAccountId);

    if (sourceAccount is null)
        return NotFound("Source account not found");

    if (sourceAccount.Balance < request.Amount)
        return BadRequest("Insufficient funds");

    var destinationAccount = await _db.Accounts
        .FirstOrDefaultAsync(a => a.Id == request.DestinationAccountId);

    if (destinationAccount is null)
        return NotFound("Destination account not found");

    sourceAccount.Balance -= request.Amount;
    destinationAccount.Balance += request.Amount;

    await _db.SaveChangesAsync();
    return Ok();
}

This code will pass every unit test you throw at it. It reads cleanly. It handles nulls. It validates the balance. A code reviewer would likely approve it without comment. But it has a race condition hiding in plain sight. If two concurrent requests arrive to transfer funds from the same account, both requests can read the balance before either has decremented it, and the account ends up in an inconsistent state. The balance check passes for both requests, but the account is debited twice, potentially going negative.

A unit test will never catch this because unit tests run sequentially. An integration test might not catch it because reproducing the timing is difficult in an automated test. But a QA engineer who has seen this pattern before, who knows to open two browser tabs and click "Submit" in rapid succession? They will find it in minutes.

Part 2: The AI Amplification Effect

If the case for QA was strong before the AI revolution, it has become overwhelming since. The numbers are staggering.

The Output Explosion

AI coding tools have fundamentally changed the volume, velocity, and risk profile of code entering the pipeline. The average developer now submits approximately 7,800 lines of code per month, up from roughly 4,450, representing a 76 percent increase in output per person. For mid-size teams, the increase is even more dramatic. Pull requests per author have risen significantly, while review capacity has not scaled to match.

This is not a criticism of AI tools. They are genuinely useful. They help developers write boilerplate faster, explore unfamiliar APIs, and prototype ideas quickly. But every line of AI-generated code is a line that needs to be tested, reviewed, and understood. And the evidence suggests that the testing capacity of most organizations has not kept pace with the output increase.

Failure Rates Are Climbing

Incidents per pull request have increased by 23.5 percent, and change failure rates have risen roughly 30 percent. This is the predictable consequence of producing more code without proportionally increasing the investment in verification. The bottleneck has shifted. It is no longer creation — it is verification.

AI Code Has a Specific Bug Profile

AI-generated code tends to produce a particular category of bugs that are difficult for automated tests to catch. These bugs arise because large language models optimize for plausibility, not correctness. The code looks right. It follows patterns the model has seen in training data. It compiles. It passes lint. But it may contain subtle logical errors, incorrect assumptions about API behavior, or security vulnerabilities that only surface under specific conditions.

AI-produced code can hide subtle performance bugs, security gaps, or odd logic patterns that only surface under real pressure. Some QA teams have responded by creating specialized checklists for reviewing AI-generated code — things to look for when the code was written by a model rather than a person.

Consider a real-world scenario. A developer asks an AI tool to generate a caching layer for an ASP.NET application. The AI produces something like this:

public class UserCacheService
{
    private static readonly Dictionary<int, UserDto> _cache = new();
    private readonly IUserRepository _repository;

    public UserCacheService(IUserRepository repository)
    {
        _repository = repository;
    }

    public async Task<UserDto> GetUserAsync(int userId)
    {
        if (_cache.TryGetValue(userId, out var cached))
            return cached;

        var user = await _repository.GetByIdAsync(userId);
        if (user is not null)
            _cache[userId] = user;

        return user;
    }
}

This code looks perfectly reasonable. It compiles. It has clear intent. A quick code review might approve it. But it has at least three problems that a QA engineer would eventually surface:

1. The Dictionary<int, UserDto> is not thread-safe. In an ASP.NET application where multiple requests hit this service concurrently, you will get corrupted state, lost updates, or InvalidOperationException from concurrent enumeration. The fix is ConcurrentDictionary<int, UserDto>.

2. The cache never expires. Once a user is loaded, the cached version is served forever, even if the underlying data changes. In a long-running application, this leads to stale data bugs that are maddening to diagnose.

3. When the cache misses, there is no protection against the thundering herd problem. If a hundred requests arrive simultaneously for the same uncached user, all hundred will hit the database. The fix is to use SemaphoreSlim or a library like LazyCache that provides lock-per-key semantics.

None of these bugs will appear in a unit test that exercises the method once with a single thread. They appear when a QA engineer puts the application under realistic load, navigates aggressively, and watches for inconsistencies over time.

Part 3: The Testing Pyramid Is Necessary but Not Sufficient

Every developer is taught the testing pyramid early in their career. Unit tests at the base. Integration tests in the middle. End-to-end tests at the top. More of the cheap, fast tests. Fewer of the expensive, slow ones. It is a useful mental model, and teams that follow it are better off than teams that do not.

But the pyramid has a blind spot: it assumes that the thing being tested is well-specified to begin with. If the requirements are ambiguous, the unit tests will faithfully verify the wrong behavior. If the interaction between two components was never documented, no integration test will cover it. If the user experience depends on timing, animation state, or the order of asynchronous operations, end-to-end tests may not be deterministic enough to catch the problem.

Unit Tests: The Foundation

Unit tests are the bedrock of any quality strategy. In a .NET project, they are fast, isolated, and give you immediate feedback when a method's contract changes. Here is a typical example from our own codebase:

[Fact]
public void FrontMatter_ParsesAllFields()
{
    var markdown = """
        ---
        title: Test Post
        date: 2026-03-01
        author: observer-team
        summary: A test summary
        tags:
          - test
          - integration
        featured: true
        series: Test Series
        image: /images/test.jpg
        ---
        ## Hello

        This is the body.
        """;

    var (frontMatter, body) = ParseFrontMatter(markdown);

    Assert.Equal("Test Post", frontMatter.Title);
    Assert.Equal(new DateTime(2026, 3, 1), frontMatter.Date);
    Assert.Equal("observer-team", frontMatter.Author);
    Assert.Equal("A test summary", frontMatter.Summary);
    Assert.Equal(["test", "integration"], frontMatter.Tags);
    Assert.True(frontMatter.Featured);
    Assert.Contains("## Hello", body);
}

This test is valuable. It verifies that the YAML front matter parser correctly extracts all fields from a well-formed markdown file. It runs in milliseconds and catches regressions instantly. But it tests the happy path with valid input. What happens when the front matter is malformed? When the date is in an unexpected format? When a field contains Unicode characters? When the YAML indentation is inconsistent? Each of these is a separate test case that someone needs to think of. The developer who wrote the parser thought of some of them. The QA engineer who tests the blog pipeline will think of others.

Integration Tests: Verifying the Seams

Integration tests verify that components work together correctly. They are more expensive to write and maintain, but they catch a different category of bugs — the ones that live in the seams between components.

[Fact]
public void Rss_ContainsCategoriesFromTags()
{
    var posts = new[]
    {
        new RssPostEntry
        {
            Slug = "test",
            Title = "Test",
            Date = DateTime.UtcNow,
            Summary = "Summary",
            Tags = ["alpha", "beta"]
        }
    };

    var rssXml = GenerateRss("Test Blog", "Desc", "https://example.com", posts);

    var doc = XDocument.Parse(rssXml);
    var categories = doc.Descendants("item")
        .First()
        .Elements("category")
        .Select(c => c.Value)
        .ToArray();

    Assert.Equal(["alpha", "beta"], categories);
}

This test verifies that the RSS generator correctly maps post tags to RSS category elements. It exercises the full RSS generation pipeline, including XML serialization. But it still operates on controlled data. It does not test what happens when the RSS feed is consumed by an actual RSS reader, or when the feed contains a post with a title that includes an ampersand, or when the feed is fetched over HTTP with gzip compression.

End-to-End Tests: Simulating the User

End-to-end tests simulate real user interactions. In the Blazor WebAssembly world, tools like bUnit let you render components and assert on the resulting HTML:

[Fact]
public void BlogPage_RendersPostList()
{
    // Arrange - register services, configure HttpClient mock
    // Act - render the Blog component
    // Assert - verify the correct post titles appear in the DOM
}

These tests are valuable for verifying that components render correctly and respond to user interaction. But they still operate within the test harness. They do not exercise the full download-parse-render cycle of a Blazor WebAssembly application in a real browser. They do not account for network latency, browser differences, viewport sizes, or the fact that users sometimes click faster than the framework can handle.

The Missing Layer: Exploratory Testing

This is where dedicated QA shines. Exploratory testing is not random clicking. It is a disciplined practice where a tester simultaneously learns about the application, designs tests, and executes them. It is guided by experience, intuition, and a mental model of where bugs tend to hide.

An experienced QA engineer testing a new blog feature might:

• Try to publish a post with a future date and verify it does not appear
• Create a post with a title that is 500 characters long
• Paste formatted text from Microsoft Word into the markdown editor
• Navigate to a blog post, hit the back button, and verify the blog index state is preserved
• Open the same blog post in two tabs and check for inconsistencies
• Test on a slow network connection to see how the loading state behaves
• Rapidly switch between themes while a blog post is loading
• Try to access a blog post URL that does not exist
• Submit a form with JavaScript disabled
• Test keyboard navigation for accessibility compliance

No automated test suite would cover all of these scenarios unless someone first thought to write them. And the person most likely to think of them is the person whose entire job is thinking about how software can break.

Part 4: Concurrency Bugs — The QA Engineer's Specialty

Concurrency bugs deserve their own section because they represent the quintessential category of defect that automated tests miss and QA engineers find. They are the most insidious bugs in web development, and modern ASP.NET applications are especially vulnerable to them because of the inherent concurrency of HTTP request processing.

Why Concurrency Bugs Are Hard

Concurrency bugs are non-deterministic. They depend on the timing of thread execution, which is controlled by the operating system scheduler — not by your code. A race condition might manifest once in a thousand requests, or only under specific load conditions, or only when the garbage collector happens to pause a thread at exactly the wrong moment.

This non-determinism makes them nearly impossible to reproduce in a development environment where you are the only user. They pass all unit tests because unit tests run sequentially. They often pass integration tests because the test environment has less contention than production. They surface in staging or production when real users generate real concurrent load.

A Catalog of Common ASP.NET Concurrency Bugs

Here are patterns that QA engineers should know about and actively test for.

The Double-Submit Problem. A user clicks the "Submit" button twice in quick succession. If the server does not implement idempotency, two records are created. This is especially dangerous for financial transactions, order placements, and any operation with real-world side effects. The fix involves a combination of client-side button disabling, server-side idempotency keys, and database-level unique constraints.

// Vulnerable: no idempotency protection
[HttpPost("orders")]
public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
{
    var order = new Order
    {
        CustomerId = request.CustomerId,
        Items = request.Items,
        CreatedAt = DateTime.UtcNow
    };
    _db.Orders.Add(order);
    await _db.SaveChangesAsync();
    return Created($"/orders/{order.Id}", order);
}

// Fixed: idempotency key prevents duplicate creation
[HttpPost("orders")]
public async Task<IActionResult> CreateOrder(
    [FromHeader(Name = "Idempotency-Key")] string idempotencyKey,
    CreateOrderRequest request)
{
    var existing = await _db.Orders
        .FirstOrDefaultAsync(o => o.IdempotencyKey == idempotencyKey);

    if (existing is not null)
        return Ok(existing); // Return the existing order, not a duplicate

    var order = new Order
    {
        IdempotencyKey = idempotencyKey,
        CustomerId = request.CustomerId,
        Items = request.Items,
        CreatedAt = DateTime.UtcNow
    };

    _db.Orders.Add(order);
    await _db.SaveChangesAsync();
    return Created($"/orders/{order.Id}", order);
}

The Read-Modify-Write Race. This is the fund transfer example from earlier. Whenever your code reads a value, makes a decision based on that value, and then writes an updated value back, there is a window between the read and the write where another thread can change the data. In Entity Framework, the fix is optimistic concurrency control using a row version column:

public class Account
{
    public int Id { get; set; }
    public decimal Balance { get; set; }

    [Timestamp]
    public byte[] RowVersion { get; set; } = [];
}

With this in place, if two concurrent requests try to update the same account, one of them will get a DbUpdateConcurrencyException, which you can catch and retry or report to the user. The important thing is that the data stays consistent.

The Stale Cache Thundering Herd. When a cache entry expires and many concurrent requests arrive for the same data simultaneously, all of them miss the cache and hit the underlying data source at once. This can bring down a database or overwhelm an external API. The fix is to use a cache implementation that supports lock-per-key, so only one thread refreshes the cache while others wait for the result.

The Shared Mutable State. Any static field or singleton-scoped service that holds mutable state is a concurrency bug waiting to happen. In ASP.NET's dependency injection system, services registered as Singleton persist for the lifetime of the application and are shared across all requests. If those services hold mutable state without synchronization, you have a race condition.

// Dangerous: static mutable state with no synchronization
public class RequestCounter
{
    private static int _count = 0;

    public int Increment() => _count++; // Not thread-safe!
}

// Fixed: use Interlocked for atomic operations
public class RequestCounter
{
    private static int _count = 0;

    public int Increment() => Interlocked.Increment(ref _count);
}

How QA Engineers Find Concurrency Bugs

QA engineers find concurrency bugs through a combination of techniques:

1. Rapid interaction testing. Double-clicking buttons, rapidly navigating between pages, submitting forms multiple times, and using the browser's back and forward buttons aggressively.

2. Multi-tab and multi-browser testing. Opening the same application in multiple tabs or browsers and performing conflicting operations simultaneously. This is the simplest way to simulate concurrent users.

3. Slow network simulation. Using browser developer tools to throttle the network connection, which widens the timing windows where race conditions can occur.

4. Load testing. Using tools like k6, JMeter, or NBomber to simulate realistic concurrent load. This is where race conditions that only appear under contention become visible.

5. State inspection. Checking database records, cache entries, and log files after performing concurrent operations to verify that the data is consistent.

6. Session testing. Logging in as two different users and performing operations that interact with the same data, verifying that one user's actions do not corrupt another user's experience.

Part 5: The Economics of Quality

There is a widely cited claim, often attributed to IBM's Systems Sciences Institute, that a bug found in production is 100 times more expensive to fix than one found during the design phase. The original source of this specific figure has been questioned — researchers have noted that the underlying data may trace back to internal IBM training materials from the early 1980s, and the exact multiplier has never been independently verified.

But even if the precise number is debatable, the directional truth is not. Bugs found later in the development lifecycle are more expensive to fix. This is true for straightforward reasons that do not require an academic study to understand:

• A bug found during code review requires the developer to fix the code. Cost: minutes to hours.
• A bug found during QA testing requires a bug report, a context switch for the developer, a fix, a re-test, and possibly a new build. Cost: hours to a day.
• A bug found in production requires all of the above plus incident response, customer communication, possible data remediation, hotfix deployment, and post-incident review. Cost: days to weeks, plus reputational damage that is difficult to quantify.

The Consortium for Information and Software Quality (CISQ) estimated in their 2022 report that the cost of poor software quality in the United States has reached approximately $2.41 trillion. That figure includes operational failures, software vulnerabilities, technical debt, and the direct cost of defects. Even if you discount the number heavily, the scale is sobering.

The QA Return on Investment

A dedicated QA engineer's salary is a known, fixed cost. The cost of the bugs they prevent is variable but potentially enormous. Consider:

• A single production outage at a mid-size company can cost tens of thousands of dollars per hour in lost revenue and customer goodwill.
• A security vulnerability that leads to a data breach can cost millions in fines, remediation, and legal fees.
• A series of small, annoying bugs that erode user trust can lead to churn that compounds over months, resulting in losses that dwarf the cost of a QA team.

The math is not complicated. If a QA engineer prevents even one significant production incident per quarter, they have almost certainly paid for themselves. If they catch a security vulnerability before it ships, they have paid for themselves many times over.

AI Testing Tools Are Helpful but Not Sufficient

There is a growing ecosystem of AI-powered testing tools that can generate test cases, detect flaky tests, self-heal broken selectors, and prioritize test execution based on risk. These tools are genuinely useful, and teams should evaluate and adopt them where they add value.

But AI testing tools have the same fundamental limitation as AI coding tools: they optimize for patterns they have seen before. They are excellent at generating variations of known test scenarios. They are poor at imagining entirely new categories of failure. They cannot think about whether the user experience "feels right." They cannot notice that the loading spinner disappears 200 milliseconds before the content appears, creating a disconcerting flash. They cannot tell you that the error message is technically accurate but emotionally tone-deaf.

In a survey of experienced testing professionals, 67 percent said they would trust AI-generated tests, but only with human review. That finding captures the state of the industry perfectly: AI is a powerful tool for QA, but it is not a replacement for QA.

Part 6: Practical Recommendations for ASP.NET Teams

If you are convinced that QA matters — and if the preceding five thousand words have not convinced you, the next production outage probably will — here are concrete steps you can take to strengthen quality assurance in your ASP.NET projects.

1. Embed QA in the Development Process, Not After It

The worst QA setup is the one where developers write code for two weeks, throw it over the wall to QA, and QA files a hundred bugs. This leads to a combative relationship where developers resent QA for slowing them down and QA resents developers for producing sloppy work.

Instead, involve QA from the beginning. Have QA engineers participate in sprint planning and review the requirements before any code is written. They will spot ambiguities, missing edge cases, and contradictory requirements that developers will not catch because developers are thinking about implementation, not usage.

2. Automate the Boring Parts

There are categories of testing that machines do better than humans: regression testing, performance testing, accessibility scanning, security scanning, and API contract verification. Automate these aggressively. Use tools like:

• xUnit and bUnit for unit and component tests in your .NET projects
• NBomber or k6 for load testing
• Playwright or Selenium for browser-based end-to-end tests
• OWASP ZAP for security scanning
• axe-core or Lighthouse for accessibility auditing
• Pact or contract testing libraries for verifying API compatibility

Automation frees your QA engineers to do what humans do best: think creatively about how the software can break.

3. Write Tests at Every Level

In the .NET ecosystem, a healthy test suite includes:

Unit tests that verify individual methods and classes in isolation. Register services with mock dependencies and assert on return values and state changes.

Component tests with bUnit that render Blazor components and verify the DOM output, event handling, and component lifecycle.

[Fact]
public void Counter_IncrementButton_UpdatesCount()
{
    using var ctx = new BunitContext();
    var cut = ctx.Render<Counter>();

    cut.Find("button").Click();

    cut.Find("p").TextContent.MarkupMatches("Current count: 1");
}

Integration tests that verify the content processing pipeline, RSS generation, database queries, and API endpoints.

End-to-end tests that exercise the deployed application in a real browser, verifying navigation, routing, and full-page rendering.

4. Make Tests Fast and Reliable

Tests that take minutes to run get run less often. Tests that are flaky get ignored. Both outcomes are worse than having no tests at all, because they give you false confidence.

In our Observer Magazine project, the entire test suite runs in under ten seconds:

dotnet test

This is fast enough to run after every change. If your test suite takes longer than 30 seconds, invest in making it faster. Parallelize test execution. Replace slow database tests with in-memory alternatives. Split tests into "fast" and "slow" categories and run the fast ones on every commit, the slow ones on every merge to main.

5. Implement Concurrency Testing as a First-Class Practice

Do not wait for concurrency bugs to find you. Actively hunt them.

Write tests that exercise concurrent scenarios:

[Fact]
public async Task ConcurrentTransfers_DoNotCorruptBalance()
{
    // Arrange: create an account with $1000
    var account = new Account { Balance = 1000m };
    await _db.Accounts.AddAsync(account);
    await _db.SaveChangesAsync();

    // Act: attempt 100 concurrent $10 transfers
    var tasks = Enumerable.Range(0, 100)
        .Select(_ => TransferAsync(account.Id, 10m));

    await Task.WhenAll(tasks);

    // Assert: balance should never go negative
    await _db.Entry(account).ReloadAsync();
    Assert.True(account.Balance >= 0);
}

This kind of test will not catch every race condition — the timing is still somewhat controlled — but it catches many of them and serves as a regression guard once a concurrency bug is fixed.

6. Use OpenTelemetry to Make Bugs Visible

Structured logging and distributed tracing make bugs easier to find and faster to diagnose. In a .NET application, OpenTelemetry integration gives you visibility into request timing, exception rates, and dependency failures.

When a QA engineer reports a bug, having detailed traces and structured logs means the developer can reproduce the conditions precisely rather than guessing. This reduces the back-and-forth between QA and development and shortens the fix cycle.

7. Test the Unhappy Paths

It is human nature to test that the software works when used correctly. The most valuable testing verifies what happens when it is used incorrectly. Every API endpoint should be tested with:

• Missing required fields
• Fields with the wrong data type
• Fields with boundary values (zero, negative, maximum integer, empty string, very long strings)
• Malformed JSON
• Missing or expired authentication tokens
• Requests that exceed rate limits
• Concurrent requests that create conflicting state

8. Create a Bug Taxonomy

Track not just the bugs you find, but the categories they fall into. Over time, you will discover patterns. Maybe your team consistently introduces concurrency bugs in services that use caching. Maybe your API validation is always missing edge cases for date fields. Maybe your Blazor components break when the user navigates away during an async operation.

Once you know the patterns, you can create targeted checklists, automated checks, and training materials that prevent the same categories of bugs from recurring. This is how QA transforms from a reactive function (finding bugs) to a proactive one (preventing bugs).

Part 7: The Human Element

There is one more dimension to QA that is rarely discussed in technical articles, and it may be the most important one: QA engineers represent the user's voice inside the development team.

Developers are incentivized to ship features. Product managers are incentivized to hit deadlines. Designers are incentivized to create beautiful interfaces. QA engineers are the only team members whose primary incentive is to make sure the software actually works for the person using it. They are the user's advocate, the skeptic in the room, the person who asks "what happens if..." when everyone else is celebrating a green build.

This advocacy role extends beyond bug finding. A good QA engineer will:

• Push back on unrealistic timelines that leave no room for testing
• Flag when requirements are ambiguous and likely to produce bugs
• Advocate for accessibility and internationalization
• Insist on testing with realistic data, not just the three sample records in the dev database
• Remind the team that "works on my machine" is not the same as "works"

In an era where AI can generate code faster than humans can review it, where pull request volume is skyrocketing, and where the pressure to ship quickly has never been more intense, this advocacy role is not just nice to have. It is essential.

Part 8: QA in the Age of AI — A Practical Framework

The relationship between AI and QA is not adversarial. The teams that will thrive are those that use AI tools to augment their QA process, not replace it. Here is a practical framework.

Let AI Generate, Let Humans Verify

Use AI tools to generate initial test cases from requirements. Have QA engineers review, refine, and augment those test cases with edge cases and scenarios that the AI missed. This is faster than writing every test from scratch and more reliable than trusting AI-generated tests blindly.

Use AI for Regression, Humans for Exploration

Automated regression suites — whether AI-generated or hand-written — are excellent at verifying that existing functionality still works. They are poor at discovering new categories of bugs. Reserve human QA effort for exploratory testing, usability testing, and testing new features where the bug landscape is unknown.

Monitor AI-Generated Code More Closely

Some QA teams are creating specialized checklists for reviewing code written by AI models rather than people, since AI-produced code can contain subtle patterns that differ from human-written code. This is a good practice. AI-generated code tends to have specific failure modes: incorrect error handling, missing edge cases, naive concurrency assumptions, and over-reliance on patterns that were common in training data but are not appropriate for the current context.

Invest in QA Tooling, Not Just Developer Tooling

Fifty percent of organizations struggle to fund the automation tools they already need for QA, even as budgets flow overwhelmingly toward developer productivity tools and AI infrastructure. This imbalance is dangerous. If you are investing in tools that help developers produce code faster, you must also invest in tools that help QA verify that code faster. Otherwise, you are building a pipeline that generates bugs more efficiently.

Conclusion: Slow Down to Speed Up

There is a paradox at the heart of software quality: slowing down to test thoroughly actually speeds up delivery over time. Teams that skip QA ship faster in the short term but spend more time on bug fixes, hotfixes, incident response, and customer support in the long term. Teams that invest in QA ship slightly slower in the short term but spend less time on rework, enjoy higher customer satisfaction, and build a codebase that is easier to extend and maintain.

This paradox becomes even more pronounced in the age of AI-generated code. When code is being produced at 76 percent higher volume, when change failure rates are climbing by 30 percent, and when the code itself is generated by models that optimize for plausibility rather than correctness, the need for human verification has never been greater.

The four clicks that brought down our staging environment were not a failure of our test suite. They were not a failure of our code review process. They were not a failure of our CI pipeline. They were a reminder that software is used by human beings who do unpredictable things, and the best way to catch unpredictable bugs is to have a human being whose job is to think unpredictably.

QA is not a luxury. It is not a line item to cut when budgets are tight. It is not a phase you can skip when the deadline is approaching. In a world where AI can write code faster than humans can read it, QA is the last line of defense between your users and an avalanche of untested code.

Invest in it. Respect it. And whatever you do, do not ship without it.

If you are a .NET developer who has spent most of your career working with SQL Server on Windows, PostgreSQL can feel like a different world. The terminology is different, the tooling is different, the configuration is different, and even the philosophical approach to certain problems diverges significantly from what you are used to. This guide is written to bridge that gap completely.

We are going to cover everything. Not some things. Everything. From installing PostgreSQL on bare metal Linux, a VPS, or a Docker/Podman container, to configuring it for development and production, to writing queries in the terminal, to connecting from .NET using Npgsql with both Dapper and Entity Framework Core, to understanding transactions, isolation levels, locking, connection pooling, session management, networking, debugging, and monitoring. We will also survey every free and open-source IDE and GUI tool available on Linux for working with PostgreSQL.

This article assumes you are running Linux (Fedora, Ubuntu, Debian, Arch, or a similar distribution). It assumes you know C# and have worked with ASP.NET. It does not assume any prior PostgreSQL experience.

Let us begin.

Part 1: What Is PostgreSQL and Why Should You Care?

PostgreSQL is a free, open-source, object-relational database management system. It has been under active development since 1986, originating from the POSTGRES project at the University of California, Berkeley. The "SQL" was appended to the name in 1996 when SQL language support was added, and the project has been community-driven ever since.

PostgreSQL is not owned by any corporation. There is no "PostgreSQL Inc." that controls the project. It is developed by a global community of contributors under the PostgreSQL Global Development Group. The license is the PostgreSQL License, which is a permissive open-source license similar to BSD and MIT. You can use PostgreSQL for any purpose, including commercial, without paying anyone anything, ever. There are no "community editions" versus "enterprise editions." There is one PostgreSQL, and it is free.

As of early 2026, PostgreSQL has surpassed MySQL as the most widely used database among developers, with roughly 55% usage in developer surveys. Every major cloud provider offers managed PostgreSQL services: Amazon RDS and Aurora PostgreSQL, Azure Database for PostgreSQL, Google Cloud SQL for PostgreSQL, and many others. But you do not need to use any cloud service. PostgreSQL runs perfectly well on a single Linux machine, a Raspberry Pi, or a $5/month VPS.

For .NET developers specifically, PostgreSQL is compelling because the .NET ecosystem has first-class support for it through Npgsql, the open-source ADO.NET data provider. Npgsql consistently ranks among the top performers on the TechEmpower Web Framework Benchmarks. Entity Framework Core has an official PostgreSQL provider maintained by the Npgsql team. Dapper works flawlessly with Npgsql. There is no technical reason to avoid PostgreSQL in a .NET application.

PostgreSQL vs. SQL Server: Key Philosophical Differences

Before we dive into specifics, you need to understand a few philosophical differences between PostgreSQL and SQL Server:

PostgreSQL uses Multi-Version Concurrency Control (MVCC) as its fundamental concurrency mechanism. Every transaction sees a snapshot of the data as it existed at the start of the transaction. Readers never block writers, and writers never block readers. This is fundamentally different from SQL Server's default behavior, where readers acquire shared locks that can block writers. SQL Server added MVCC-like behavior later through Read Committed Snapshot Isolation (RCSI) and Snapshot Isolation, but these are opt-in features. In PostgreSQL, MVCC is the default and only model.

PostgreSQL does not have a concept equivalent to SQL Server's NOLOCK hint, and you should not miss it. The entire NOLOCK pattern exists in SQL Server because its default isolation level (Read Committed with locking) causes readers to block writers. Since PostgreSQL uses MVCC by default, readers never block writers, so the problem NOLOCK solves simply does not exist. We will discuss this in much more detail in the transactions section.

PostgreSQL is case-sensitive for identifiers by default, but it lowercases unquoted identifiers. If you write CREATE TABLE MyTable, PostgreSQL stores it as mytable. If you want mixed-case identifiers, you must double-quote them: CREATE TABLE "MyTable". The strong convention in the PostgreSQL world is to use snake_case for everything: table names, column names, function names. Embrace this convention.

PostgreSQL uses schemas differently than SQL Server. In SQL Server, dbo is the default schema and many teams barely think about schemas. In PostgreSQL, public is the default schema, but the schema system is powerful and you should use it to organize your database objects.

Part 2: Installing PostgreSQL on Linux

Bare Metal / VPS Installation

On Fedora or RHEL-based systems:

# Install PostgreSQL 18 (latest stable as of March 2026)
sudo dnf install postgresql18-server postgresql18

# Initialize the database cluster
sudo postgresql-18-setup --initdb

# Start and enable the service
sudo systemctl start postgresql-18
sudo systemctl enable postgresql-18

On Ubuntu or Debian-based systems:

# Add the official PostgreSQL APT repository
sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update

# Install PostgreSQL 18
sudo apt-get install postgresql-18

# The service starts automatically on Debian/Ubuntu
sudo systemctl status postgresql

On Arch Linux:

sudo pacman -S postgresql

# Initialize the data directory
sudo -u postgres initdb -D /var/lib/postgres/data

# Start and enable
sudo systemctl start postgresql
sudo systemctl enable postgresql

After installation, PostgreSQL creates a system user called postgres. This user is the default superuser. To connect for the first time:

# Switch to the postgres user
sudo -u postgres psql

# You are now in the psql shell as the superuser
# Create a database and user for your application
CREATE USER myapp WITH PASSWORD 'my-secure-password';
CREATE DATABASE myappdb OWNER myapp;

# Grant connect privilege
GRANT CONNECT ON DATABASE myappdb TO myapp;

# Exit
\q

Docker Installation

Docker is the quickest way to get PostgreSQL running for development:

# Pull the official PostgreSQL 18 image
docker pull postgres:18

# Run a container
docker run -d \
  --name pg-dev \
  -e POSTGRES_USER=myapp \
  -e POSTGRES_PASSWORD=my-secure-password \
  -e POSTGRES_DB=myappdb \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  postgres:18

# Connect using psql from the host
psql -h localhost -U myapp -d myappdb

# Or connect from inside the container
docker exec -it pg-dev psql -U myapp -d myappdb

The -v pgdata:/var/lib/postgresql/data flag creates a named Docker volume so your data persists across container restarts and removals. Without it, you lose all data when the container is removed.

Podman Installation

Podman is a daemonless container engine that is often preferred on Fedora and RHEL systems. It is a drop-in replacement for Docker:

# Pull and run (identical syntax to Docker)
podman run -d \
  --name pg-dev \
  -e POSTGRES_USER=myapp \
  -e POSTGRES_PASSWORD=my-secure-password \
  -e POSTGRES_DB=myappdb \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  docker.io/library/postgres:18

# Connect
podman exec -it pg-dev psql -U myapp -d myappdb

If you want to run PostgreSQL as a rootless Podman container that starts on boot:

# Generate a systemd user service
podman generate systemd --name pg-dev --files --new
mkdir -p ~/.config/systemd/user/
mv container-pg-dev.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable container-pg-dev.service
systemctl --user start container-pg-dev.service

# Enable lingering so it starts on boot even without login
loginctl enable-linger $USER

Docker Compose for Development

For a more complete development setup, use a docker-compose.yml:

services:
  db:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: my-secure-password
      POSTGRES_DB: myappdb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myappdb"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

Any .sql or .sh files placed in /docker-entrypoint-initdb.d/ inside the container are executed when the database is initialized for the first time.

Part 3: Configuring PostgreSQL

PostgreSQL's configuration lives in two primary files: postgresql.conf and pg_hba.conf. Understanding both is essential.

Finding the Configuration Files

-- Inside psql, find the config file locations
SHOW config_file;
-- Example: /var/lib/postgresql/data/postgresql.conf

SHOW hba_file;
-- Example: /var/lib/postgresql/data/pg_hba.conf

SHOW data_directory;
-- Example: /var/lib/postgresql/data

On a Docker container, these are at /var/lib/postgresql/data/. On a bare-metal Fedora install, they are typically at /var/lib/pgsql/18/data/. On Ubuntu, they are at /etc/postgresql/18/main/.

postgresql.conf: The Main Configuration File

This file controls everything about how PostgreSQL runs. Here are the settings you need to understand:

Connection Settings:

# Listen on all interfaces (default is localhost only)
listen_addresses = '*'          # For development; restrict in production

# Maximum concurrent connections
max_connections = 100           # Default is 100; tune based on workload

# Port (default 5432)
port = 5432

Memory Settings:

# Shared memory for caching data pages
# Rule of thumb: 25% of total system RAM
shared_buffers = 2GB            # Default is 128MB — far too low

# Memory for sorting, hashing, and other operations per query
work_mem = 64MB                 # Default 4MB; increase for complex queries

# Memory for maintenance operations (VACUUM, CREATE INDEX)
maintenance_work_mem = 512MB    # Default 64MB

# OS page cache hint
effective_cache_size = 6GB      # 50-75% of total RAM; helps query planner

Write-Ahead Log (WAL) Settings:

# WAL level (minimal, replica, or logical)
wal_level = replica             # Needed for replication and point-in-time recovery

# Checkpoint settings
checkpoint_completion_target = 0.9
max_wal_size = 2GB
min_wal_size = 80MB

Query Planner Settings:

# Cost estimates for planner decisions
random_page_cost = 1.1          # Lower if using SSDs (default 4.0 assumes HDDs)
effective_io_concurrency = 200  # Higher for SSDs; default 1

# PostgreSQL 18: Asynchronous I/O method
io_method = worker              # 'worker' (all platforms), 'io_uring' (Linux), 'sync' (legacy)

Logging:

# Log destination
logging_collector = on
log_directory = 'pg_log'
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'

# What to log
log_min_duration_statement = 500    # Log queries taking > 500ms
log_statement = 'none'              # 'none', 'ddl', 'mod', or 'all'
log_line_prefix = '%t [%p] %u@%d '  # Timestamp, PID, user@database

# Log slow queries with their execution plans
auto_explain.log_min_duration = 1000  # Requires loading auto_explain extension

Development vs. Production:

For development, you might use more aggressive logging:

log_statement = 'all'
log_min_duration_statement = 0
log_connections = on
log_disconnections = on

For production, you want to log only what matters:

log_statement = 'ddl'
log_min_duration_statement = 1000
log_connections = off
log_disconnections = off

pg_hba.conf: Client Authentication Configuration

This file controls who can connect to your database and how they authenticate. Each line specifies a connection type, database, user, address, and authentication method.

# TYPE  DATABASE    USER        ADDRESS         METHOD

# Local connections (Unix socket)
local   all         postgres                    peer
local   all         all                         scram-sha-256

# IPv4 local connections
host    all         all         127.0.0.1/32    scram-sha-256

# IPv4 remote connections (restrict in production)
host    all         all         0.0.0.0/0       scram-sha-256

# IPv6 local connections
host    all         all         ::1/128         scram-sha-256

Authentication methods you should know:

peer uses the operating system username. If you are logged in as the Linux user postgres, you can connect to the postgres database role without a password. This only works for local (Unix socket) connections.

scram-sha-256 is the modern password authentication method. It is significantly more secure than the older md5 method. PostgreSQL 18 has deprecated MD5 authentication, and it will be removed in a future release. Always use SCRAM.

reject denies the connection. Useful for explicitly blocking certain combinations.

cert requires a TLS client certificate. Used in high-security environments.

After editing pg_hba.conf, you must reload the configuration:

sudo systemctl reload postgresql-18
# Or from inside psql:
SELECT pg_reload_conf();

Configuration for Docker Containers

When running PostgreSQL in Docker, you can pass configuration parameters at startup:

docker run -d \
  --name pg-dev \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  postgres:18 \
  -c shared_buffers=512MB \
  -c work_mem=32MB \
  -c max_connections=200

Or mount a custom configuration file:

docker run -d \
  --name pg-dev \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  -v ./my-postgresql.conf:/etc/postgresql/postgresql.conf \
  postgres:18 \
  -c config_file=/etc/postgresql/postgresql.conf

Part 4: The Terminal — psql and Beyond

psql: The Standard Client

psql is PostgreSQL's interactive terminal. It is the equivalent of sqlcmd for SQL Server, but far more capable. Every PostgreSQL developer should be fluent with psql.

Connecting:

# Connect to a local database
psql -U myapp -d myappdb

# Connect to a remote server
psql -h 192.168.1.100 -p 5432 -U myapp -d myappdb

# Using a connection string
psql "host=192.168.1.100 port=5432 dbname=myappdb user=myapp password=secret sslmode=require"

# Using a URI
psql postgresql://myapp:secret@192.168.1.100:5432/myappdb?sslmode=require

Essential Meta-Commands:

\l          List all databases
\c dbname   Connect to a different database
\dt         List tables in current schema
\dt+        List tables with sizes
\d table    Describe a table (columns, types, constraints)
\d+ table   Describe with additional detail (storage, description)
\di         List indexes
\df         List functions
\dv         List views
\dn         List schemas
\du         List roles/users
\dp         List table privileges
\x          Toggle expanded display (vertical output)
\timing     Toggle query timing display
\e          Open query in $EDITOR
\i file.sql Execute SQL from a file
\o file.txt Send output to a file
\q          Quit

Running SQL from the Command Line:

# Execute a single command
psql -U myapp -d myappdb -c "SELECT count(*) FROM users;"

# Execute a SQL file
psql -U myapp -d myappdb -f migrations/001-create-tables.sql

# Execute and get CSV output
psql -U myapp -d myappdb -c "COPY (SELECT * FROM users) TO STDOUT WITH CSV HEADER;"

# Pipe SQL from stdin
echo "SELECT now();" | psql -U myapp -d myappdb

Environment Variables:

You can avoid typing credentials repeatedly by setting environment variables:

export PGHOST=localhost
export PGPORT=5432
export PGUSER=myapp
export PGPASSWORD=my-secure-password
export PGDATABASE=myappdb

# Now just type:
psql

For a more secure approach, use a .pgpass file:

# Create ~/.pgpass with format: hostname:port:database:username:password
echo "localhost:5432:myappdb:myapp:my-secure-password" > ~/.pgpass
chmod 600 ~/.pgpass

pgcli: A Better Terminal Experience

pgcli is a drop-in replacement for psql with intelligent autocompletion and syntax highlighting:

# Install via pip
pip install pgcli

# Or on Fedora
sudo dnf install pgcli

# Or on Ubuntu
sudo apt install pgcli

# Use exactly like psql
pgcli -U myapp -d myappdb

pgcli provides real-time autocomplete for table names, column names, SQL keywords, and even suggests JOINs based on foreign key relationships. If you spend any time in the terminal, install pgcli immediately.

Part 5: PostgreSQL 17 and 18 — What Is New

PostgreSQL 17 (Released September 26, 2024)

PostgreSQL 17 delivered major performance improvements. The vacuum subsystem received a complete memory management overhaul, reducing memory consumption by up to 20x. This means autovacuum runs more efficiently, keeping your tables healthy with less resource contention. Bulk loading and exporting via the COPY command saw up to 2x performance improvements for large rows.

The JSON_TABLE function arrived, letting you convert JSON data directly into a relational table representation within SQL:

SELECT *
FROM JSON_TABLE(
    '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]'::jsonb,
    '$[*]'
    COLUMNS (
        name TEXT PATH '$.name',
        age INT PATH '$.age'
    )
) AS jt;

The MERGE statement gained a RETURNING clause, and views became updatable via MERGE. The COPY command added an ON_ERROR option that allows imports to continue even when individual rows fail. Logical replication received failover slot synchronization, enabling high-availability setups to maintain replication through primary failovers. Incremental backups landed natively via pg_basebackup --incremental, with pg_combinebackup for restoration. Direct SSL connections became possible with the sslnegotiation=direct client option, saving a roundtrip during connection establishment.

PostgreSQL 18 (Released September 25, 2025)

PostgreSQL 18 is a landmark release. The headline feature is the Asynchronous I/O (AIO) subsystem, which fundamentally changes how PostgreSQL handles read operations. Instead of issuing synchronous I/O calls and waiting for each to complete, PostgreSQL 18 can issue multiple I/O requests concurrently. Benchmarks demonstrate up to 3x performance improvements for sequential scans, bitmap heap scans, and vacuum operations.

-- Configure the AIO method
SET io_method = 'worker';     -- Worker-based (all platforms)
SET io_method = 'io_uring';   -- io_uring (Linux only, fastest)
SET io_method = 'sync';       -- Traditional synchronous I/O

Native UUIDv7 support arrived via the uuidv7() function. UUIDv7 combines global uniqueness with timestamp-based ordering, making it ideal for primary keys because the sequential nature provides excellent B-tree index performance:

-- Generate a timestamp-ordered UUID
SELECT uuidv7();
-- Result: 01980de8-ad3d-715c-b739-faf2bb1a7aad

-- Extract the embedded timestamp
SELECT uuid_extract_timestamp(uuidv7());

-- Use as a primary key
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT uuidv7(),
    customer_id INT NOT NULL,
    total DECIMAL(10,2) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now()
);

Virtual generated columns became the default. Unlike stored generated columns (which write computed values to disk), virtual columns compute their values on-the-fly during reads:

CREATE TABLE invoices (
    id SERIAL PRIMARY KEY,
    subtotal DECIMAL(10,2),
    tax_rate DECIMAL(5,4) DEFAULT 0.0875,
    -- Virtual by default: computed at read time, no disk storage
    total DECIMAL(10,2) GENERATED ALWAYS AS (subtotal * (1 + tax_rate))
);

The RETURNING clause was enhanced with OLD and NEW references for INSERT, UPDATE, DELETE, and MERGE:

-- See both old and new values in a single UPDATE
UPDATE products
SET price = price * 1.10
WHERE category = 'electronics'
RETURNING name, old.price AS was, new.price AS now;

Temporal constraints allow defining non-overlapping constraints on range types, ideal for scheduling and reservation systems:

CREATE TABLE room_bookings (
    room_id INT,
    booked_during TSTZRANGE,
    guest TEXT,
    PRIMARY KEY (room_id, booked_during WITHOUT OVERLAPS)
);

OAuth 2.0 authentication support was added, enabling integration with modern identity providers. MD5 password authentication was deprecated in favor of SCRAM-SHA-256. The pg_upgrade utility now preserves planner statistics during major version upgrades, eliminating the performance dip that previously occurred while ANALYZE rebuilt statistics. Skip scan lookups on multicolumn B-tree indexes allow queries that omit leading index columns to still benefit from the index.

EXPLAIN ANALYZE now automatically includes buffer usage statistics (previously required BUFFERS option), and verbose output includes WAL writes, CPU time, and average read times.

Part 6: Npgsql — The .NET Data Provider

Npgsql is the open-source ADO.NET data provider for PostgreSQL. It is licensed under the PostgreSQL License (permissive, like MIT). The latest major version is Npgsql 10.x, which targets .NET 10.

Installation

dotnet add package Npgsql

Or in your Directory.Packages.props for central package management:

<PackageVersion Include="Npgsql" Version="10.0.2" />

Basic Usage with NpgsqlDataSource

Modern Npgsql (version 7+) uses NpgsqlDataSource as the preferred entry point. It manages connection pooling, configuration, and type mapping:

using Npgsql;

var connString = "Host=localhost;Port=5432;Database=myappdb;Username=myapp;Password=secret";
var dataSourceBuilder = new NpgsqlDataSourceBuilder(connString);
await using var dataSource = dataSourceBuilder.Build();

// Get a connection from the pool
await using var conn = await dataSource.OpenConnectionAsync();

// Execute a query
await using var cmd = new NpgsqlCommand("SELECT id, name, email FROM users WHERE active = @active", conn);
cmd.Parameters.AddWithValue("active", true);

await using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    var id = reader.GetInt32(0);
    var name = reader.GetString(1);
    var email = reader.GetString(2);
    Console.WriteLine($"{id}: {name} ({email})");
}

Connection String Parameters You Should Know

Host=localhost           Server hostname or IP
Port=5432                Server port
Database=myappdb         Database name
Username=myapp           Database user
Password=secret          Password
SSL Mode=Prefer          None, Prefer, Require, VerifyCA, VerifyFull
Pooling=true             Enable connection pooling (default: true)
Minimum Pool Size=0      Minimum idle connections
Maximum Pool Size=100    Maximum concurrent connections
Connection Idle Lifetime=300   Seconds before idle connection is closed
Timeout=15               Connection timeout in seconds
Command Timeout=30       Default command timeout in seconds
Include Error Detail=true  Include server error details (dev only)

For production, always use SSL:

Host=db.example.com;Database=prod;Username=app;Password=secret;SSL Mode=VerifyFull;Trust Server Certificate=false

Npgsql with Dependency Injection in ASP.NET

// In Program.cs
builder.Services.AddNpgsqlDataSource(
    builder.Configuration.GetConnectionString("DefaultConnection")!,
    dataSourceBuilder =>
    {
        dataSourceBuilder.UseNodaTime();       // Optional: NodaTime date/time types
        dataSourceBuilder.MapEnum<OrderStatus>("order_status"); // Map PostgreSQL enums
    }
);

This registers NpgsqlDataSource as a singleton in the DI container. Inject it anywhere:

public class UserRepository(NpgsqlDataSource dataSource)
{
    public async Task<User?> GetByIdAsync(int id)
    {
        await using var conn = await dataSource.OpenConnectionAsync();
        await using var cmd = new NpgsqlCommand("SELECT id, name, email FROM users WHERE id = @id", conn);
        cmd.Parameters.AddWithValue("id", id);

        await using var reader = await cmd.ExecuteReaderAsync();
        if (await reader.ReadAsync())
        {
            return new User(reader.GetInt32(0), reader.GetString(1), reader.GetString(2));
        }
        return null;
    }
}

Key Npgsql 9.0 and 10.0 Features

Npgsql 9.0 dropped .NET Standard 2.0 support (and thus .NET Framework). If you need .NET Framework, stay on Npgsql 8.x.

Npgsql 9.0 introduced UUIDv7 generation for EF Core key values by default. When EF Core generates Guid keys client-side, Npgsql 9.0+ uses sequential UUIDv7 instead of random UUIDv4, improving index performance significantly.

Direct SSL support was added for PostgreSQL 17+, saving a roundtrip when establishing secure connections. Enable it with SslNegotiation=direct in your connection string.

OpenTelemetry tracing was improved with a ConfigureTracing API that lets you filter which commands are traced, add custom tags to spans, and control span naming.

Npgsql 10.0 (latest as of March 2026) targets .NET 10 and is considering deprecating synchronous APIs (NpgsqlConnection.Open, NpgsqlCommand.ExecuteNonQuery, etc.) in a future release. The recommendation is to use async APIs everywhere: OpenAsync, ExecuteNonQueryAsync, ExecuteReaderAsync.

Part 7: Npgsql with Dapper

Dapper is a lightweight micro-ORM that extends IDbConnection with extension methods for mapping query results to objects. It works beautifully with Npgsql.

Installation

dotnet add package Dapper

Basic Queries

using Dapper;
using Npgsql;

public class ProductRepository(NpgsqlDataSource dataSource)
{
    public async Task<IEnumerable<Product>> GetAllAsync()
    {
        await using var conn = await dataSource.OpenConnectionAsync();
        return await conn.QueryAsync<Product>("SELECT id, name, price, stock FROM products ORDER BY name");
    }

    public async Task<Product?> GetByIdAsync(int id)
    {
        await using var conn = await dataSource.OpenConnectionAsync();
        return await conn.QuerySingleOrDefaultAsync<Product>(
            "SELECT id, name, price, stock FROM products WHERE id = @Id",
            new { Id = id }
        );
    }

    public async Task<int> CreateAsync(Product product)
    {
        await using var conn = await dataSource.OpenConnectionAsync();
        return await conn.ExecuteScalarAsync<int>(
            """
            INSERT INTO products (name, price, stock)
            VALUES (@Name, @Price, @Stock)
            RETURNING id
            """,
            product
        );
    }

    public async Task<bool> UpdateAsync(Product product)
    {
        await using var conn = await dataSource.OpenConnectionAsync();
        var affected = await conn.ExecuteAsync(
            """
            UPDATE products
            SET name = @Name, price = @Price, stock = @Stock
            WHERE id = @Id
            """,
            product
        );
        return affected > 0;
    }

    public async Task<bool> DeleteAsync(int id)
    {
        await using var conn = await dataSource.OpenConnectionAsync();
        var affected = await conn.ExecuteAsync("DELETE FROM products WHERE id = @Id", new { Id = id });
        return affected > 0;
    }
}

Multi-Mapping (Joins)

public async Task<IEnumerable<Order>> GetOrdersWithCustomerAsync()
{
    await using var conn = await dataSource.OpenConnectionAsync();
    var sql = """
        SELECT o.id, o.order_date, o.total,
               c.id, c.name, c.email
        FROM orders o
        INNER JOIN customers c ON o.customer_id = c.id
        ORDER BY o.order_date DESC
        """;

    return await conn.QueryAsync<Order, Customer, Order>(
        sql,
        (order, customer) =>
        {
            order.Customer = customer;
            return order;
        },
        splitOn: "id"  // Column where the second object starts
    );
}

Transactions with Dapper

public async Task TransferFundsAsync(int fromId, int toId, decimal amount)
{
    await using var conn = await dataSource.OpenConnectionAsync();
    await using var tx = await conn.BeginTransactionAsync();

    try
    {
        await conn.ExecuteAsync(
            "UPDATE accounts SET balance = balance - @Amount WHERE id = @Id",
            new { Amount = amount, Id = fromId },
            transaction: tx
        );

        await conn.ExecuteAsync(
            "UPDATE accounts SET balance = balance + @Amount WHERE id = @Id",
            new { Amount = amount, Id = toId },
            transaction: tx
        );

        await tx.CommitAsync();
    }
    catch
    {
        await tx.RollbackAsync();
        throw;
    }
}

Dapper Tips for PostgreSQL

PostgreSQL uses snake_case column names, but C# uses PascalCase properties. Configure Dapper to handle this automatically:

// In Program.cs or startup
Dapper.DefaultTypeMap.MatchNamesWithUnderscores = true;

Now order_date in PostgreSQL maps to OrderDate in C#.

For PostgreSQL arrays, Npgsql handles them natively:

var tags = new[] { "electronics", "sale" };
var products = await conn.QueryAsync<Product>(
    "SELECT * FROM products WHERE tags && @Tags",
    new { Tags = tags }
);

For JSONB columns:

var metadata = JsonSerializer.Serialize(new { source = "web", campaign = "spring" });
await conn.ExecuteAsync(
    "INSERT INTO events (type, metadata) VALUES (@Type, @Metadata::jsonb)",
    new { Type = "page_view", Metadata = metadata }
);

Part 8: Npgsql with Entity Framework Core

Installation

dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

DbContext Configuration

public class AppDbContext : DbContext
{
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<Customer> Customers => Set<Customer>();

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

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Use snake_case naming convention for all tables and columns
        modelBuilder.HasDefaultSchema("public");

        modelBuilder.Entity<Product>(entity =>
        {
            entity.ToTable("products");
            entity.HasKey(e => e.Id);
            entity.Property(e => e.Id).HasColumnName("id");
            entity.Property(e => e.Name).HasColumnName("name").HasMaxLength(200);
            entity.Property(e => e.Price).HasColumnName("price").HasColumnType("decimal(10,2)");
            entity.Property(e => e.Stock).HasColumnName("stock");
            entity.Property(e => e.Tags).HasColumnName("tags").HasColumnType("text[]");
            entity.Property(e => e.Metadata).HasColumnName("metadata").HasColumnType("jsonb");
            entity.HasIndex(e => e.Name);
        });
    }
}

Registration in ASP.NET

// Program.cs
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(
        builder.Configuration.GetConnectionString("DefaultConnection"),
        npgsqlOptions =>
        {
            npgsqlOptions.UseNodaTime();
            npgsqlOptions.MapEnum<OrderStatus>("order_status");
            npgsqlOptions.SetPostgresVersion(18, 0);  // Enable PG18-specific SQL generation
            npgsqlOptions.EnableRetryOnFailure(
                maxRetryCount: 3,
                maxRetryDelay: TimeSpan.FromSeconds(5),
                errorCodesToAdd: null
            );
        }
    )
);

Migrations

# Add a migration
dotnet ef migrations add InitialCreate

# Apply migrations
dotnet ef database update

# Generate a SQL script (for production deployments)
dotnet ef migrations script -o migrations.sql

PostgreSQL-Specific EF Core Features

JSONB Columns:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public Dictionary<string, string> Metadata { get; set; } = new();
}

// In OnModelCreating
entity.Property(e => e.Metadata).HasColumnType("jsonb");

// Query JSONB
var products = await context.Products
    .Where(p => EF.Functions.JsonContains(p.Metadata, new { color = "red" }))
    .ToListAsync();

Array Columns:

public class Product
{
    public int Id { get; set; }
    public string[] Tags { get; set; } = [];
}

// Query arrays
var electronics = await context.Products
    .Where(p => p.Tags.Contains("electronics"))
    .ToListAsync();

Full-Text Search:

var results = await context.Products
    .Where(p => EF.Functions.ToTsVector("english", p.Name + " " + p.Description)
        .Matches(EF.Functions.ToTsQuery("english", "wireless & keyboard")))
    .ToListAsync();

PostgreSQL Enums:

public enum OrderStatus { Pending, Processing, Shipped, Delivered, Cancelled }

// In OnModelCreating
modelBuilder.HasPostgresEnum<OrderStatus>();
modelBuilder.Entity<Order>().Property(e => e.Status).HasColumnType("order_status");

// In UseNpgsql configuration
npgsqlOptions.MapEnum<OrderStatus>("order_status");

EF Core Performance Tips for PostgreSQL

Use compiled queries for hot paths:

private static readonly Func<AppDbContext, int, Task<Product?>> GetProductById =
    EF.CompileAsyncQuery((AppDbContext ctx, int id) =>
        ctx.Products.FirstOrDefault(p => p.Id == id));

Use AsNoTracking() for read-only queries:

var products = await context.Products.AsNoTracking().ToListAsync();

Use ExecuteUpdateAsync and ExecuteDeleteAsync for bulk operations (avoids loading entities):

await context.Products
    .Where(p => p.Stock == 0)
    .ExecuteUpdateAsync(s => s.SetProperty(p => p.Status, "Discontinued"));

await context.Products
    .Where(p => p.DeletedAt < DateTime.UtcNow.AddYears(-1))
    .ExecuteDeleteAsync();

Part 9: Transactions and Isolation Levels

Transaction Basics

PostgreSQL supports full ACID transactions. Every statement in PostgreSQL runs inside a transaction. If you do not explicitly begin one, each statement is wrapped in an implicit transaction.

-- Explicit transaction
BEGIN;
    UPDATE accounts SET balance = balance - 100 WHERE id = 1;
    UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;

-- Rollback on error
BEGIN;
    UPDATE accounts SET balance = balance - 100 WHERE id = 1;
    -- Oops, something went wrong
ROLLBACK;

Savepoints

Savepoints allow partial rollback within a transaction:

BEGIN;
    INSERT INTO orders (customer_id, total) VALUES (1, 99.99);
    SAVEPOINT before_items;

    INSERT INTO order_items (order_id, product_id, qty) VALUES (1, 100, 1);
    -- This fails due to a constraint violation
    ROLLBACK TO SAVEPOINT before_items;

    -- Try a different product
    INSERT INTO order_items (order_id, product_id, qty) VALUES (1, 200, 1);
COMMIT;

Isolation Levels

PostgreSQL supports four isolation levels. Here is what each one actually does:

Read Committed (Default): Each statement within a transaction sees a snapshot of the database as of the moment that statement began execution. If another transaction commits between two statements in your transaction, the second statement sees the committed changes. This is the default and is appropriate for most workloads.

Repeatable Read: The transaction sees a snapshot of the database as of the moment the transaction began (not each statement). If another transaction commits changes to rows your transaction has read, and you try to update those same rows, PostgreSQL raises a serialization error and you must retry the transaction. This prevents non-repeatable reads and phantom reads.

Serializable: The strictest level. PostgreSQL guarantees that the result of concurrent serializable transactions is equivalent to some serial (one-at-a-time) ordering. If PostgreSQL detects that no such ordering is possible, it raises a serialization error. This is the safest but most restrictive level.

Read Uncommitted: In PostgreSQL, this is identical to Read Committed. PostgreSQL does not support dirty reads, ever. Setting READ UNCOMMITTED is accepted for SQL standard compliance but behaves as Read Committed.

-- Set isolation level for a transaction
BEGIN ISOLATION LEVEL REPEATABLE READ;
    SELECT * FROM accounts WHERE id = 1;
    -- ... more operations ...
COMMIT;

-- Set default isolation level for a session
SET default_transaction_isolation = 'repeatable read';

In C# with Npgsql:

await using var conn = await dataSource.OpenConnectionAsync();
await using var tx = await conn.BeginTransactionAsync(IsolationLevel.RepeatableRead);

try
{
    // ... operations ...
    await tx.CommitAsync();
}
catch (PostgresException ex) when (ex.SqlState == "40001") // serialization_failure
{
    await tx.RollbackAsync();
    // Retry the entire transaction
}

The NOLOCK Question

This deserves its own section because it is the single most common question from SQL Server developers.

In SQL Server, NOLOCK (or READ UNCOMMITTED isolation level) tells the engine to read data without acquiring shared locks. This prevents readers from blocking writers and vice versa. It is commonly used in SQL Server because the default Read Committed isolation level uses locking, which can cause severe blocking under concurrent load.

You do not need NOLOCK in PostgreSQL. It does not exist, and you should not miss it.

PostgreSQL uses MVCC for all isolation levels. Readers never block writers. Writers never block readers. The problem that NOLOCK solves in SQL Server simply does not exist in PostgreSQL. When you execute a SELECT in PostgreSQL, you read from a consistent snapshot without acquiring any locks that would block concurrent INSERT, UPDATE, or DELETE operations.

The only time you can experience blocking in PostgreSQL is when two transactions try to modify the same row concurrently. In that case, the second transaction waits for the first to commit or rollback. This is correct behavior — you would not want two concurrent updates to silently overwrite each other.

Should you use READ UNCOMMITTED in development? It makes no difference in PostgreSQL. It behaves identically to READ COMMITTED.

Should you use READ UNCOMMITTED in production? It makes no difference in PostgreSQL. But do not bother setting it. Just use the default READ COMMITTED.

Bottom line: forget about NOLOCK. PostgreSQL solved this problem at the architecture level.

Advisory Locks

PostgreSQL provides advisory locks for application-level locking that does not correspond to any particular table or row:

-- Session-level advisory lock (held until session ends or explicitly released)
SELECT pg_advisory_lock(12345);
-- ... do exclusive work ...
SELECT pg_advisory_unlock(12345);

-- Transaction-level advisory lock (released at end of transaction)
BEGIN;
SELECT pg_advisory_xact_lock(12345);
-- ... do exclusive work ...
COMMIT;  -- Lock is automatically released

-- Try to acquire without blocking
SELECT pg_try_advisory_lock(12345);  -- Returns true/false

In C# with Npgsql:

await using var conn = await dataSource.OpenConnectionAsync();
await using var tx = await conn.BeginTransactionAsync();

await using (var cmd = new NpgsqlCommand("SELECT pg_advisory_xact_lock(@key)", conn))
{
    cmd.Parameters.AddWithValue("key", 12345L);
    cmd.Transaction = tx;
    await cmd.ExecuteNonQueryAsync();
}

// ... perform exclusive work ...

await tx.CommitAsync(); // Advisory lock released

Part 10: Networking, Sessions, and Connection Pooling

SSL/TLS Configuration

For production, always encrypt connections. In postgresql.conf:

ssl = on
ssl_cert_file = '/path/to/server.crt'
ssl_key_file = '/path/to/server.key'
ssl_ca_file = '/path/to/ca.crt'

# PostgreSQL 18: Control TLS 1.3 cipher suites
ssl_tls13_ciphers = 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256'

In your .NET connection string:

Host=db.example.com;Database=prod;Username=app;Password=secret;SSL Mode=VerifyFull;Root Certificate=/path/to/ca.crt

Connection Pooling

Npgsql has built-in connection pooling enabled by default. Each unique connection string gets its own pool. Key parameters:

Minimum Pool Size=0       # Pre-create this many connections
Maximum Pool Size=100     # Hard limit on concurrent connections
Connection Idle Lifetime=300  # Close idle connections after 5 minutes
Connection Pruning Interval=10  # Check for idle connections every 10 seconds

For high-concurrency applications, consider PgBouncer as an external connection pooler:

# pgbouncer.ini
[databases]
myappdb = host=127.0.0.1 port=5432 dbname=myappdb

[pgbouncer]
listen_port = 6432
listen_addr = 0.0.0.0
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction    # transaction pooling is best for web apps
default_pool_size = 20
max_client_conn = 1000

With transaction-mode pooling, PgBouncer assigns a server connection to a client for the duration of a transaction, then returns it to the pool. This allows hundreds of application connections to share a much smaller number of PostgreSQL connections.

Monitoring Active Sessions

-- View all active connections
SELECT pid, usename, datname, client_addr, state, query, query_start
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY query_start;

-- Kill a specific session
SELECT pg_terminate_backend(12345);

-- Cancel the current query in a session (gentler than terminate)
SELECT pg_cancel_backend(12345);

-- View connection counts by state
SELECT state, count(*)
FROM pg_stat_activity
GROUP BY state;

Lock Monitoring

-- View current locks
SELECT l.pid, l.locktype, l.mode, l.granted,
       a.usename, a.query, a.state
FROM pg_locks l
JOIN pg_stat_activity a ON l.pid = a.pid
WHERE NOT l.granted
ORDER BY l.pid;

-- Find blocking queries
SELECT blocked.pid AS blocked_pid,
       blocked.query AS blocked_query,
       blocking.pid AS blocking_pid,
       blocking.query AS blocking_query
FROM pg_stat_activity blocked
JOIN pg_locks bl ON blocked.pid = bl.pid AND NOT bl.granted
JOIN pg_locks gl ON bl.locktype = gl.locktype
    AND bl.relation = gl.relation
    AND bl.page = gl.page
    AND bl.tuple = gl.tuple
    AND gl.granted
JOIN pg_stat_activity blocking ON gl.pid = blocking.pid
WHERE blocked.pid != blocking.pid;

Part 11: Debugging and Performance Tuning

EXPLAIN and EXPLAIN ANALYZE

This is the single most important debugging tool in PostgreSQL. EXPLAIN shows the query plan. EXPLAIN ANALYZE actually executes the query and shows real timing.

-- Show the query plan (does not execute)
EXPLAIN SELECT * FROM products WHERE price > 100;

-- Execute and show actual timing
EXPLAIN ANALYZE SELECT * FROM products WHERE price > 100;

-- PostgreSQL 18: BUFFERS is included automatically in EXPLAIN ANALYZE
-- In older versions, add it explicitly:
EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM products WHERE price > 100;

-- Format as JSON (useful for visualization tools)
EXPLAIN (ANALYZE, FORMAT JSON) SELECT * FROM products WHERE price > 100;

Key things to look for in query plans:

Seq Scan: A full table scan. Fine for small tables, concerning for large ones. If you see a Seq Scan on a large table with a WHERE clause, you probably need an index.

Index Scan: Uses a B-tree (or other) index. This is what you want for selective queries.

Index Only Scan: Even better — the query is answered entirely from the index without accessing the table heap.

Bitmap Index Scan + Bitmap Heap Scan: Used when the query matches many rows. The bitmap index scan builds a bitmap of matching pages, then the bitmap heap scan fetches those pages. Efficient for medium-selectivity queries.

Nested Loop / Hash Join / Merge Join: Join strategies. Nested Loop is best for small result sets, Hash Join for larger ones, Merge Join when both inputs are sorted.

Rows: Compare "estimated" vs "actual" rows. Large discrepancies mean your statistics are stale (run ANALYZE).

Statistics and ANALYZE

PostgreSQL's query planner relies on statistics about your data to choose efficient plans. These statistics are updated by the autovacuum daemon, but you can trigger an update manually:

-- Update statistics for a specific table
ANALYZE products;

-- Update statistics for the entire database
ANALYZE;

-- Check when statistics were last updated
SELECT schemaname, relname, last_analyze, last_autoanalyze
FROM pg_stat_user_tables;

pg_stat_statements

This extension tracks execution statistics for all SQL statements:

-- Enable the extension
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- View top queries by total time
SELECT query, calls, total_exec_time, mean_exec_time, rows
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 20;

-- Reset statistics
SELECT pg_stat_statements_reset();

Add to postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all

auto_explain

Automatically logs execution plans for slow queries:

# postgresql.conf
shared_preload_libraries = 'pg_stat_statements,auto_explain'
auto_explain.log_min_duration = 1000    # Log plans for queries > 1 second
auto_explain.log_analyze = on           # Include actual timing
auto_explain.log_buffers = on           # Include buffer usage
auto_explain.log_format = json          # JSON format for tooling

Indexing Best Practices

-- Standard B-tree index (most common)
CREATE INDEX idx_products_name ON products (name);

-- Partial index (only indexes rows matching a condition)
CREATE INDEX idx_active_products ON products (name) WHERE active = true;

-- Multi-column index (order matters for leftmost prefix matching)
CREATE INDEX idx_orders_customer_date ON orders (customer_id, order_date DESC);

-- GIN index for full-text search
CREATE INDEX idx_products_fts ON products
    USING GIN (to_tsvector('english', name || ' ' || description));

-- GIN index for JSONB containment queries
CREATE INDEX idx_products_metadata ON products USING GIN (metadata);

-- GIN index for array containment
CREATE INDEX idx_products_tags ON products USING GIN (tags);

-- BRIN index for naturally ordered data (timestamps, sequences)
-- Much smaller than B-tree, good for append-only tables
CREATE INDEX idx_events_created ON events USING BRIN (created_at);

-- Covering index (includes extra columns to enable index-only scans)
CREATE INDEX idx_products_name_covering ON products (name) INCLUDE (price, stock);

-- Concurrent index creation (does not lock the table)
CREATE INDEX CONCURRENTLY idx_products_sku ON products (sku);

Part 12: Free and Open-Source IDEs and GUI Tools on Linux

pgAdmin 4

pgAdmin is the official PostgreSQL administration tool, maintained by the PostgreSQL Global Development Group. It is the equivalent of SQL Server Management Studio, though it operates as a web application.

Installation on Fedora:

sudo rpm -i https://ftp.postgresql.org/pub/pgadmin/pgadmin4/yum/pgadmin4-fedora-repo-2-1.noarch.rpm
sudo dnf install pgadmin4-desktop  # Desktop mode
# Or
sudo dnf install pgadmin4-web      # Web server mode

Installation on Ubuntu:

curl -fsS https://www.pgadmin.org/static/packages_pgadmin_org.pub | sudo gpg --dearmor -o /usr/share/keyrings/packages-pgadmin-org.gpg
echo "deb [signed-by=/usr/share/keyrings/packages-pgadmin-org.gpg] https://ftp.postgresql.org/pub/pgadmin/pgadmin4/apt/$(lsb_release -cs) pgadmin4 main" | sudo tee /etc/apt/sources.list.d/pgadmin4.list
sudo apt update && sudo apt install pgadmin4-desktop

Strengths: Comprehensive server administration, backup/restore wizards, role management, server monitoring dashboard, visual explain plan viewer, query history. It is free, official, and supports every PostgreSQL feature.

Weaknesses: The interface is web-based (runs a local web server), which makes it noticeably slower than native applications. The UI is dense and complex. Query autocompletion is basic compared to other tools. Startup time is slow. It only supports PostgreSQL.

DBeaver Community Edition

DBeaver is the most popular general-purpose open-source database GUI. The Community Edition is free and open-source under the Apache License 2.0. It supports over 100 database types through JDBC drivers.

Installation:

# Flatpak (universal)
flatpak install flathub io.dbeaver.DBeaverCommunity

# Snap
sudo snap install dbeaver-ce

# Or download the .deb/.rpm from https://dbeaver.io/download/

Strengths: Supports virtually every database you will ever encounter. SQL editor with intelligent autocompletion. ER diagram generation. Data export to CSV, JSON, XML, SQL, Excel, HTML. Visual query builder. Active community with frequent releases. It works with PostgreSQL, SQL Server, MySQL, SQLite, Oracle, MongoDB, and dozens more from a single application.

Weaknesses: Java-based, so it can feel sluggish compared to native applications. The interface is feature-rich but busy. Initial schema loading can be slow on very large databases.

Beekeeper Studio

Beekeeper Studio is a modern, cross-platform SQL editor focused on usability. The Community Edition is free and open-source under GPL v3.

Installation:

# Flatpak
flatpak install flathub io.beekeeperstudio.Studio

# Snap
sudo snap install beekeeper-studio

# Or download from https://www.beekeeperstudio.io/

Strengths: Clean, fast, modern interface. Excellent autocomplete. Tabbed query results. Native-feeling performance. Supports PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB, and more. The simplest tool to pick up and use immediately.

Weaknesses: Fewer advanced administration features compared to pgAdmin or DBeaver. The free Community Edition has some limitations compared to the paid Ultimate edition (though all PostgreSQL core features are free).

DbGate

DbGate is a free, open-source database client that runs both as a desktop application and as a web application. It supports SQL and NoSQL databases.

Installation:

# Snap
sudo snap install dbgate

# Or download from https://dbgate.org/

Strengths: Works in the browser (no installation needed for the web version). Supports PostgreSQL, MySQL, SQL Server, MongoDB, SQLite, CockroachDB, and more. Data archiving and comparison features. Active development.

Weaknesses: Smaller community than DBeaver or pgAdmin. Some rough edges in the UI.

pgcli (Terminal)

Already mentioned above, but worth emphasizing: pgcli is the best terminal-based PostgreSQL client. It provides intelligent autocompletion, syntax highlighting, and multi-line editing.

pip install pgcli
# or
sudo dnf install pgcli

Visual Studio Code with PostgreSQL Extension

Microsoft released an official PostgreSQL extension for VS Code. It provides an object explorer, query editor with IntelliSense, schema visualization, and query history. Since many .NET developers already live in VS Code, this is a natural choice.

Installation: Search for "PostgreSQL" in the VS Code extensions marketplace and install the one by Microsoft.

Azure Data Studio

Azure Data Studio (formerly SQL Operations Studio) is Microsoft's cross-platform database tool. While it originated as a SQL Server tool, it supports PostgreSQL through an extension. It is free and open-source.

# Download from https://learn.microsoft.com/en-us/azure-data-studio/download
# Or install via Snap/Flatpak

Adminer

Adminer is a single PHP file that provides a complete database management interface. If you have PHP installed, you can deploy it in seconds. It supports PostgreSQL, MySQL, SQLite, SQL Server, and Oracle.

# Download the single file
wget https://www.adminer.org/latest.php -O adminer.php
php -S localhost:8080 adminer.php
# Open http://localhost:8080 in your browser

Comparison Summary

For pure PostgreSQL administration, use pgAdmin. It has every feature and is maintained by the PostgreSQL team. For a general-purpose GUI that handles multiple databases beautifully, use DBeaver Community. For a fast, clean, modern developer experience, use Beekeeper Studio. For terminal work, use pgcli. For integration with your editor, use the VS Code PostgreSQL extension.

All of these tools are completely free and open-source. None require payment for any feature relevant to PostgreSQL development work on Linux.

Part 13: Backup and Restore

pg_dump and pg_restore

# Dump a single database to a custom-format file (recommended)
pg_dump -h localhost -U myapp -d myappdb -Fc -f backup.dump

# Dump to plain SQL
pg_dump -h localhost -U myapp -d myappdb -f backup.sql

# Dump only the schema (no data)
pg_dump -h localhost -U myapp -d myappdb --schema-only -f schema.sql

# Dump only the data (no schema)
pg_dump -h localhost -U myapp -d myappdb --data-only -f data.sql

# Restore from custom format
pg_restore -h localhost -U myapp -d myappdb -c backup.dump

# Restore from plain SQL
psql -h localhost -U myapp -d myappdb -f backup.sql

# Dump all databases
pg_dumpall -h localhost -U postgres -f all-databases.sql

PostgreSQL 17: Incremental Backups

# Enable WAL summarization
ALTER SYSTEM SET summarize_wal = on;
SELECT pg_reload_conf();

# Take a full base backup
pg_basebackup -D /backups/full -Ft -z -P

# Take an incremental backup (only changes since last backup)
pg_basebackup -D /backups/incr1 --incremental /backups/full/backup_manifest -Ft -z -P

# Combine full + incremental for restore
pg_combinebackup /backups/full /backups/incr1 -o /backups/combined

Automated Backups with Cron

# Daily backup at 2 AM, keep 7 days
# Add to crontab: crontab -e
0 2 * * * pg_dump -h localhost -U myapp -d myappdb -Fc -f /backups/myappdb-$(date +\%Y\%m\%d).dump && find /backups -name "myappdb-*.dump" -mtime +7 -delete

Part 14: Common SQL Patterns for .NET Developers

Pagination

-- Offset-based (simple but slow for large offsets)
SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 40;

-- Cursor-based (efficient for large datasets)
SELECT * FROM products WHERE id > @LastId ORDER BY id LIMIT 20;

Upsert (INSERT ON CONFLICT)

INSERT INTO products (sku, name, price, stock)
VALUES ('WIDGET-001', 'Widget', 9.99, 100)
ON CONFLICT (sku)
DO UPDATE SET
    name = EXCLUDED.name,
    price = EXCLUDED.price,
    stock = EXCLUDED.stock;

Common Table Expressions (CTEs)

-- Recursive CTE for hierarchical data (e.g., categories)
WITH RECURSIVE category_tree AS (
    -- Base case: root categories
    SELECT id, name, parent_id, 0 AS depth
    FROM categories
    WHERE parent_id IS NULL

    UNION ALL

    -- Recursive case: children
    SELECT c.id, c.name, c.parent_id, ct.depth + 1
    FROM categories c
    INNER JOIN category_tree ct ON c.parent_id = ct.id
)
SELECT * FROM category_tree ORDER BY depth, name;

Window Functions

-- Rank products by price within each category
SELECT name, category, price,
       RANK() OVER (PARTITION BY category ORDER BY price DESC) AS price_rank,
       AVG(price) OVER (PARTITION BY category) AS avg_category_price
FROM products;

-- Running total
SELECT order_date, total,
       SUM(total) OVER (ORDER BY order_date) AS running_total
FROM orders;

GENERATE_SERIES

-- Generate a date series (useful for reports with no gaps)
SELECT d::date AS day,
       COALESCE(SUM(o.total), 0) AS daily_total
FROM generate_series('2026-01-01'::date, '2026-01-31'::date, '1 day') AS d
LEFT JOIN orders o ON o.order_date::date = d::date
GROUP BY d::date
ORDER BY d::date;

Full-Text Search

-- Add a tsvector column (or use a generated column)
ALTER TABLE products ADD COLUMN search_vector tsvector
    GENERATED ALWAYS AS (to_tsvector('english', name || ' ' || coalesce(description, ''))) STORED;

-- Create a GIN index
CREATE INDEX idx_products_search ON products USING GIN (search_vector);

-- Search
SELECT name, ts_rank(search_vector, query) AS rank
FROM products, to_tsquery('english', 'wireless & keyboard') AS query
WHERE search_vector @@ query
ORDER BY rank DESC;

Part 15: OpenTelemetry and Observability

Npgsql has built-in OpenTelemetry support:

dotnet add package Npgsql.OpenTelemetry

// Program.cs
builder.Services.AddNpgsqlDataSource(
    connectionString,
    dataSourceBuilder =>
    {
        dataSourceBuilder.ConfigureTracing(tracing =>
        {
            tracing.ConfigureCommandFilter(cmd =>
                !cmd.CommandText.StartsWith("SELECT 1")); // Filter out health checks
        });
    }
);

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddNpgsql();
        tracing.AddAspNetCoreInstrumentation();
        tracing.AddOtlpExporter();
    });

This emits OpenTelemetry spans for every database command, including the SQL text (sanitized by default), duration, and error information. You can view these in Jaeger, Zipkin, Grafana Tempo, or any OpenTelemetry-compatible backend.

For metrics, Npgsql emits connection pool statistics (active connections, idle connections, pending requests) as OpenTelemetry metrics automatically when you configure the tracing above.

Part 16: Security Best Practices

Always use SCRAM-SHA-256 authentication, never MD5 (deprecated in PostgreSQL 18). Always use SSL in production. Never use the postgres superuser for application connections; create dedicated users with minimal privileges.

-- Create a read-only user
CREATE ROLE readonly_user WITH LOGIN PASSWORD 'secure-password';
GRANT CONNECT ON DATABASE myappdb TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user;

-- Create an application user with read/write but no DDL
CREATE ROLE app_user WITH LOGIN PASSWORD 'secure-password';
GRANT CONNECT ON DATABASE myappdb TO app_user;
GRANT USAGE ON SCHEMA public TO app_user;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO app_user;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO app_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO app_user;

Use row-level security for multi-tenant applications:

ALTER TABLE tenant_data ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON tenant_data
    USING (tenant_id = current_setting('app.current_tenant')::int);

-- In your application, set the tenant context per request:
-- SET app.current_tenant = '42';

Part 17: Migrating from SQL Server Mental Models

Here is a quick reference for translating SQL Server concepts to PostgreSQL:

SQL Server's IDENTITY becomes PostgreSQL's SERIAL or GENERATED ALWAYS AS IDENTITY. SQL Server's NVARCHAR(MAX) becomes PostgreSQL's TEXT (there is no performance difference between VARCHAR(n) and TEXT in PostgreSQL; TEXT is preferred). SQL Server's DATETIME2 becomes PostgreSQL's TIMESTAMPTZ (always use the timezone-aware variant). SQL Server's BIT becomes PostgreSQL's BOOLEAN. SQL Server's UNIQUEIDENTIFIER becomes PostgreSQL's UUID. SQL Server's NVARCHAR(n) becomes PostgreSQL's VARCHAR(n) or TEXT (PostgreSQL stores all text as UTF-8 by default; there is no separate N prefix). SQL Server's TOP n becomes PostgreSQL's LIMIT n. SQL Server's ISNULL() becomes PostgreSQL's COALESCE(). SQL Server's GETDATE() becomes PostgreSQL's now() or CURRENT_TIMESTAMP. SQL Server's square-bracket quoting [column] becomes PostgreSQL's double-quote quoting "column", but you should use snake_case and avoid quoting entirely. SQL Server's @@IDENTITY / SCOPE_IDENTITY() becomes PostgreSQL's RETURNING id clause. SQL Server's stored procedures written in T-SQL become PostgreSQL functions or procedures written in PL/pgSQL, though many .NET developers prefer to keep logic in the application layer.

Conclusion

PostgreSQL is a world-class database that is completely free, fully featured, and exceptionally well-supported in the .NET ecosystem through Npgsql. Whether you are building a small side project or an enterprise application, PostgreSQL provides everything you need: MVCC concurrency that eliminates the locking headaches of SQL Server, a rich type system with native JSON, arrays, and full-text search support, excellent performance through the new AIO subsystem in PostgreSQL 18, and first-class .NET integration through Npgsql with both Dapper and Entity Framework Core.

The tooling on Linux is mature and diverse. pgAdmin gives you full administration capabilities, DBeaver gives you a universal GUI, Beekeeper Studio gives you a beautiful modern interface, pgcli gives you a superb terminal experience, and VS Code gives you database access without leaving your editor. All of it is free. All of it is open source.

The configuration is straightforward once you understand the two key files: postgresql.conf for server behavior and pg_hba.conf for authentication. Docker and Podman make it trivially easy to spin up PostgreSQL for development. And with the connection pooling built into Npgsql (or external via PgBouncer), your ASP.NET applications can handle massive concurrent loads efficiently.

If you are coming from SQL Server, the transition is smoother than you might expect. The SQL is standard. The concepts are familiar. The main adjustments are embracing MVCC (and forgetting about NOLOCK), adopting snake_case naming conventions, and learning the PostgreSQL-specific extensions like JSONB, arrays, and full-text search that do not have direct SQL Server equivalents.

Welcome to PostgreSQL. Your database just became free forever.

SQL Server is the database engine that powers a massive share of the .NET ecosystem. Whether you are building an ASP.NET Core Web API backed by Entity Framework Core, a Blazor application hitting a data layer, or a legacy Web Forms app with hand-crafted stored procedures, SQL Server is likely somewhere in your stack. Despite its ubiquity, many .NET developers treat the database as a black box — they write LINQ queries, hope EF Core generates something reasonable, and call it a day.

This guide exists to change that. We will walk through everything a practicing .NET developer should know about SQL Server: the evolution of features across versions 2016 through 2025, how to use SQL Server Management Studio (SSMS) like a power user, how to work from the terminal with sqlcmd, the fundamentals and advanced corners of T-SQL, how transactions and locking actually work, networking and session management, debugging production issues, and the best practices that separate a smooth-running production system from a 3 AM pager alert.

This is a long article. Bookmark it and come back. Let us begin.

Part 1: SQL Server Versions — What Shipped and Why It Matters

Understanding which features landed in which version is critical. Your production server might be running SQL Server 2019 while your development machine has 2022. Knowing the boundaries prevents you from writing code that works locally and fails in staging.

SQL Server 2016 (Version 13.x)

SQL Server 2016 was a watershed release. It introduced temporal tables — system-versioned tables that automatically track the full history of data changes, letting you query data as it existed at any point in the past using the FOR SYSTEM_TIME clause. It brought row-level security, allowing you to define predicate functions that filter rows based on the identity of the executing user, directly within the database engine rather than in application code. Dynamic data masking arrived, enabling you to obscure sensitive columns (like email addresses or credit card numbers) so that unprivileged users see masked values while authorized users see the real data.

The Always Encrypted feature debuted in 2016, providing client-side encryption of sensitive columns such that the database engine itself never sees the plaintext values — the encryption and decryption happen entirely in the client driver, which is critical for compliance scenarios.

On the performance front, 2016 introduced the Query Store — a built-in flight recorder for query plans and runtime statistics. The Query Store captures the execution plan history for every query, along with resource consumption metrics, making it straightforward to identify plan regressions and force a known-good plan without touching application code. This single feature changed how DBAs and developers troubleshoot performance problems.

JSON support also landed in 2016 with FOR JSON, OPENJSON, JSON_VALUE, and JSON_QUERY functions, though at this stage JSON was stored as plain NVARCHAR with no dedicated data type. R Services (later renamed Machine Learning Services) allowed you to execute R scripts directly inside the database engine.

SQL Server 2017 (Version 14.x)

The headline of SQL Server 2017 was Linux support. For the first time, SQL Server ran natively on Ubuntu, Red Hat Enterprise Linux, and SUSE Linux Enterprise Server, and was also available as a Docker container. This was a seismic shift — it meant you could run SQL Server in your CI pipeline on a Linux agent, deploy it on Kubernetes, or use it on a Mac for development via Docker.

Adaptive query processing appeared, where the query optimizer could adjust join strategies (for example, switching from a nested loop to a hash join) during execution based on actual row counts, and memory grant feedback allowed the engine to learn from previous executions and adjust memory allocations automatically. Graph database support was introduced with the NODE and EDGE table types, enabling you to model and query complex relationship-heavy data (think social networks, recommendation engines, or fraud detection graphs) using the MATCH pattern in T-SQL. Python support was added to Machine Learning Services alongside R, and automatic database tuning debuted — the engine could detect plan regressions and automatically force the last known good execution plan.

SQL Server 2019 (Version 15.x)

SQL Server 2019 brought Intelligent Query Processing (IQP) to the forefront with a suite of features: table variable deferred compilation (so the optimizer no longer assumed one row for table variables), batch mode on rowstore (previously batch mode was only available for columnstore indexes), and scalar UDF inlining (the optimizer could inline simple scalar functions directly into the calling query's plan, eliminating the per-row function call overhead that made scalar UDFs so notoriously slow).

Big Data Clusters were introduced (and later deprecated in SQL Server 2025, so do not invest new work here). Accelerated database recovery (ADR) fundamentally changed the crash recovery model by using a persistent version store, making recovery time proportional to the longest uncommitted transaction rather than the amount of work in the log. This was a game-changer for databases with long-running transactions.

UTF-8 collation support arrived, allowing you to use VARCHAR columns with UTF-8 encoding instead of needing NVARCHAR for international text, which could significantly reduce storage for data that is mostly ASCII but needs occasional Unicode support. The OPTIMIZE_FOR_SEQUENTIAL_KEY index option addressed the last-page insert contention problem common in tables with identity columns under high-concurrency inserts.

SQL Server 2022 (Version 16.x)

SQL Server 2022 was a major step toward cloud integration and performance modernization. The Intelligent Query Processing suite expanded further with Parameter Sensitivity Plan Optimization (PSP optimization) — the optimizer could now create multiple cached plans for the same parameterized query if it detected that different parameter values led to fundamentally different optimal plans. This directly attacked the classic parameter sniffing problem that has plagued SQL Server developers for decades. You no longer had to pepper your stored procedures with OPTION (RECOMPILE) or use the OPTIMIZE FOR hint as a band-aid.

Degree of Parallelism (DOP) feedback allowed the engine to learn the ideal degree of parallelism for a query over repeated executions and adjust it automatically, rather than relying on a server-wide MAXDOP setting. Cardinality estimation (CE) feedback let the optimizer correct persistent misestimates over time.

Ledger tables were introduced for tamper-evident data — the database maintains a cryptographic hash chain of all changes, allowing you to prove that data has not been modified outside of normal transactions. This is valuable for auditing and regulatory compliance without the complexity of a full blockchain.

Contained Availability Groups made it possible to include instance-level objects (logins, SQL Agent jobs, linked servers) inside the AG, so failover truly moved everything you needed. The LEAST and GREATEST functions finally arrived (yes, it took until 2022 to get these built-in). The DATETRUNC function, GENERATE_SERIES, STRING_SPLIT with an ordinal column, and WINDOW clause for cleaner window function syntax all simplified common T-SQL patterns.

On the connectivity side, SQL Server 2022 introduced TDS 8.0 with support for TLS 1.3 and strict encryption mode, where the connection is encrypted before the login handshake even begins.

The Query Store was enabled by default on new databases in SQL Server 2022, and Query Store hints became generally available — you could apply query hints (like MAXDOP, RECOMPILE, or USE HINT) to specific queries identified by their Query Store query_id, without modifying application code.

SQL Server 2025 (Version 17.x)

SQL Server 2025 reached general availability on November 18, 2025 at Microsoft Ignite. It is the most AI-focused release in SQL Server history, while simultaneously delivering substantial improvements for traditional workloads.

The native JSON data type is the headline developer feature. After a decade of storing JSON as NVARCHAR, SQL Server 2025 provides a proper JSON column type with optimized storage and native indexing. This means JSON data is stored in an efficient binary format internally, queries against JSON properties are faster, and you get schema validation at the engine level.

The native vector data type and built-in vector search bring AI and machine learning capabilities directly into the database engine. You can store embeddings (arrays of floating-point numbers produced by ML models) in VECTOR columns and perform similarity searches using distance functions like cosine similarity, all in T-SQL. For .NET developers building retrieval-augmented generation (RAG) applications, this eliminates the need for a separate vector database.

T-SQL enhancements are substantial: REGEX functions for pattern matching (you no longer need CLR assemblies or LIKE with wildcards for complex patterns), fuzzy string matching functions, and the ability to call external REST endpoints directly from T-SQL using sp_invoke_external_rest_endpoint. You can generate text embeddings and chunks directly in T-SQL, which is remarkable for in-database AI pipelines.

Optimized locking is a major engine improvement. SQL Server 2025 reworks the locking subsystem to reduce lock memory consumption and contention, which is particularly beneficial for high-concurrency OLTP workloads. Transaction ID (TID) locking replaces row-level locking after qualification, reducing the number of locks held and the potential for deadlocks.

Optional Parameter Plan Optimization (OPPO) is the evolution of PSP optimization from 2022, allowing the query optimizer to generate multiple plans for parameterized queries with even finer granularity.

The abort_query_execution hint lets DBAs block known-problematic queries from executing at all, which is a powerful safety net for production systems where a single bad query can bring down the server.

SQL Server Reporting Services (SSRS) is discontinued starting with 2025 — all on-premises reporting consolidation happens under Power BI Report Server (PBIRS).

On the platform side, SQL Server 2025 on Linux adds TLS 1.3, custom password policies, and signed container images. Platform support extends to RHEL 10 and Ubuntu 24.04. The Express edition maximum database size jumps to 50 GB (up from 10 GB), and the Express Advanced edition is consolidated into the base Express edition with all features included.

Standard edition capacity limits increase to 4 sockets or 32 cores, which is meaningful for mid-tier workloads that previously required Enterprise licensing.

Change event streaming allows you to stream changes directly from the transaction log to Azure Event Hubs, providing a lower-overhead alternative to Change Data Capture (CDC) for real-time event-driven architectures.

Part 2: SQL Server Management Studio (SSMS) — Mastering the Tool

SSMS is where most .NET developers spend their SQL Server time. As of March 2026, there are two current major versions: SSMS 21 and SSMS 22.

SSMS 21 and SSMS 22 Overview

Both SSMS 21 and 22 are built on the Visual Studio 2022 shell, making them 64-bit applications. This is a significant departure from SSMS 18, 19, and 20, which used the Visual Studio 2015 shell and were 32-bit. The practical impact is that SSMS 21/22 can handle much larger result sets and more complex execution plans without running out of memory.

SSMS is completely free and standalone. It does not require a SQL Server license, and it is not tied to any specific SQL Server edition or version. You can manage SQL Server 2012 through 2025, Azure SQL Database, Azure SQL Managed Instance, and Azure Synapse Analytics from a single SSMS installation.

SSMS 22 is the latest as of March 2026, with version 22.4.1 released on March 18, 2026. It introduces initial ARM64 support, GitHub Copilot integration (preview), a rebuilt connection dialog, and native support for SQL Server 2025 features like the vector data type.

Installation

Install SSMS using the Visual Studio Installer bootstrapper. Download the installer from the official Microsoft download page. The installer is a small bootstrapper that downloads the actual components. You do not need to install full Visual Studio — the installer handles the shell components automatically.

You can also install via the command line:

winget install Microsoft.SQLServerManagementStudio

For SSMS 21 specifically:

winget install Microsoft.SQLServerManagementStudio.21

SSMS 21 and 22 can coexist with SSMS 20 or earlier. You do not need to uninstall your old version first. Migrate your settings when you are comfortable.

The Connection Dialog

When you connect to SQL Server, pay attention to the encryption settings. SSMS 22 defaults to mandatory encryption (-Nm behavior), which is a breaking change from earlier versions. If you are connecting to a development SQL Server that uses a self-signed certificate, you may need to check "Trust server certificate" or the connection will fail with a certificate validation error. In production, you should use a proper certificate from a trusted CA and set the encryption mode to Strict (available for SQL Server 2022 and later), which uses TDS 8.0 and encrypts before the TLS handshake.

The authentication dropdown now includes Microsoft Entra (formerly Azure Active Directory) options: MFA, Interactive, Managed Identity, Service Principal, and Default. If your organization uses Entra ID for SQL Database or Managed Instance, these are the correct authentication methods.

SSMS Features Every Developer Should Use

Object Explorer is the tree view on the left. Right-clicking on any object gives you context-specific options. Right-click a table and choose "Script Table as > SELECT To > New Query Window" to generate a SELECT statement. Right-click a stored procedure and choose "Modify" to open its definition for editing. Right-click a database and go to "Reports > Standard Reports" for built-in reports on disk usage, index physical statistics, top queries by total CPU time, and more.

Activity Monitor (right-click the server name in Object Explorer and select "Activity Monitor") shows real-time data about processes, resource waits, data file I/O, and expensive queries. This is your first stop when something is slow. The "Recent Expensive Queries" pane shows the top queries by CPU, duration, physical reads, and logical writes. Click any query to see its execution plan.

Execution Plans are the single most important diagnostic tool. Before running a query, press Ctrl+L to display the estimated execution plan without actually executing the query. Press Ctrl+M to enable "Include Actual Execution Plan," then execute the query with F5 — the actual plan appears in a new tab showing real row counts, actual vs. estimated rows, memory grants, and other runtime statistics.

When reading an execution plan, read from right to left and top to bottom. The width of the arrows between operators indicates the relative number of rows flowing through. Look for large discrepancies between estimated and actual rows — these indicate stale statistics or cardinality estimation problems. Look for Key Lookups (a nonclustered index found the rows but needed to go back to the clustered index to fetch additional columns), which often suggest adding included columns to the nonclustered index. Look for Table Scans and Clustered Index Scans on large tables, which may indicate missing indexes or non-sargable WHERE clauses.

Right-click any operator in the plan to see its properties, including the output list (columns it produces), predicates, memory fractions, estimated CPU and I/O cost, and the actual number of rows vs. estimated. Hover over the thick arrows to see the number of rows.

Include Live Query Statistics (Ctrl+Alt+L before executing) shows the execution plan with real-time progress animation — you can literally watch rows flow through the operators as the query runs. This is invaluable for long-running queries because you can see exactly where the query is spending time without waiting for it to finish.

Query Store UI is accessed by expanding a database in Object Explorer, then expanding "Query Store." Here you find built-in reports: Top Resource Consuming Queries, Regressed Queries, Overall Resource Consumption, and Forced Plans. The Regressed Queries view is particularly useful — it shows queries whose performance has degraded compared to historical execution, and lets you force a previous, better-performing plan with a single click. This is one of the most powerful features in SQL Server for application developers who deploy code changes and notice performance degradation.

Template Explorer (Ctrl+Alt+T) provides pre-built T-SQL templates for common tasks like creating indexes, adding constraints, or configuring replication. Each template has placeholder parameters that SSMS highlights for you to fill in.

SQLCMD Mode in SSMS lets you use sqlcmd-specific commands directly in the query editor. Enable it from the Query menu. In SQLCMD mode, you can use :CONNECT to connect to a different server mid-script, :r to include external script files, and scripting variables with $(VariableName) syntax. This is useful for deployment scripts that target multiple servers.

Multi-Server Queries: You can register multiple servers in the "Registered Servers" window (Ctrl+Alt+G), create server groups, and then execute a query simultaneously against all servers in a group. The results come back with an additional column showing which server produced each row.

Keyboard Shortcuts: F5 executes the selected text (or the entire batch if nothing is selected). Ctrl+E also executes. Ctrl+L shows the estimated plan. Ctrl+K, Ctrl+C comments the selection, Ctrl+K, Ctrl+U uncomments. Ctrl+Shift+U uppercases the selection, Ctrl+Shift+L lowercases. Alt+F1 with a table name selected runs sp_help on it. Ctrl+R toggles the results pane. Ctrl+T switches results to text mode (which is often more readable for narrow result sets). Ctrl+D switches results to grid mode.

Snippets: SSMS supports code snippets. Press Ctrl+K, Ctrl+X to insert a snippet. You can create custom snippets for your frequently-used T-SQL patterns by adding XML files to the snippets directory.

Search: SSMS 21 and 22 include a search bar at the top (Ctrl+Q) with two modes — Feature Search (find SSMS settings and commands) and Code Search (find strings in files, folders, or repositories). Feature Search is particularly handy when you cannot remember where a setting lives — just type "line numbers" and it shows you the option to toggle line numbers on or off.

Tabs: SSMS 21/22 supports multi-row tabs and configurable tab positions (top, left, or right). Right-click on a tab strip and choose "Set Tab Layout" to change this. With dozens of query windows open, multi-row tabs are a sanity saver.

Git Integration: SSMS 21/22 includes Git and GitHub integration. You can initialize a local repository, commit script changes, push to GitHub, and track historical changes to your SQL files directly within SSMS. This is accessible from the Git menu. For teams that version-control their database scripts, this eliminates the need to switch to a separate Git client.

SQL Profiler and Extended Events

SQL Profiler is the legacy tracing tool included with SSMS. Launch it from Tools > SQL Server Profiler. It lets you capture a real-time stream of events happening on the server: query executions, RPC calls, logins, errors, deadlocks, and more.

To use SQL Profiler effectively: create a new trace, connect to your server, and in the "Events Selection" tab, be selective about what you capture. Capturing everything will generate massive amounts of data and impose significant overhead on the server. For a typical debugging session, include these events:

• SQL:BatchCompleted — captures the text of each completed batch along with duration, CPU, reads, and writes
• RPC:Completed — captures stored procedure calls (this is what you see from parameterized queries sent by EF Core or Dapper)
• Showplan XML — captures the actual execution plan for each query (high overhead, use sparingly)
• Deadlock graph — captures the XML deadlock graph whenever a deadlock occurs

In the "Column Filters" tab, filter by DatabaseName (to avoid capturing system database activity), Duration (set a minimum to only capture slow queries), and ApplicationName (to isolate traffic from your specific application).

Important: SQL Profiler is deprecated. Microsoft recommends using Extended Events instead. However, Profiler remains included in SSMS and is still the quickest way to answer "what queries is my application actually sending to the server?" during development. Just do not run Profiler against a production server under heavy load — the overhead is real and can cause performance problems.

Extended Events (XEvents) is the modern replacement for Profiler. It is built into the SQL Server engine and has dramatically lower overhead. In SSMS, expand your server in Object Explorer, go to Management > Extended Events > Sessions. You can create new sessions through the GUI (New Session Wizard or New Session dialog) or with T-SQL.

A common Extended Events session for development captures slow queries:

CREATE EVENT SESSION [SlowQueries] ON SERVER
ADD EVENT sqlserver.sql_batch_completed (
    SET collect_batch_text = 1
    ACTION (
        sqlserver.sql_text,
        sqlserver.database_name,
        sqlserver.client_app_name,
        sqlserver.session_id
    )
    WHERE duration > 1000000  -- 1 second in microseconds
)
ADD TARGET package0.event_file (
    SET filename = N'SlowQueries.xel',
        max_file_size = 50  -- MB
)
WITH (
    MAX_MEMORY = 4096 KB,
    EVENT_RETENTION_MODE = ALLOW_SINGLE_EVENT_LOSS,
    MAX_DISPATCH_LATENCY = 5 SECONDS,
    STARTUP_STATE = ON
);
GO

ALTER EVENT SESSION [SlowQueries] ON SERVER STATE = START;

You can then view the captured events by right-clicking the session in Object Explorer and choosing "Watch Live Data" for a real-time feed, or double-clicking the event file target to open captured data in the SSMS viewer with full filtering and grouping capabilities.

For deadlock analysis, SQL Server maintains a built-in Extended Events session called system_health that captures deadlock graphs among other diagnostic events. You can query it:

SELECT
    xdr.value('@timestamp', 'datetime2') AS deadlock_time,
    xdr.query('.') AS deadlock_graph
FROM (
    SELECT CAST(target_data AS XML) AS target_data
    FROM sys.dm_xe_session_targets st
    JOIN sys.dm_xe_sessions s ON s.address = st.event_session_address
    WHERE s.name = 'system_health'
      AND st.target_name = 'ring_buffer'
) AS data
CROSS APPLY target_data.nodes('//RingBufferTarget/event[@name="xml_deadlock_report"]') AS XEventData(xdr);

Part 3: Working with SQL Server from the Terminal

Not every interaction with SQL Server requires opening SSMS. For scripting, automation, CI/CD pipelines, and quick checks, the command line is often faster.

sqlcmd — The Classic and the Modern

There are two variants of sqlcmd:

sqlcmd (ODBC) is the traditional command-line utility that ships with SQL Server and the ODBC driver. It has been around for decades.

sqlcmd (Go) — also called go-sqlcmd — is the modern, cross-platform replacement built on the go-mssqldb driver. It runs on Windows, macOS, and Linux. It is open source under the MIT license. Install it with:

winget install sqlcmd

Or on macOS:

brew install sqlcmd

Or on Linux via the Microsoft package repository. The Go variant supports all the same commands as the ODBC version plus additional features: syntax coloring in the terminal, vertical result format (much easier to read wide rows), Docker container management (sqlcmd create mssql spins up a SQL Server container), and broader Microsoft Entra authentication support.

Connecting

Connect with Windows Authentication to a local default instance:

sqlcmd -S localhost -E

Connect with SQL Authentication:

sqlcmd -S myserver.database.windows.net -U myuser

The Go variant no longer accepts -P on the command line for the password (security improvement). It prompts you, or you can set the SQLCMDPASSWORD environment variable.

Connect to a named instance:

sqlcmd -S localhost\SQLEXPRESS

Connect using a specific protocol:

sqlcmd -S tcp:myserver,1433
sqlcmd -S np:\\myserver\pipe\sql\query

Running Queries

Interactive mode:

1> SELECT name, database_id FROM sys.databases;
2> GO

The GO keyword is the batch terminator — it tells sqlcmd to send everything typed so far to the server. GO is not a T-SQL keyword; it is a client-side command recognized by sqlcmd and SSMS.

Run a single query and exit:

sqlcmd -S localhost -d MyDatabase -Q "SELECT TOP 10 * FROM Customers"

Run a script file:

sqlcmd -S localhost -d MyDatabase -i deploy_schema.sql -o results.txt

Run multiple script files in order:

sqlcmd -S localhost -i schema.sql data.sql indexes.sql

Use scripting variables:

sqlcmd -S localhost -v DatabaseName="Production" -i create_db.sql

In the script, reference the variable as $(DatabaseName).

Piping and Automation

You can pipe SQL directly:

echo "SELECT @@VERSION" | sqlcmd -S localhost

This is useful in shell scripts and CI pipelines. When piping input, GO batch terminators are optional — sqlcmd automatically executes the batch when input ends.

Checking Your Connection

Once connected, useful diagnostic queries:

-- What version am I connected to?
SELECT @@VERSION;
GO

-- What protocol am I using?
SELECT net_transport
FROM sys.dm_exec_connections
WHERE session_id = @@SPID;
GO

-- What database am I in?
SELECT DB_NAME();
GO

-- What login am I?
SELECT SUSER_SNAME();
GO

PowerShell Integration

The Invoke-Sqlcmd cmdlet (part of the SqlServer PowerShell module) lets you run queries from PowerShell:

Install-Module -Name SqlServer
Invoke-Sqlcmd -ServerInstance "localhost" -Database "MyDb" -Query "SELECT TOP 5 * FROM Products"

The SqlServer module also includes cmdlets for backup, restore, reading error logs, and managing availability groups.

Docker for Development

The Go sqlcmd can spin up a SQL Server container in seconds:

sqlcmd create mssql --accept-eula --tag 2025-latest

This pulls the SQL Server 2025 container image, starts it, and connects sqlcmd to it. You can also restore a sample database in the same command:

sqlcmd create mssql --accept-eula --tag 2025-latest --using https://github.com/Microsoft/sql-server-samples/releases/download/wide-world-importers-v1.0/WideWorldImporters-Full.bak

For .NET developers, this is the fastest way to get a throwaway SQL Server instance for integration tests.

Part 4: T-SQL Deep Dive

T-SQL (Transact-SQL) is Microsoft's extension of the SQL standard. As a .NET developer, even if you primarily use EF Core, you need to understand T-SQL for performance tuning, debugging, migrations, and anything that EF Core does not express cleanly.

Data Types — Choosing Correctly

Use the narrowest appropriate data type. INT when you need 4 bytes, BIGINT when you need 8, SMALLINT or TINYINT when values fit. For monetary values, use DECIMAL(19,4) or MONEY — never FLOAT or REAL, which have floating-point precision issues. For dates, use DATE if you only need the date, DATETIME2(0) through DATETIME2(7) for date and time (with 0 to 7 fractional second digits), and DATETIMEOFFSET when you need timezone awareness. Avoid DATETIME for new development — it has only 3.33ms precision and wastes storage compared to DATETIME2.

For string columns, prefer NVARCHAR for user-facing text that may include international characters, and VARCHAR for ASCII-only data or when you use a UTF-8 collation (available since SQL Server 2019). Always specify a length — NVARCHAR(100) not NVARCHAR(MAX) — unless you truly need more than 4,000 characters. MAX columns cannot be part of an index key and have different storage behavior.

For SQL Server 2025, the new JSON data type stores JSON more efficiently than NVARCHAR(MAX). The VECTOR data type stores embedding vectors for AI/ML workloads.

Common Table Expressions (CTEs)

CTEs make complex queries readable:

WITH ActiveCustomers AS (
    SELECT CustomerID, Name, Email
    FROM Customers
    WHERE IsActive = 1
      AND LastOrderDate > DATEADD(MONTH, -6, GETDATE())
),
OrderTotals AS (
    SELECT CustomerID, SUM(TotalAmount) AS LifetimeValue
    FROM Orders
    GROUP BY CustomerID
)
SELECT ac.Name, ac.Email, ot.LifetimeValue
FROM ActiveCustomers ac
JOIN OrderTotals ot ON ac.CustomerID = ot.CustomerID
WHERE ot.LifetimeValue > 1000
ORDER BY ot.LifetimeValue DESC;

Recursive CTEs are indispensable for hierarchical data:

WITH OrgChart AS (
    -- Anchor: top-level managers
    SELECT EmployeeID, Name, ManagerID, 0 AS Level
    FROM Employees
    WHERE ManagerID IS NULL

    UNION ALL

    -- Recursive: subordinates
    SELECT e.EmployeeID, e.Name, e.ManagerID, oc.Level + 1
    FROM Employees e
    JOIN OrgChart oc ON e.ManagerID = oc.EmployeeID
)
SELECT * FROM OrgChart
ORDER BY Level, Name
OPTION (MAXRECURSION 100);

Window Functions

Window functions compute values across a set of rows related to the current row without collapsing the result set:

SELECT
    OrderID,
    CustomerID,
    OrderDate,
    TotalAmount,
    SUM(TotalAmount) OVER (
        PARTITION BY CustomerID
        ORDER BY OrderDate
        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
    ) AS RunningTotal,
    ROW_NUMBER() OVER (
        PARTITION BY CustomerID
        ORDER BY OrderDate DESC
    ) AS RecentOrderRank,
    LAG(TotalAmount) OVER (
        PARTITION BY CustomerID
        ORDER BY OrderDate
    ) AS PreviousOrderAmount,
    LEAD(TotalAmount) OVER (
        PARTITION BY CustomerID
        ORDER BY OrderDate
    ) AS NextOrderAmount
FROM Orders;

The ROWS BETWEEN clause controls the window frame. RANGE BETWEEN is subtly different — it treats ties as part of the same frame. In SQL Server 2022 and later, the WINDOW clause lets you define named window specifications and reuse them:

SELECT
    OrderID,
    CustomerID,
    SUM(TotalAmount) OVER w AS RunningTotal,
    AVG(TotalAmount) OVER w AS RunningAvg
FROM Orders
WINDOW w AS (
    PARTITION BY CustomerID
    ORDER BY OrderDate
    ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
);

MERGE Statement

MERGE performs insert, update, and delete in a single atomic statement based on a source/target comparison:

MERGE INTO Products AS target
USING StagingProducts AS source
ON target.SKU = source.SKU
WHEN MATCHED AND target.Price <> source.Price THEN
    UPDATE SET target.Price = source.Price, target.UpdatedAt = GETUTCDATE()
WHEN NOT MATCHED BY TARGET THEN
    INSERT (SKU, Name, Price, CreatedAt)
    VALUES (source.SKU, source.Name, source.Price, GETUTCDATE())
WHEN NOT MATCHED BY SOURCE THEN
    DELETE;

Always include the semicolon after MERGE — it is one of the few T-SQL statements that requires a terminating semicolon.

Error Handling

Use TRY...CATCH blocks:

BEGIN TRY
    BEGIN TRANSACTION;

    UPDATE Accounts SET Balance = Balance - 500 WHERE AccountID = 1;
    UPDATE Accounts SET Balance = Balance + 500 WHERE AccountID = 2;

    COMMIT TRANSACTION;
END TRY
BEGIN CATCH
    IF @@TRANCOUNT > 0
        ROLLBACK TRANSACTION;

    DECLARE @ErrorMessage NVARCHAR(4000) = ERROR_MESSAGE();
    DECLARE @ErrorSeverity INT = ERROR_SEVERITY();
    DECLARE @ErrorState INT = ERROR_STATE();
    DECLARE @ErrorLine INT = ERROR_LINE();
    DECLARE @ErrorProcedure NVARCHAR(200) = ERROR_PROCEDURE();

    -- Log the error
    INSERT INTO ErrorLog (Message, Severity, State, Line, Procedure, OccurredAt)
    VALUES (@ErrorMessage, @ErrorSeverity, @ErrorState, @ErrorLine, @ErrorProcedure, GETUTCDATE());

    -- Re-raise
    THROW;
END CATCH;

THROW (introduced in SQL Server 2012) is preferred over RAISERROR for re-raising errors because it preserves the original error number, severity, and state. Use RAISERROR when you need to raise a custom error with a specific severity level.

String Functions — Old and New

SQL Server 2022 and 2025 added string functions that developers had been requesting for years:

-- TRIM (SQL Server 2017+)
SELECT TRIM('   hello   ');  -- 'hello'
SELECT TRIM('xy' FROM 'xyhelloyx');  -- 'hello' (SQL Server 2022+)

-- STRING_AGG (SQL Server 2017+)
SELECT DepartmentID, STRING_AGG(Name, ', ') AS Employees
FROM Employees
GROUP BY DepartmentID;

-- STRING_SPLIT with ordinal (SQL Server 2022+)
SELECT value, ordinal
FROM STRING_SPLIT('a,b,c', ',', 1);

-- GREATEST and LEAST (SQL Server 2022+)
SELECT GREATEST(10, 20, 5);   -- 20
SELECT LEAST(10, 20, 5);      -- 5

-- DATETRUNC (SQL Server 2022+)
SELECT DATETRUNC(MONTH, GETDATE());  -- First day of current month

-- GENERATE_SERIES (SQL Server 2022+)
SELECT value FROM GENERATE_SERIES(1, 10);
SELECT value FROM GENERATE_SERIES(1, 100, 5);  -- Step by 5

In SQL Server 2025, REGEX functions allow true regular expression matching without CLR:

-- SQL Server 2025
SELECT *
FROM Customers
WHERE REGEX_LIKE(Email, '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$');

Part 5: Transactions — Understanding the Fundamentals

Transactions are the mechanism that ensures data integrity. Every .NET developer must understand them.

ACID Properties

Atomicity: All statements in a transaction succeed or all are rolled back. There is no partial commit. Consistency: The database moves from one valid state to another. Constraints, triggers, and cascades are enforced. Isolation: Concurrent transactions do not interfere with each other (the degree depends on the isolation level). Durability: Once committed, the data survives a crash — it is written to the transaction log on disk before the commit completes.

Implicit vs. Explicit Transactions

By default, SQL Server operates in auto-commit mode: each individual statement is its own transaction. When you run UPDATE Customers SET Name = 'Alice' WHERE CustomerID = 1, SQL Server implicitly wraps it in a transaction, executes it, and commits. If the statement fails, it is automatically rolled back.

Explicit transactions use BEGIN TRANSACTION, COMMIT, and ROLLBACK:

BEGIN TRANSACTION;

UPDATE Inventory SET Quantity = Quantity - 1 WHERE ProductID = 42;
INSERT INTO OrderItems (OrderID, ProductID, Quantity) VALUES (100, 42, 1);

COMMIT TRANSACTION;

If any statement between BEGIN and COMMIT fails and you do not catch it, the transaction remains open. Always use TRY...CATCH with explicit transactions, and always check @@TRANCOUNT in the CATCH block.

Save Points

Within a transaction, you can set save points to enable partial rollback:

BEGIN TRANSACTION;

INSERT INTO Orders (CustomerID, OrderDate) VALUES (1, GETDATE());
SAVE TRANSACTION AfterOrderInsert;

BEGIN TRY
    INSERT INTO OrderItems (OrderID, ProductID, Quantity) VALUES (SCOPE_IDENTITY(), 99, 1);
END TRY
BEGIN CATCH
    -- Roll back only the failed insert, not the entire transaction
    ROLLBACK TRANSACTION AfterOrderInsert;
END CATCH;

COMMIT TRANSACTION;

Transaction Isolation Levels

This is where many bugs live. The isolation level controls what concurrent transactions can see.

READ UNCOMMITTED: The transaction can read data modified by other uncommitted transactions (dirty reads). This is the least restrictive level. Useful for rough estimates on data that is not critical.

READ COMMITTED (default): The transaction can only read data that has been committed. However, if you read the same row twice, it might have changed between reads (non-repeatable reads), and new rows matching your WHERE clause might appear (phantom reads).

REPEATABLE READ: Once a row is read, it cannot be modified by another transaction until the current transaction ends. This prevents non-repeatable reads but not phantom reads.

SERIALIZABLE: The most restrictive level. Range locks are placed on the data, preventing other transactions from inserting rows that would match the current transaction's WHERE clauses. This prevents dirty reads, non-repeatable reads, and phantom reads, but it causes the most blocking and the highest risk of deadlocks.

SNAPSHOT: Uses row versioning. When the transaction starts, it gets a consistent snapshot of the database as of that point in time. It can read without acquiring shared locks, so readers do not block writers and writers do not block readers. However, if the transaction tries to modify a row that has been modified by another transaction since the snapshot was taken, it gets an update conflict error.

READ COMMITTED SNAPSHOT ISOLATION (RCSI): A database-level option that changes the behavior of READ COMMITTED to use row versioning instead of shared locks. Readers get a snapshot as of the start of each individual statement (not the start of the transaction). This is the default behavior for Azure SQL Database and is strongly recommended for most OLTP workloads.

To enable RCSI:

ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON;

This requires exclusive access to the database (no other connections). For production databases, coordinate a brief maintenance window.

Transaction Best Practices

Keep transactions short. Every lock held by a transaction blocks other transactions. A transaction that holds locks for 30 seconds while calling an external API is a production incident waiting to happen. Do your external calls, computations, and validations outside the transaction, then enter the transaction only for the database writes.

Always set a transaction timeout in your application code:

using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();
using var transaction = await connection.BeginTransactionAsync();
// SqlCommand.CommandTimeout = 30 seconds by default

In EF Core:

using var transaction = await dbContext.Database.BeginTransactionAsync();
try
{
    // ... operations
    await dbContext.SaveChangesAsync();
    await transaction.CommitAsync();
}
catch
{
    await transaction.RollbackAsync();
    throw;
}

Part 6: Locking, Blocking, and Deadlocks

How Locking Works

SQL Server uses a multi-granularity locking system. Locks can be acquired at the row level, page level (8 KB), extent level (64 KB, 8 pages), table level, or database level. The engine starts with the finest granularity appropriate for the operation and may escalate to a coarser level if too many fine-grained locks are held (by default, escalation occurs at approximately 5,000 locks on a single table).

The main lock modes are: Shared (S) for reads, Exclusive (X) for writes, Update (U) for update operations (a transitional lock that converts to X when the actual modification happens), Intent locks (IS, IX, IU) that signal to higher-granularity lock checks that a finer-grained lock exists, and Schema locks (Sch-S and Sch-M) for DDL operations.

The NOLOCK Debate — Should You Use It?

WITH (NOLOCK) — equivalent to SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED for that table reference — is one of the most controversial hints in SQL Server.

What NOLOCK does: It tells SQL Server to read data without acquiring shared locks, and to ignore exclusive locks held by other transactions. This means the query will never be blocked by a writer and will never block a writer.

What can go wrong: Dirty reads (reading data from an uncommitted transaction that may later be rolled back — you would be working with data that never actually existed). Skipped rows or duplicate rows (if a page split occurs during an allocation order scan, the scan can miss rows that moved or encounter the same row twice). Errors (reading a page that is in the middle of being updated can cause incorrect column values or even errors).

Development environment: Using NOLOCK is generally acceptable during development for ad hoc queries where you want quick answers and do not care about perfect accuracy. Running SELECT COUNT(*) FROM LargeTable WITH (NOLOCK) to get a rough row count is fine.

Production reads: The answer depends on your workload. For a reporting query against a large table where an approximate result is acceptable and blocking readers would impact OLTP throughput, NOLOCK may be a pragmatic choice. But the better answer for most OLTP workloads is to enable Read Committed Snapshot Isolation (RCSI) at the database level. RCSI gives you non-blocking reads with transactional consistency — no dirty reads, no skipped or duplicate rows, no page-split anomalies. It costs some tempdb I/O for the version store, but this is almost always a good tradeoff.

Production writes: Never use NOLOCK on the target of an UPDATE or DELETE. It does not apply there anyway — write operations always acquire exclusive locks.

Recommendation: Enable RCSI on your databases and stop using NOLOCK. If you need historical consistency across multiple statements, use SNAPSHOT isolation.

Diagnosing Blocking

When queries hang, check for blocking:

-- Who is blocking whom?
SELECT
    blocking.session_id AS BlockingSessionID,
    blocked.session_id AS BlockedSessionID,
    blocked.wait_type,
    blocked.wait_time / 1000 AS WaitSeconds,
    blocked_sql.text AS BlockedQuery,
    blocking_sql.text AS BlockingQuery
FROM sys.dm_exec_requests blocked
JOIN sys.dm_exec_sessions blocking
    ON blocked.blocking_session_id = blocking.session_id
CROSS APPLY sys.dm_exec_sql_text(blocked.sql_handle) blocked_sql
OUTER APPLY sys.dm_exec_sql_text(blocking.most_recent_sql_handle) blocking_sql
WHERE blocked.blocking_session_id <> 0;

Deadlocks

A deadlock occurs when two or more transactions each hold a lock that the other needs. SQL Server automatically detects deadlocks (via the lock monitor thread, which runs every 5 seconds by default) and kills one of the transactions (the deadlock victim, chosen based on cost to roll back).

To minimize deadlocks: access tables in the same order in all transactions, keep transactions short, use the lowest necessary isolation level, and avoid user interaction mid-transaction. If deadlocks persist, use the deadlock graph (from Extended Events or the system_health session) to identify the specific resources and queries involved, then redesign the access patterns.

In your .NET code, always handle deadlocks with a retry loop:

const int maxRetries = 3;
for (int attempt = 1; attempt <= maxRetries; attempt++)
{
    try
    {
        await ExecuteTransactionAsync();
        return;
    }
    catch (SqlException ex) when (ex.Number == 1205) // Deadlock victim
    {
        if (attempt == maxRetries) throw;
        await Task.Delay(TimeSpan.FromMilliseconds(100 * attempt));
    }
}

SQL Server 2025 Optimized Locking

SQL Server 2025 introduces Transaction ID (TID) locking, which changes how row locks are handled after qualification. Instead of holding a row lock for the duration of the transaction, the engine can release it earlier and use a lighter-weight TID lock. This reduces lock memory consumption and contention, particularly for high-concurrency workloads. The behavior is automatic on SQL Server 2025 — you do not need to change queries or hints.

Part 7: Indexing Best Practices

Clustered Index

Every table should have a clustered index. The clustered index defines the physical order of data on disk. For most tables, the primary key — typically an INT IDENTITY or BIGINT IDENTITY — is the clustered index. This gives you sequential inserts (minimizing page splits), narrow keys (4 or 8 bytes — important because every nonclustered index carries a copy of the clustered index key), and unique values.

Using a GUID (UNIQUEIDENTIFIER) as a clustered index key is almost always a mistake. NEWID() generates random values, causing random inserts across the entire B-tree, which leads to massive page splits, fragmentation, and terrible I/O performance. NEWSEQUENTIALID() mitigates this somewhat but is still 16 bytes wide. Use GUIDs as nonclustered index columns if you need them for distributed identity, but keep the clustered key narrow and sequential.

Nonclustered Indexes

Design nonclustered indexes based on your query patterns, not your table structure. The key columns should be the columns in your WHERE clause and JOIN conditions, ordered from most selective to least selective. Include columns (in the INCLUDE clause) for columns that are only in the SELECT list — this prevents key lookups.

-- If your common query is:
SELECT OrderID, OrderDate, TotalAmount
FROM Orders
WHERE CustomerID = @CustID AND Status = 'Shipped'
ORDER BY OrderDate DESC;

-- Then create:
CREATE NONCLUSTERED INDEX IX_Orders_CustomerID_Status
ON Orders (CustomerID, Status)
INCLUDE (OrderDate, TotalAmount);

Filtered Indexes

If a column has a heavily skewed distribution (for example, 95% of rows have Status = 'Completed' and you only ever query for the other 5%), use a filtered index:

CREATE NONCLUSTERED INDEX IX_Orders_Pending
ON Orders (CustomerID, OrderDate)
INCLUDE (TotalAmount)
WHERE Status IN ('Pending', 'Processing', 'Shipped');

This index is smaller, faster to maintain, and uses less memory.

Columnstore Indexes

For analytical queries that scan large portions of a table, columnstore indexes provide order-of-magnitude performance improvements. They store data in a columnar format and use batch mode processing. You can add a nonclustered columnstore index alongside your rowstore indexes:

CREATE NONCLUSTERED COLUMNSTORE INDEX NCCI_Orders_Analytics
ON Orders (CustomerID, OrderDate, TotalAmount, Status);

Missing Index DMVs

SQL Server tracks queries that could benefit from an index:

SELECT
    mig.index_group_handle,
    mid.statement AS TableName,
    mid.equality_columns,
    mid.inequality_columns,
    mid.included_columns,
    migs.unique_compiles,
    migs.user_seeks,
    migs.avg_total_user_cost * migs.avg_user_impact * (migs.user_seeks + migs.user_scans) AS ImprovementScore
FROM sys.dm_db_missing_index_groups mig
JOIN sys.dm_db_missing_index_group_stats migs ON mig.index_group_handle = migs.group_handle
JOIN sys.dm_db_missing_index_details mid ON mig.index_handle = mid.index_handle
ORDER BY ImprovementScore DESC;

Do not blindly create every missing index — review them for overlap with existing indexes, consolidate where possible, and consider the write overhead of maintaining additional indexes.

Part 8: Networking, Sessions, and Connection Management

SQL Server Network Configuration

SQL Server listens on one or more network protocols: TCP/IP (the most common, default port 1433), Named Pipes (for local or intranet connections), and Shared Memory (local connections only). Configure these in SQL Server Configuration Manager.

For production, use TCP/IP exclusively. Ensure the firewall allows inbound connections on port 1433 (or your custom port). If you use a named instance, it uses a dynamic port assigned by the SQL Server Browser service (which listens on UDP 1434). For production named instances, assign a static port in Configuration Manager.

Connection Strings from .NET

A typical ASP.NET Core connection string:

Server=myserver.database.windows.net;Database=MyApp;User Id=myuser;Password=mypassword;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;

Key parameters to understand: Encrypt=True enables TLS encryption (mandatory for Azure SQL, strongly recommended for all production servers). TrustServerCertificate=False (the default) validates the server certificate — set this to True only for development with self-signed certificates. Connection Timeout=30 is the maximum time to wait for a connection from the pool. Max Pool Size=100 (default) is the maximum number of connections in the pool. MultipleActiveResultSets=True allows multiple open readers on a single connection (required by some EF Core patterns, but adds overhead).

Connection Pooling

ADO.NET (and by extension EF Core and Dapper) uses connection pooling by default. When you close a connection in code, it is returned to the pool — not actually closed. When you open a connection, the pool gives you an existing one if available. This is why it is critical to always dispose of SqlConnection objects promptly (use using statements).

If your application hits Max Pool Size and all connections are in use, the next OpenAsync() call will block until a connection is returned or the connection timeout expires, at which point you get a TimeoutException. This almost always means you have a connection leak — some code path is opening a connection without closing/disposing it.

Monitor pool usage:

SELECT
    DB_NAME(dbid) AS DatabaseName,
    COUNT(*) AS ConnectionCount,
    loginame AS LoginName,
    hostname AS HostName,
    program_name AS Application
FROM sys.sysprocesses
GROUP BY dbid, loginame, hostname, program_name
ORDER BY ConnectionCount DESC;

Or with the modern DMV:

SELECT
    s.session_id,
    s.login_name,
    s.host_name,
    s.program_name,
    c.connect_time,
    c.net_transport,
    c.protocol_type,
    c.encrypt_option,
    s.status,
    s.last_request_start_time,
    s.last_request_end_time,
    r.command,
    r.wait_type,
    r.blocking_session_id
FROM sys.dm_exec_sessions s
LEFT JOIN sys.dm_exec_connections c ON s.session_id = c.session_id
LEFT JOIN sys.dm_exec_requests r ON s.session_id = r.session_id
WHERE s.is_user_process = 1
ORDER BY s.last_request_start_time DESC;

Session Management

Every connection to SQL Server creates a session. Useful session-level settings:

SET NOCOUNT ON;              -- Suppress "N rows affected" messages (reduces network traffic)
SET XACT_ABORT ON;           -- Auto-rollback the transaction on any error
SET ARITHABORT ON;           -- Required for indexed views and computed columns
SET ANSI_NULLS ON;           -- NULL comparisons follow ANSI standard
SET QUOTED_IDENTIFIER ON;    -- Double quotes delimit identifiers, not strings

SET XACT_ABORT ON is particularly important. Without it, some errors (like constraint violations) leave the transaction open, and subsequent statements execute as if nothing happened. With XACT_ABORT ON, any error immediately rolls back the entire transaction. Always set this at the beginning of stored procedures.

Killing Sessions

If a session is blocking others and needs to be terminated:

KILL 52;  -- 52 is the session_id

Use this judiciously — killing a session that is mid-transaction causes a rollback, which can take time proportional to the work already done.

Part 9: Debugging Production Issues

Dynamic Management Views (DMVs)

DMVs are your primary diagnostic tool for production SQL Server. They expose internal state without the overhead of profiling.

Currently executing queries:

SELECT
    r.session_id,
    r.status,
    r.command,
    r.wait_type,
    r.wait_time,
    r.blocking_session_id,
    r.cpu_time,
    r.logical_reads,
    r.total_elapsed_time / 1000 AS ElapsedSeconds,
    SUBSTRING(t.text, r.statement_start_offset / 2 + 1,
        (CASE WHEN r.statement_end_offset = -1
            THEN LEN(CONVERT(NVARCHAR(MAX), t.text)) * 2
            ELSE r.statement_end_offset END - r.statement_start_offset) / 2 + 1
    ) AS CurrentStatement,
    p.query_plan
FROM sys.dm_exec_requests r
CROSS APPLY sys.dm_exec_sql_text(r.sql_handle) t
CROSS APPLY sys.dm_exec_query_plan(r.plan_handle) p
WHERE r.session_id > 50  -- Exclude system sessions
ORDER BY r.total_elapsed_time DESC;

Top queries by CPU (historical, from plan cache):

SELECT TOP 20
    qs.total_worker_time / qs.execution_count AS AvgCPU,
    qs.total_worker_time AS TotalCPU,
    qs.execution_count,
    qs.total_logical_reads / qs.execution_count AS AvgReads,
    SUBSTRING(t.text, qs.statement_start_offset / 2 + 1,
        (CASE WHEN qs.statement_end_offset = -1
            THEN LEN(CONVERT(NVARCHAR(MAX), t.text)) * 2
            ELSE qs.statement_end_offset END - qs.statement_start_offset) / 2 + 1
    ) AS QueryText
FROM sys.dm_exec_query_stats qs
CROSS APPLY sys.dm_exec_sql_text(qs.sql_handle) t
ORDER BY AvgCPU DESC;

Wait statistics (what is the server waiting on?):

SELECT TOP 20
    wait_type,
    waiting_tasks_count,
    wait_time_ms / 1000 AS WaitSeconds,
    signal_wait_time_ms / 1000 AS SignalWaitSeconds,
    (wait_time_ms - signal_wait_time_ms) / 1000 AS ResourceWaitSeconds
FROM sys.dm_os_wait_stats
WHERE wait_type NOT IN (
    'SLEEP_TASK', 'BROKER_TASK_STOP', 'BROKER_EVENTHANDLER',
    'CLR_AUTO_EVENT', 'CLR_MANUAL_EVENT', 'LAZYWRITER_SLEEP',
    'SQLTRACE_BUFFER_FLUSH', 'WAITFOR', 'XE_TIMER_EVENT',
    'BROKER_TO_FLUSH', 'BROKER_RECEIVE_WAITFOR', 'CHECKPOINT_QUEUE',
    'REQUEST_FOR_DEADLOCK_SEARCH', 'FT_IFTS_SCHEDULER_IDLE_WAIT',
    'XE_DISPATCHER_WAIT', 'LOGMGR_QUEUE', 'ONDEMAND_TASK_QUEUE',
    'DIRTY_PAGE_POLL', 'HADR_FILESTREAM_IOMGR_IOCOMPLETION',
    'SP_SERVER_DIAGNOSTICS_SLEEP'
)
AND waiting_tasks_count > 0
ORDER BY wait_time_ms DESC;

Common wait types and what they mean: PAGEIOLATCH_SH (waiting for a data page to be read from disk — indicates memory pressure or slow I/O), LCK_M_X or LCK_M_S (waiting for a lock — blocking), CXPACKET or CXCONSUMER (parallelism waits — often normal, but excessive amounts may indicate skewed parallelism), WRITELOG (waiting for the transaction log to be written to disk — check log disk performance), SOS_SCHEDULER_YIELD (CPU pressure — the server needs more CPU or query tuning).

Index Fragmentation

Check fragmentation for a specific table:

SELECT
    i.name AS IndexName,
    ps.avg_fragmentation_in_percent,
    ps.page_count,
    ps.record_count
FROM sys.dm_db_index_physical_stats(
    DB_ID(), OBJECT_ID('dbo.Orders'), NULL, NULL, 'LIMITED'
) ps
JOIN sys.indexes i ON ps.object_id = i.object_id AND ps.index_id = i.index_id
WHERE ps.page_count > 1000  -- Only look at indexes with meaningful size
ORDER BY ps.avg_fragmentation_in_percent DESC;

Below 10% fragmentation: do nothing. Between 10% and 30%: reorganize (ALTER INDEX ... REORGANIZE). Above 30%: rebuild (ALTER INDEX ... REBUILD). Reorganize is an online, incremental operation. Rebuild is more thorough but takes a schema lock (unless you use ONLINE = ON, which requires Enterprise edition or SQL Server 2025 Standard).

tempdb Monitoring

tempdb is a shared resource used for temporary tables, table variables, sort spill, hash join spill, version store (for RCSI and snapshot isolation), and internal engine operations. If tempdb runs out of space or has contention, everything on the server slows down.

SELECT
    SUM(unallocated_extent_page_count) * 8 / 1024 AS FreeSpaceMB,
    SUM(internal_object_reserved_page_count) * 8 / 1024 AS InternalObjectsMB,
    SUM(user_object_reserved_page_count) * 8 / 1024 AS UserObjectsMB,
    SUM(version_store_reserved_page_count) * 8 / 1024 AS VersionStoreMB
FROM sys.dm_db_file_space_usage;

Part 10: Best Practices Checklist for .NET Developers

Database Design

Always use schemas (dbo, sales, hr) to organize objects. Do not put everything in dbo. Use meaningful, consistent naming conventions — PascalCase for tables and columns is the most common in .NET shops. Every table gets a clustered primary key. Use foreign keys to enforce referential integrity — do not rely on application code alone. Add appropriate check constraints.

Stored Procedures vs. Inline SQL vs. EF Core

There is no universal answer. EF Core is excellent for CRUD operations, migrations, and applications where developer productivity matters most. Raw SQL (via Dapper or SqlCommand) is appropriate for complex queries, bulk operations, or performance-critical paths where you need full control over the T-SQL. Stored procedures are appropriate when you need to encapsulate complex business logic at the database layer, when security requirements mandate that the application cannot issue ad hoc SQL, or when you need to share logic across multiple applications.

If you use EF Core, always monitor the generated SQL using logging:

optionsBuilder.LogTo(Console.WriteLine, LogLevel.Information)
              .EnableSensitiveDataLogging();

Look for N+1 query patterns (a query for each item in a loop instead of a single query with Include), unnecessary columns being fetched (use Select projections), and queries that pull the entire table into memory instead of filtering at the database.

Connection Handling

Always use using statements or await using for connections, commands, and readers. Never hold a connection open across an HTTP request boundary (open late, close early). Do not increase Max Pool Size to mask a connection leak — find and fix the leak.

Parameterized Queries — Always

Never concatenate user input into SQL strings. Always use parameters:

// WRONG — SQL injection vulnerability
var sql = $"SELECT * FROM Users WHERE Name = '{userName}'";

// RIGHT
var sql = "SELECT * FROM Users WHERE Name = @Name";
cmd.Parameters.AddWithValue("@Name", userName);

// BETTER — explicit type
cmd.Parameters.Add("@Name", SqlDbType.NVarChar, 100).Value = userName;

EF Core handles parameterization automatically, but if you use FromSqlRaw, make sure to use parameter placeholders.

Monitoring and Alerting

Set up alerts for: long-running queries (over N seconds), deadlocks, tempdb space usage, log file growth, failed logins, and database integrity check failures (DBCC CHECKDB). Use SQL Server Agent alerts, Azure Monitor, or your preferred monitoring stack.

Run DBCC CHECKDB on a schedule. It detects physical and logical corruption. For large databases, run it weekly during a maintenance window. For critical databases, run it daily.

Backup and Recovery

Test your backups by restoring them. A backup you have never tested is not a backup — it is a hope. Understand the difference between full backups, differential backups (changes since the last full backup), and transaction log backups (changes since the last log backup). For point-in-time recovery, you need the full recovery model and a chain of log backups.

In your .NET application, handle transient failures (network blips, failovers) with retry policies. The Microsoft.Data.SqlClient library supports configurable retry logic.

Statistics

SQL Server uses statistics (histograms of data distribution) to make query plan decisions. If statistics are stale, the optimizer makes bad choices. Auto-update statistics is enabled by default, but it triggers only after approximately 20% of the rows have changed (with a lower threshold for larger tables in SQL Server 2016+ with trace flag 2371, which is default behavior in SQL Server 2022+).

For tables with skewed distributions or after large data loads, manually update statistics:

UPDATE STATISTICS dbo.Orders WITH FULLSCAN;

Or for all tables:

EXEC sp_updatestats;

Maintenance Plans

Set up regular maintenance: index reorganize/rebuild (weekly), statistics update (daily or after large data changes), DBCC CHECKDB (weekly), and cleanup of old backup files, job history, and maintenance plan reports. Ola Hallengren's maintenance solution (free, open source) is the gold standard for automated index and statistics maintenance.

Part 11: SQL Server from C# — Practical Patterns

Dapper for Performance-Critical Paths

using Dapper;

await using var connection = new SqlConnection(connectionString);
var orders = await connection.QueryAsync<Order>(
    @"SELECT OrderID, CustomerID, OrderDate, TotalAmount
      FROM Orders
      WHERE CustomerID = @CustomerId AND OrderDate > @Since",
    new { CustomerId = 42, Since = DateTime.UtcNow.AddMonths(-6) }
);

Bulk Operations

For inserting thousands of rows, do not use individual INSERT statements or even EF Core's AddRange. Use SqlBulkCopy:

using var bulkCopy = new SqlBulkCopy(connection, SqlBulkCopyOptions.TableLock, null);
bulkCopy.DestinationTableName = "dbo.StagingOrders";
bulkCopy.BatchSize = 10000;
await bulkCopy.WriteToServerAsync(dataTable);

For EF Core 7+, the ExecuteUpdate and ExecuteDelete methods generate set-based UPDATE and DELETE statements, avoiding the per-row overhead:

await dbContext.Orders
    .Where(o => o.Status == "Cancelled" && o.OrderDate < cutoff)
    .ExecuteDeleteAsync();

Resilience with Microsoft.Data.SqlClient

var options = new SqlRetryLogicOption
{
    NumberOfTries = 3,
    DeltaTime = TimeSpan.FromSeconds(1),
    MaxTimeInterval = TimeSpan.FromSeconds(20),
    TransientErrors = new[] { 1205, 49920, 49919 } // Deadlock, throttled, etc.
};
var retryProvider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

using var connection = new SqlConnection(connectionString);
connection.RetryLogicProvider = retryProvider;

Part 12: Security Essentials

Principle of Least Privilege

Your application's database login should have only the permissions it needs. Create a dedicated login and database user:

CREATE LOGIN AppUser WITH PASSWORD = 'StrongPassword123!';
CREATE USER AppUser FOR LOGIN AppUser;

-- Grant specific permissions
GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO AppUser;
-- Or for stored procedures:
GRANT EXECUTE ON SCHEMA::dbo TO AppUser;

Never use sa or db_owner for application connections.

Always Encrypted

For columns containing sensitive data (SSN, credit card numbers), use Always Encrypted. The encryption keys are managed by the client driver (your .NET application) and the database engine never sees the plaintext. Configure this through SSMS: right-click the database, choose Tasks > Manage Always Encrypted Keys, then right-click the table and choose Encrypt Columns.

In your connection string, add Column Encryption Setting=Enabled.

Row-Level Security

Create a predicate function and a security policy to filter rows based on the current user:

CREATE FUNCTION dbo.fn_TenantFilter(@TenantID INT)
RETURNS TABLE
WITH SCHEMABINDING
AS
    RETURN SELECT 1 AS Result
    WHERE @TenantID = CAST(SESSION_CONTEXT(N'TenantID') AS INT);

CREATE SECURITY POLICY dbo.TenantPolicy
ADD FILTER PREDICATE dbo.fn_TenantFilter(TenantID) ON dbo.Orders;

In your .NET middleware, set the session context for each request:

await using var cmd = connection.CreateCommand();
cmd.CommandText = "EXEC sp_set_session_context @key = N'TenantID', @value = @TenantID";
cmd.Parameters.AddWithValue("@TenantID", currentTenantId);
await cmd.ExecuteNonQueryAsync();

Transparent Data Encryption (TDE)

TDE encrypts the database files at rest — the data files, log files, and backups are encrypted on disk. Enable it in one command:

CREATE DATABASE ENCRYPTION KEY
WITH ALGORITHM = AES_256
ENCRYPTION BY SERVER CERTIFICATE MyServerCert;

ALTER DATABASE MyDatabase SET ENCRYPTION ON;

This is transparent to the application — no code changes needed.

Part 13: Performance Tuning Workflow

When a query is slow, follow this systematic approach:

1. Get the actual execution plan (Ctrl+M in SSMS, then F5).
2. Look at the actual vs. estimated rows for each operator. Large discrepancies indicate statistics problems.
3. Identify the most expensive operators (the ones with the highest percentage cost).
4. Check for Key Lookups — add INCLUDE columns to the relevant nonclustered index.
5. Check for Table Scans on large tables — determine if an index would help.
6. Check for implicit conversions — look for yellow warning triangles on operators. A common cause is comparing an NVARCHAR parameter against a VARCHAR column, which forces a scan because the engine must convert every row.
7. Check wait statistics for the specific query — is it waiting on I/O, locks, memory, or CPU?
8. Review the Query Store for plan regression — did this query used to be fast with a different plan?
9. Update statistics with FULLSCAN if they appear stale.
10. Consider rewriting the query — sometimes a different approach (replacing a correlated subquery with a JOIN, breaking a complex query into CTEs, or using EXISTS instead of IN) changes the plan dramatically.

Part 14: SQL Server 2025 AI Features for .NET Developers

SQL Server 2025 brings AI capabilities that .NET developers can use directly from their existing codebase.

Vector Search

Store and search embeddings directly in SQL Server:

CREATE TABLE Documents (
    DocumentID INT IDENTITY PRIMARY KEY,
    Title NVARCHAR(200),
    Content NVARCHAR(MAX),
    Embedding VECTOR(1536)  -- 1536 dimensions, matching OpenAI ada-002
);

-- Find similar documents by cosine similarity
SELECT TOP 10
    DocumentID,
    Title,
    VECTOR_DISTANCE('cosine', Embedding, @QueryEmbedding) AS Distance
FROM Documents
ORDER BY VECTOR_DISTANCE('cosine', Embedding, @QueryEmbedding);

From C#, generate the embedding using an AI service (Azure OpenAI, for example), then pass it as a parameter.

REST Endpoint Calls from T-SQL

Call external APIs directly from the database:

DECLARE @response NVARCHAR(MAX);
DECLARE @url NVARCHAR(4000) = 'https://api.example.com/enrich';

EXEC sp_invoke_external_rest_endpoint
    @url = @url,
    @method = 'POST',
    @payload = N'{"customerId": 42}',
    @response = @response OUTPUT;

This enables scenarios like data enrichment, webhook notifications, and AI model inference directly from T-SQL stored procedures.

Conclusion

SQL Server is a deep, powerful, and continuously evolving database engine. As a .NET developer, your relationship with SQL Server goes far beyond writing LINQ queries. Understanding how the engine works — from locking and transactions to execution plans and indexing — makes you a dramatically more effective developer. It is the difference between guessing why something is slow and knowing.

SQL Server 2025 is the most capable release yet, with native JSON, vector search, REGEX, optimized locking, and AI integration. SSMS 22 gives you a modern, 64-bit environment with Copilot assistance and first-class support for all these new features. The go-sqlcmd tool makes command-line interactions seamless across Windows, macOS, and Linux.

Invest the time to learn these tools and concepts. Your future self — debugging a production issue at 2 AM or optimizing a critical query path — will thank you.

TypeScript is a statically typed superset of JavaScript developed by Microsoft. Every valid JavaScript program is also a valid TypeScript program, but TypeScript adds optional type annotations, interfaces, generics, enums, and a rich compiler infrastructure that catches bugs before your code ever runs. Since its initial release in October 2012, TypeScript has grown from a niche experiment into the most popular language on GitHub, overtaking Python in August 2025 with 2.6 million monthly contributors.

This article is comprehensive by design. We will start with why TypeScript exists by examining the quirks and footguns of JavaScript that motivated its creation. We will walk through every major feature of the type system, explain every significant compiler option in tsconfig.json, trace the evolution of the language from version 1.0 through the just-released 6.0, and look ahead to the historic Go rewrite in TypeScript 7. Whether you are evaluating TypeScript for the first time, preparing to migrate a legacy codebase, or just want to understand the language at a deeper level, this guide is for you.

Part 1: Why TypeScript Exists — JavaScript's Quirks and Footguns

To understand TypeScript, you must first understand what JavaScript gets wrong. JavaScript was famously designed in ten days in 1995 by Brendan Eich at Netscape. It has evolved enormously since then, but many of its original design decisions remain baked into the language and cannot be changed without breaking the web.

Type Coercion

JavaScript is dynamically typed and performs implicit type coercion in ways that surprise almost everyone. When you use the == operator, JavaScript will attempt to convert both operands to the same type before comparing them. This produces results that are logically inconsistent:

"" == 0          // true
0 == "0"         // true
"" == "0"        // false — transitivity violated

[] == false      // true
[] == ![]        // true — an array equals not-itself

null == undefined // true
null == 0         // false
null == ""        // false

The + operator is particularly treacherous because it serves double duty as both addition and string concatenation:

1 + "2"          // "12" — string concatenation
1 - "2"          // -1   — numeric subtraction
"5" - 3          // 2    — numeric subtraction
"5" + 3          // "53" — string concatenation

What TypeScript does: TypeScript's type system catches many of these issues at compile time. If you declare a variable as number, the compiler will not let you accidentally concatenate it with a string without an explicit conversion. However, TypeScript does not change JavaScript's runtime behavior. If your types are wrong (because you used any or a type assertion), the coercion still happens at runtime.

The this Keyword

In most object-oriented languages, this always refers to the current instance. In JavaScript, this depends on how a function is called, not where it is defined:

const obj = {
  name: "Alice",
  greet() {
    console.log(this.name);
  }
};

obj.greet();          // "Alice"
const fn = obj.greet;
fn();                 // undefined — `this` is now the global object (or undefined in strict mode)

setTimeout(obj.greet, 100); // undefined — same problem

This is one of the most common sources of bugs in JavaScript, especially in event handlers and callbacks.

What TypeScript does: TypeScript introduced the this parameter syntax, allowing you to explicitly annotate what this should be inside a function. The compiler will then enforce it:

interface Obj {
  name: string;
  greet(this: Obj): void;
}

Arrow functions also help because they lexically capture this from the enclosing scope — and TypeScript understands this.

null and undefined

JavaScript has two "nothing" values: null and undefined. They are subtly different: undefined is the default value for uninitialized variables and missing function parameters, while null is an explicit assignment. Yet both are treated as falsy, and typeof null returns "object" (a famous bug from the original implementation that can never be fixed).

typeof undefined  // "undefined"
typeof null       // "object" — a bug since 1995

let x;
console.log(x);  // undefined
x = null;
console.log(x);  // null

What TypeScript does: With the strictNullChecks compiler option (enabled by strict: true), TypeScript treats null and undefined as distinct types that are not assignable to other types. This forces you to explicitly check for null before using a value, which eliminates an entire class of runtime errors.

Prototypal Inheritance

JavaScript uses prototypal inheritance rather than classical inheritance. Every object has an internal [[Prototype]] link to another object. The class keyword (introduced in ES2015) is syntactic sugar over this prototype chain. This leads to confusing behavior:

function Dog(name) {
  this.name = name;
}
Dog.prototype.speak = function() {
  return this.name + " barks";
};

const d = new Dog("Rex");
d.speak();        // "Rex barks"
Dog.speak();      // TypeError — speak is on the prototype, not the constructor

What TypeScript does: TypeScript fully supports the class syntax with compile-time enforcement of access modifiers (public, private, protected), abstract classes, and interface implementation. The class is still compiled to prototype-based JavaScript, but the type checker ensures correctness at development time.

Equality and Comparisons

JavaScript has two equality operators: == (abstract equality, with coercion) and === (strict equality, no coercion). Virtually every style guide recommends using === exclusively, but == still exists and is still used.

0 === ""          // false — different types
0 == ""           // true  — coercion

NaN === NaN       // false — NaN is not equal to itself
NaN == NaN        // false — still not equal

What TypeScript does: TypeScript does not prevent you from using ==, but many TypeScript-adjacent linters (ESLint with @typescript-eslint) can enforce ===. The type system helps by flagging comparisons between incompatible types.

Floating Point Arithmetic

JavaScript has only one number type: IEEE 754 double-precision floating point. There are no integers, no decimals, no BigDecimal. This leads to the classic:

0.1 + 0.2        // 0.30000000000000004
0.1 + 0.2 === 0.3 // false

What TypeScript does: TypeScript does not fix this. The number type is still a 64-bit float. However, TypeScript does support the bigint type (introduced in ES2020 and TypeScript 3.2), which provides arbitrary-precision integers. For decimal arithmetic, you still need a library.

Variable Hoisting and Scoping

Before ES2015, JavaScript only had function-scoped variables declared with var. Variables declared with var are "hoisted" to the top of their function, which means they exist before the line where they are declared:

console.log(x);  // undefined — not a ReferenceError!
var x = 5;

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// prints 3, 3, 3 — not 0, 1, 2

ES2015 introduced let and const with block scoping, which fixes most of these issues.

What TypeScript does: TypeScript supports let and const (and always has). When targeting older JavaScript versions, the compiler can down-level let and const to var with appropriate transformations. TypeScript also flags many hoisting-related bugs through control flow analysis.

Other Quirks Worth Knowing

There are many more JavaScript quirks that TypeScript developers should be aware of:

The arguments object is not a real array. It is array-like but lacks array methods like map and filter. TypeScript discourages its use and encourages rest parameters (...args) instead.

typeof is unreliable for complex types: typeof [] returns "object", typeof null returns "object", and typeof NaN returns "number".

Automatic semicolon insertion (ASI) means JavaScript sometimes inserts semicolons where you did not intend them, leading to subtle bugs:

function foo() {
  return
    { bar: 42 };
}
foo(); // undefined — JS inserted a semicolon after return

JavaScript objects are not hash maps. They have a prototype chain, so properties like constructor, toString, and __proto__ exist on every object. Using Map is safer for key-value storage.

Part 2: TypeScript's Type System — The Fundamentals

Now that we understand what JavaScript gets wrong, let us look at how TypeScript's type system works.

Basic Types

TypeScript provides types for all of JavaScript's primitives and adds a few of its own:

let isDone: boolean = false;
let decimal: number = 6;
let hex: number = 0xf00d;
let binary: number = 0b1010;
let octal: number = 0o744;
let big: bigint = 100n;
let color: string = "blue";
let nothing: null = null;
let notDefined: undefined = undefined;
let sym: symbol = Symbol("key");

TypeScript also has several types that do not exist in JavaScript:

any — Opts out of type checking entirely. Any value can be assigned to any, and any can be assigned to anything. Using any defeats the purpose of TypeScript and should be avoided.

unknown — The type-safe counterpart to any. You can assign any value to unknown, but you cannot do anything with an unknown value without first narrowing its type through a type guard. Introduced in TypeScript 3.0.

void — The return type of functions that do not return a value.

never — The type of values that never occur. A function that always throws an exception or has an infinite loop has return type never. It is also used for exhaustiveness checking.

Arrays and Tuples

Arrays can be typed in two equivalent ways:

let list1: number[] = [1, 2, 3];
let list2: Array<number> = [1, 2, 3];

Tuples are fixed-length arrays where each element has a known type:

let pair: [string, number] = ["hello", 42];
let first: string = pair[0];
let second: number = pair[1];

TypeScript 4.0 introduced variadic tuple types, allowing you to spread tuple types and create complex type-level operations on tuples. TypeScript 4.2 added rest elements in the middle of tuples, and labeled tuple elements for documentation:

type NamedPoint = [x: number, y: number, z: number];
type Head<T extends any[]> = T extends [infer H, ...any[]] ? H : never;

Interfaces and Type Aliases

Interfaces describe the shape of objects:

interface User {
  name: string;
  age: number;
  email?: string;          // optional
  readonly id: number;     // cannot be modified after creation
}

Type aliases can describe the same shapes, plus unions, intersections, primitives, tuples, and more:

type StringOrNumber = string | number;
type Point = { x: number; y: number };
type Result<T> = { success: true; data: T } | { success: false; error: string };

The practical difference between interfaces and type aliases has narrowed over the years. Interfaces can be extended with extends and merged across declarations (declaration merging). Type aliases can represent unions, intersections, conditional types, and mapped types. For object shapes, either works. For everything else, use type aliases.

Enums

TypeScript provides several kinds of enums:

// Numeric enum — auto-incremented from 0
enum Direction {
  Up,      // 0
  Down,    // 1
  Left,    // 2
  Right,   // 3
}

// String enum — each member must be initialized
enum Color {
  Red = "RED",
  Green = "GREEN",
  Blue = "BLUE",
}

// Const enum — inlined at compile time, no runtime object
const enum Status {
  Active = "ACTIVE",
  Inactive = "INACTIVE",
}

Enums are one of the few TypeScript features that have runtime semantics — they generate JavaScript code (unless they are const enums). This is important because Node.js's type-stripping mode (--experimental-strip-types) cannot handle constructs with runtime semantics. TypeScript 5.8 introduced the --erasableSyntaxOnly flag to enforce that your code uses only syntax that can be erased without changing behavior.

Many TypeScript developers avoid enums entirely and use string literal unions instead:

type Direction = "up" | "down" | "left" | "right";

This approach has no runtime overhead and works with type stripping.

Union and Intersection Types

Union types represent a value that can be one of several types:

function formatId(id: string | number): string {
  if (typeof id === "string") {
    return id.toUpperCase();
  }
  return id.toString();
}

Intersection types combine multiple types into one:

type Timestamped = { createdAt: Date; updatedAt: Date };
type Named = { name: string };
type TimestampedUser = Named & Timestamped;

Literal Types and Narrowing

TypeScript can narrow types to specific literal values:

type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";

function request(method: HttpMethod, url: string): void {
  // method is constrained to exactly these four strings
}

TypeScript performs control flow analysis to narrow types within conditional blocks:

function example(x: string | number | null) {
  if (x === null) {
    // x is null here
    return;
  }
  if (typeof x === "string") {
    // x is string here
    console.log(x.toUpperCase());
  } else {
    // x is number here
    console.log(x.toFixed(2));
  }
}

This narrowing works with typeof, instanceof, in, equality checks, truthiness checks, and user-defined type guards.

Type Guards and Type Predicates

You can define custom type guards using the is keyword:

interface Fish { swim(): void }
interface Bird { fly(): void }

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

function move(pet: Fish | Bird) {
  if (isFish(pet)) {
    pet.swim(); // TypeScript knows pet is Fish
  } else {
    pet.fly();  // TypeScript knows pet is Bird
  }
}

TypeScript 5.5 introduced inferred type predicates, where the compiler can automatically infer x is T return types for simple guard functions without you writing the annotation explicitly.

The satisfies Operator

Introduced in TypeScript 4.9, satisfies lets you validate that an expression matches a type without widening it:

type Colors = Record<string, [number, number, number] | string>;

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Colors;

// palette.red is still [number, number, number], not string | [number, number, number]
palette.red.map(c => c * 2); // works — type is preserved

Without satisfies, annotating the variable as Colors would widen each property to string | [number, number, number], losing the specific type information.

Part 3: Advanced Type System Features

TypeScript has one of the most sophisticated type systems of any mainstream language. This section covers the advanced features that enable complex type-level programming.

Generics

Generics let you write functions, classes, and types that work with any type while preserving type information:

function identity<T>(arg: T): T {
  return arg;
}

let output = identity("hello"); // output is string
let num = identity(42);          // num is number

You can constrain generics with extends:

function getLength<T extends { length: number }>(arg: T): number {
  return arg.length;
}

getLength("hello");     // 5
getLength([1, 2, 3]);   // 3
getLength(42);           // Error — number doesn't have length

Generic defaults let you provide fallback types:

interface ApiResponse<T = unknown> {
  data: T;
  status: number;
}

Conditional Types

Conditional types select one of two types based on a condition:

type IsString<T> = T extends string ? true : false;

type A = IsString<"hello">;  // true
type B = IsString<42>;       // false

The infer keyword lets you extract types within conditional types:

type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
type ArrayElement<T> = T extends (infer E)[] ? E : never;

type R = ReturnType<() => string>;     // string
type E = ArrayElement<number[]>;       // number

Conditional types distribute over unions:

type ToArray<T> = T extends any ? T[] : never;
type Distributed = ToArray<string | number>; // string[] | number[]

Mapped Types

Mapped types create new types by transforming each property of an existing type:

type Readonly<T> = { readonly [K in keyof T]: T[K] };
type Partial<T> = { [K in keyof T]?: T[K] };
type Required<T> = { [K in keyof T]-?: T[K] };

// Key remapping (TypeScript 4.1)
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K]
};

interface Person { name: string; age: number; }
type PersonGetters = Getters<Person>;
// { getName: () => string; getAge: () => number }

Template Literal Types

Introduced in TypeScript 4.1, template literal types let you build string types from other types:

type EventName = `${"click" | "focus" | "blur"}${"" | "Capture"}`;
// "click" | "clickCapture" | "focus" | "focusCapture" | "blur" | "blurCapture"

type PropEventSource<T> = {
  on<K extends string & keyof T>(
    eventName: `${K}Changed`,
    callback: (newValue: T[K]) => void
  ): void;
};

TypeScript provides built-in string manipulation types: Uppercase, Lowercase, Capitalize, and Uncapitalize.

Utility Types

TypeScript ships with a rich set of built-in utility types:

Partial<T> makes all properties optional. Required<T> makes all properties required. Readonly<T> makes all properties read-only. Record<K, T> creates an object type with keys of type K and values of type T. Pick<T, K> selects a subset of properties from T. Omit<T, K> removes properties from T. Exclude<T, U> removes types from a union. Extract<T, U> extracts types from a union. NonNullable<T> removes null and undefined. ReturnType<T> extracts a function's return type. Parameters<T> extracts a function's parameter types as a tuple. ConstructorParameters<T> extracts constructor parameters. InstanceType<T> extracts the instance type of a constructor. Awaited<T> unwraps a Promise (introduced in TypeScript 4.5). NoInfer<T> prevents inference on a type parameter (introduced in TypeScript 5.4).

Discriminated Unions

Also called tagged unions, discriminated unions are one of the most powerful patterns in TypeScript:

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rectangle"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rectangle":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
  }
}

TypeScript narrows the type in each case branch, giving you access to the properties specific to that variant. If you add a new variant to the union and forget to handle it, you can use the never type for exhaustiveness checking:

function assertNever(x: never): never {
  throw new Error(`Unexpected value: ${x}`);
}

// Add default: return assertNever(shape); to catch unhandled cases

using and Explicit Resource Management

TypeScript 5.2 added support for the TC39 Explicit Resource Management proposal (the using keyword):

function processFile() {
  using file = openFile("data.txt");
  // file is automatically disposed when the block exits
  return file.read();
} // file[Symbol.dispose]() called here

async function processStream() {
  await using stream = openStream("data.txt");
  // stream is automatically disposed asynchronously
  return await stream.read();
} // stream[Symbol.asyncDispose]() called here

This is similar to C#'s using statement or Python's with statement. It ensures resources like file handles, database connections, and locks are properly cleaned up.

Decorators

TypeScript has long supported experimental decorators (the legacy syntax), but TypeScript 5.0 introduced support for the TC39 Stage 3 decorators proposal, which has a different API:

function logged(originalMethod: any, context: ClassMethodDecoratorContext) {
  const methodName = String(context.name);
  function replacementMethod(this: any, ...args: any[]) {
    console.log(`Calling ${methodName}`);
    const result = originalMethod.call(this, ...args);
    console.log(`${methodName} returned ${result}`);
    return result;
  }
  return replacementMethod;
}

class Calculator {
  @logged
  add(a: number, b: number): number {
    return a + b;
  }
}

TypeScript 5.9 stabilized the TC39 Decorator Metadata proposal, enabling frameworks to build richer metadata-driven APIs.

const Type Parameters

Introduced in TypeScript 5.0, the const modifier on type parameters infers literal types instead of their widened base types:

function routes<const T extends readonly string[]>(paths: T): T {
  return paths;
}

const r = routes(["home", "about", "contact"]);
// r is readonly ["home", "about", "contact"], not string[]

Variance Annotations

TypeScript 4.7 introduced explicit variance annotations for type parameters: in for contravariance and out for covariance:

interface Producer<out T> {
  produce(): T;
}

interface Consumer<in T> {
  consume(value: T): void;
}

These annotations help TypeScript check assignability more efficiently and catch variance errors at the declaration site rather than at usage sites.

Part 4: The tsconfig.json Reference

The tsconfig.json file controls how the TypeScript compiler behaves. It contains hundreds of options organized into several categories. Here is a comprehensive reference of the most important ones.

Project Configuration

files specifies an explicit list of files to include. include uses glob patterns to match files. exclude removes files from the include set. extends inherits configuration from another tsconfig file. references declares project references for composite builds.

Target and Output

target specifies the ECMAScript version for the output JavaScript. Valid values include es5, es6/es2015, es2016 through es2025, and esnext. As of TypeScript 6.0, the default is es2025 and ES5 is deprecated. module specifies the module system for the output: commonjs, esnext, nodenext, preserve, and others. As of TypeScript 6.0, the default is esnext. The legacy values amd, umd, and systemjs are deprecated. lib specifies which built-in type declarations to include: dom, dom.iterable, es2015 through es2025, esnext, and specific feature libraries like es2015.promise. outDir specifies the output directory for compiled files. outFile concatenated all output into a single file but has been removed in TypeScript 6.0 — use a bundler instead. rootDir specifies the root directory of source files, controlling the output directory structure. declaration generates .d.ts declaration files alongside JavaScript output. declarationDir specifies a separate output directory for declaration files. declarationMap generates source maps for declaration files, enabling "go to source" in editors. sourceMap generates .map files for debugging. inlineSourceMap embeds source maps inside the generated JavaScript. inlineSources embeds the TypeScript source inside the source map. removeComments strips comments from the output. noEmit runs type checking without generating any output files. emitDeclarationOnly only emits .d.ts files, no JavaScript.

Module Resolution

moduleResolution controls how TypeScript finds modules. The values are node16/nodenext (follows Node.js resolution rules including exports in package.json), bundler (designed for use with Vite, Webpack, esbuild, and similar tools), and the legacy node (which is deprecated in TypeScript 6.0 as node10). baseUrl sets a base directory for non-relative module imports. Deprecated in TypeScript 6.0 — use paths instead. paths maps import specifiers to file locations. Only affects TypeScript's type checking, not the emitted JavaScript. resolveJsonModule allows importing .json files and generates types from their structure. allowImportingTsExtensions allows imports to include .ts, .mts, and .cts extensions. Requires noEmit or emitDeclarationOnly. verbatimModuleSyntax enforces that imports and exports are written exactly as they will be emitted — no transformation. If a require would be emitted, you must write require. If an import would be emitted, you must write import. moduleDetection controls how TypeScript detects whether a file is a module or script. The value force treats all files as modules. esModuleInterop enables compatible interop between CommonJS and ES modules by generating helper functions. allowSyntheticDefaultImports allows default imports from modules that do not have a default export, for type-checking purposes only. isolatedModules ensures each file can be safely processed in isolation (as transpilers like Babel and SWC do). isolatedDeclarations ensures each file can generate its own declaration file without requiring type information from other files. Useful for parallel declaration emit in large projects. Introduced in TypeScript 5.5.

Strict Type Checking

strict is an umbrella flag that enables all strict type-checking options. As of TypeScript 6.0, this defaults to true. The individual flags it controls are:

noImplicitAny errors when a type would be inferred as any. strictNullChecks makes null and undefined their own types that are not assignable to other types. strictFunctionTypes enables contravariant checking of function parameter types. strictBindCallApply enables stricter checking of bind, call, and apply. strictPropertyInitialization requires class properties to be initialized in the constructor or marked as optional. noImplicitThis errors when this has an implicit any type. alwaysStrict emits "use strict" in every output file — deprecated in TypeScript 6.0, as all code is now assumed to be in strict mode. useUnknownInCatchVariables makes catch clause variables unknown instead of any.

Additional Strictness

These flags are not part of strict but are commonly used:

noUncheckedIndexedAccess adds undefined to the type of indexed access expressions (array elements, object property access by index). Highly recommended. noImplicitOverride requires the override keyword when overriding a base class method. noPropertyAccessFromIndexSignature forces bracket notation for properties that come from an index signature. exactOptionalPropertyTypes distinguishes between a property being undefined and a property being missing entirely. noImplicitReturns errors if a function has code paths that do not return a value. noFallthroughCasesInSwitch errors on fallthrough cases in switch statements. noUnusedLocals errors on unused local variables. noUnusedParameters errors on unused function parameters. erasableSyntaxOnly ensures that all TypeScript-specific syntax can be removed without changing runtime behavior — required for Node.js's type-stripping mode. Introduced in TypeScript 5.8.

Build Performance

skipLibCheck skips type-checking of .d.ts files. This is recommended for most projects because checking all of node_modules is slow and usually unnecessary. forceConsistentCasingInFileNames prevents case-sensitivity issues that cause problems on case-sensitive file systems (like Linux in CI). incremental saves compilation state to a .tsbuildinfo file and reuses it on subsequent builds. composite enables project references and forces certain options that enable incremental builds across multiple projects. tsBuildInfoFile specifies the location of the .tsbuildinfo file. disableSourceOfProjectReferenceRedirect uses declaration files instead of source files for referenced projects, improving build speed.

Other Notable Options

jsx controls how JSX is transformed. Values include react (transforms to React.createElement), react-jsx (transforms to the new JSX runtime), react-jsxdev, preserve (keeps JSX in the output), and react-native. allowJs allows JavaScript files in the TypeScript compilation. checkJs type-checks JavaScript files (requires allowJs). maxNodeModuleJsDepth controls how deep into node_modules TypeScript looks when checking JavaScript files. plugins specifies TypeScript language service plugins. types limits which @types packages are automatically included. An empty array [] disables automatic inclusion. As of TypeScript 6.0, types defaults to [], meaning you must explicitly list the @types packages you need. typeRoots specifies directories to search for type declarations. downlevelIteration enables full support for iterables when targeting older JavaScript versions — deprecated in TypeScript 6.0. importHelpers imports helper functions from tslib instead of inlining them. libReplacement controls whether TypeScript looks for replacement lib packages like @typescript/lib-dom. Introduced in TypeScript 5.8, defaults to false in TypeScript 6.0.

TypeScript 6.0 Default Changes

TypeScript 6.0 changed many defaults to reflect the modern ecosystem. Here is what changed:

strict now defaults to true. module now defaults to esnext. target now defaults to es2025. noUncheckedSideEffectImports now defaults to true. libReplacement now defaults to false. rootDir now defaults to . (the tsconfig directory). types now defaults to [].

You can temporarily suppress deprecation warnings by adding "ignoreDeprecations": "6.0" to your tsconfig, but these deprecated options will be removed entirely in TypeScript 7.0.

Part 5: Version History — From TypeScript 1.0 to 6.0

TypeScript 1.0 (April 2014)

The first stable release. It established the core language: type annotations, interfaces, classes, modules, generics, and enums. It was designed to be a strict superset of JavaScript with optional types.

TypeScript 2.x (2016–2017)

TypeScript 2.0 introduced strictNullChecks, discriminated unions, the never type, and control flow-based type analysis. These features fundamentally transformed how TypeScript code is written.

TypeScript 2.1 added keyof and mapped types, enabling type-level programming for the first time. Partial, Readonly, Record, and Pick became possible.

TypeScript 2.2 added the object type (distinct from Object).

TypeScript 2.3 added --strict as an umbrella flag and introduced generic defaults.

TypeScript 2.4 added string enums.

TypeScript 2.8 introduced conditional types and the infer keyword — arguably the most transformative addition to the type system since generics.

TypeScript 2.9 added import() types for dynamic imports.

TypeScript 3.x (2018–2020)

TypeScript 3.0 introduced the unknown type, project references (for monorepo builds), and rest elements in tuple types.

TypeScript 3.1 added mapped types on tuples and arrays.

TypeScript 3.2 added bigint support.

TypeScript 3.4 introduced const assertions (as const) for creating deeply readonly literal types.

TypeScript 3.7 added optional chaining (?.), nullish coalescing (??), assertion functions, and recursive type aliases.

TypeScript 3.8 added import type and export type for type-only imports and exports, along with #private fields (ECMAScript private fields).

TypeScript 3.9 focused on performance improvements.

TypeScript 4.x (2020–2023)

TypeScript 4.0 introduced variadic tuple types and labeled tuple elements.

TypeScript 4.1 added template literal types and key remapping in mapped types — enabling string manipulation at the type level.

TypeScript 4.2 added rest elements in the middle of tuples.

TypeScript 4.3 added override keyword and template literal expression types.

TypeScript 4.4 added control flow analysis for aliased conditions and discriminants.

TypeScript 4.5 added the Awaited type, import assertions, and ES module support for Node.js.

TypeScript 4.7 added variance annotations (in/out), moduleSuffixes, and --module nodenext.

TypeScript 4.8 improved narrowing for {} and unknown.

TypeScript 4.9 introduced the satisfies operator.

TypeScript 5.x (2023–2025)

TypeScript 5.0 was a massive release. It added TC39 Stage 3 decorators (replacing the legacy experimental decorators), const type parameters, enum improvements, --moduleResolution bundler, and migrated the codebase from internal namespaces to ES modules, reducing the npm package size by 58%.

TypeScript 5.1 added easier implicit returns for undefined-returning functions and unrelated types for getters and setters.

TypeScript 5.2 introduced using declarations (explicit resource management), decorator metadata, and named/anonymous tuple elements.

TypeScript 5.3 added import attributes, narrowing within switch (true), and --resolution-mode in import types.

TypeScript 5.4 introduced the NoInfer utility type, improved type narrowing in closures, and new Object.groupBy and Map.groupBy types.

TypeScript 5.5 introduced inferred type predicates (the compiler can automatically infer x is T), regex syntax checking, isolatedDeclarations, and an improved editor experience.

TypeScript 5.6 added disallowed nullish and truthy checks (flagging expressions that are always truthy or always nullish in conditions), iterator helper types, and the --noUncheckedSideEffectImports flag.

TypeScript 5.7 improved detection of never-initialized variables, added ES2024 target support with Object.groupBy and Map.groupBy types, and the --rewriteRelativeImportExtensions flag for direct TypeScript execution.

TypeScript 5.8 added the --erasableSyntaxOnly flag for compatibility with Node.js type stripping, the --libReplacement flag, granular return type checks for conditional expressions, --module nodenext support for require() of ESM, and --module node18 for stable Node.js 18 resolution. This was the last TypeScript 5.x with significant new features, as the team had begun work on the Go rewrite.

TypeScript 5.9 (August 2025) added import defer for deferred module evaluation, expandable hover tooltips in editors, a redesigned tsc --init command, configurable hover length, and significant performance improvements through type instantiation caching. This was the final TypeScript 5.x release.

TypeScript 6.0 (March 2026)

TypeScript 6.0 is a "bridge release" — the last version of the compiler written in JavaScript, designed to prepare the ecosystem for TypeScript 7.0's Go rewrite. It makes sweeping changes to defaults and removes legacy options.

New defaults: strict: true, module: esnext, target: es2025, types: [], rootDir: .. This means every new TypeScript project is strict by default, targets modern JavaScript, and does not automatically include @types packages.

Deprecations and removals: target: es5 is deprecated. --outFile is removed. --baseUrl (without paths) is deprecated. --moduleResolution node10/classic is deprecated. Module formats amd, umd, and systemjs are deprecated. alwaysStrict: false is deprecated because all code is assumed strict.

New features: Temporal API types (the Temporal global is now in the standard library, reflecting its Stage 4 status in TC39), Map.getOrInsert and Map.getOrInsertComputed types from the "upsert" proposal, improved type inference for methods (less context-sensitivity on this-less functions), #/ subpath imports, es2025 target and lib, and --stableTypeOrdering to preview the deterministic type ordering that will be the default in TypeScript 7.0.

The ignoreDeprecations: "6.0" escape hatch allows teams to suppress deprecation warnings during migration, but TypeScript 7.0 will not support any of the deprecated options. A ts5to6 migration tool can automate configuration adjustments for baseUrl and rootDir.

TypeScript 7.0 (Upcoming, 2026)

TypeScript 7.0 is the single most ambitious change in TypeScript's history: a complete rewrite of the compiler and language service in Go, codenamed Project Corsa. The project was announced by Anders Hejlsberg in March 2025 and has been progressing rapidly ever since.

The new compiler, called tsgo, is a drop-in replacement for tsc. It uses Go's native compilation and goroutines for parallel type checking. The performance improvements are dramatic: the VS Code codebase (1.5 million lines of TypeScript) compiles in 8.74 seconds with tsgo compared to 89 seconds with tsc — a 10.2x speedup. The Sentry project dropped from 133 seconds to 16 seconds. Memory usage drops roughly 2.9x.

Why Go instead of Rust? The TypeScript team explained that Go's garbage collector and memory model map more closely to TypeScript's existing data structures. The compiler was designed around mutable shared state, and Rust's ownership model would have required fundamental architectural changes. Go allowed a relatively faithful port while achieving native speed.

The language itself does not change. The same TypeScript code, the same type system, the same errors. The differences are in the tooling: tsgo uses the Language Server Protocol (LSP) instead of the proprietary TSServer protocol, which means editor integrations need to be updated. Custom plugins and transformers that patch TypeScript internals may not work. All deprecated options from 6.0 become hard removals.

As of March 2026, the tsgo CLI is available as @typescript/native-preview on npm. A VS Code extension provides the Go-based language service for daily use. Type checking is described as "very nearly complete," with remaining mismatches down to known incomplete work or intentional behavior changes. Full emit (generating .js and .d.ts files) is still in progress. The stable TypeScript 7.0 release is targeting mid-2026.

The ecosystem implications are significant. Tools built on the TSServer protocol (many editor extensions, linting integrations) need to migrate to LSP. Custom TypeScript transformers need new APIs. The --baseUrl and other deprecated options simply will not exist. But for most teams, the migration is straightforward: install the new package, run tsgo alongside tsc to verify identical results, then switch.

Part 6: The Tooling Ecosystem

TypeScript does not exist in isolation. A rich ecosystem of tools has grown around it.

Build Tools and Transpilers

tsc is TypeScript's own compiler. It does both type checking and code generation. For many projects, it is all you need.

esbuild is an extremely fast bundler written in Go. It can transpile TypeScript to JavaScript (stripping types) but does not type-check. Many projects use esbuild for fast builds and tsc --noEmit for type checking.

SWC (Speedy Web Compiler) is a Rust-based transpiler used by Next.js, Vite, and other tools. Like esbuild, it strips types without checking them.

Babel with @babel/preset-typescript also strips types. It was once the primary alternative to tsc for compilation, but esbuild and SWC have largely supplanted it for new projects.

Vite uses esbuild for development and Rollup (or Rolldown, its Rust rewrite) for production builds. It is the most popular build tool for new frontend projects as of 2026.

Linting

ESLint with @typescript-eslint is the standard linting setup. The @typescript-eslint package provides TypeScript-aware lint rules that go beyond what the compiler checks, like enforcing ===, detecting redundant type assertions, and catching common patterns that lead to bugs.

Biome is a newer Rust-based linter and formatter that is faster than ESLint. It supports TypeScript natively and is gaining adoption, especially in projects that value startup speed.

Testing

Vitest is the modern testing framework most commonly used with TypeScript. It runs on Vite, supports TypeScript out of the box, and is significantly faster than Jest for large projects.

Jest with ts-jest or @swc/jest remains widely used, especially in existing projects. Configuration can be more involved than Vitest.

Type testing is a category of its own. Libraries like expect-type and tsd let you write tests that verify type-level behavior, ensuring that your types produce the correct results.

Runtime Validation

TypeScript types are erased at runtime. If you receive data from an API, a database, or user input, you cannot trust that it matches your TypeScript types. Runtime validation libraries bridge this gap:

Zod is the most popular runtime validation library for TypeScript. You define a schema, and Zod infers the TypeScript type from it, keeping your runtime validation and your types in sync.

Valibot is a smaller, tree-shakeable alternative to Zod with a functional API.

ArkType defines types using a TypeScript-like syntax string, providing another approach to runtime validation with minimal overhead.

Package Publishing

If you publish a TypeScript library to npm, you need to emit both JavaScript and declaration files. The standard approach is to use tsc with declaration: true and declarationMap: true. For more complex setups, tools like tsup (built on esbuild) handle bundling, declaration generation, and dual CJS/ESM publishing.

TypeScript 5.5's isolatedDeclarations option enables tools other than tsc to generate declaration files, because each file contains enough type information to produce its declaration independently. This unlocks parallel declaration emit and faster builds in monorepos.

Node.js Native TypeScript Support

As of Node.js 23.6, you can run TypeScript files directly with --experimental-strip-types. Node.js uses the Amaro library (based on SWC's WASM build) to strip type annotations from your code before execution. This does not type-check — it simply removes the TypeScript syntax, leaving valid JavaScript.

The limitation is that only "erasable" syntax is supported: type annotations, interfaces, type aliases, and other constructs that have no runtime semantics. Enums (which generate JavaScript code), namespaces with values, and parameter properties in constructors are not supported under type stripping. TypeScript 5.8's --erasableSyntaxOnly flag ensures your code is compatible.

Bloomberg's ts-blank-space is a similar tool that replaces TypeScript syntax with whitespace, preserving line numbers so source maps are not needed for debugging.

Part 7: Patterns and Best Practices

Start Strict, Stay Strict

Always enable strict: true in your tsconfig (and as of TypeScript 6.0, it is the default). Every individual strictness flag catches real bugs. noUncheckedIndexedAccess is not part of strict but is highly recommended — it adds undefined to array element access, forcing you to handle the possibility that an index is out of bounds.

Avoid any

The any type opts out of type checking. Every any in your codebase is a potential runtime error. Use unknown when you truly do not know a type, and narrow it with type guards. If you are working with third-party libraries that use any, consider wrapping them with properly typed interfaces.

Prefer Interfaces for Object Shapes, Type Aliases for Everything Else

Interfaces support declaration merging and can be extended, making them better for object shapes that might be augmented (like a library's public API). Type aliases are more versatile — they support unions, intersections, conditional types, and mapped types.

Use Discriminated Unions for State Management

Instead of optional properties and boolean flags, use discriminated unions:

// Bad
type Request = {
  status: "loading" | "success" | "error";
  data?: ResponseData;
  error?: Error;
};

// Good
type Request =
  | { status: "loading" }
  | { status: "success"; data: ResponseData }
  | { status: "error"; error: Error };

The discriminated union makes it impossible to access data when the status is "error" or error when the status is "success".

Use as const for Literal Inference

When you want TypeScript to infer the narrowest possible type, use as const:

const config = {
  endpoint: "https://api.example.com",
  retries: 3,
  methods: ["GET", "POST"],
} as const;

// config.endpoint is "https://api.example.com", not string
// config.retries is 3, not number
// config.methods is readonly ["GET", "POST"], not string[]

Validate External Data at the Boundary

TypeScript's types are erased at runtime. Data from APIs, databases, local storage, and user input should be validated using a runtime validation library like Zod. Define the schema once and let the library infer the TypeScript type:

import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>; // { id: number; name: string; email: string }

const response = await fetch("/api/users/1");
const user = UserSchema.parse(await response.json()); // validates and returns typed User

Use Project References for Large Codebases

For monorepos and large projects, TypeScript's project references (composite: true and references in tsconfig) enable incremental builds that only recompile changed projects. Combined with --build mode, this can dramatically reduce build times.

Prefer ECMAScript Features Over TypeScript-Only Features

TypeScript's enums, namespaces, and parameter properties have runtime semantics that are not part of the ECMAScript standard. Prefer standard alternatives: string literal unions instead of enums, ES modules instead of namespaces, and explicit property assignment in constructors instead of parameter properties. This makes your code compatible with type stripping, Node.js native TypeScript support, and the broader JavaScript ecosystem.

Part 8: Common Pitfalls and How to Avoid Them

The Object.keys Problem

Object.keys() returns string[], not (keyof T)[]:

const user = { name: "Alice", age: 30 };
const keys = Object.keys(user); // string[], not ("name" | "age")[]

This is by design — JavaScript objects can have additional properties at runtime that TypeScript does not know about. If you are certain of the object's shape, you can cast: (Object.keys(user) as (keyof typeof user)[]).

Structural vs Nominal Typing

TypeScript uses structural typing, meaning that any object with the right shape is assignable to a type, regardless of its name:

interface Cat { name: string; meow(): void }
interface Dog { name: string; meow(): void }

const cat: Cat = { name: "Whiskers", meow() {} };
const dog: Dog = cat; // This works! They have the same shape.

If you need nominal typing (types that are distinct even with the same shape), use branded types:

type USD = number & { __brand: "USD" };
type EUR = number & { __brand: "EUR" };

function toUSD(amount: number): USD { return amount as USD; }
function toEUR(amount: number): EUR { return amount as EUR; }

const dollars: USD = toUSD(100);
const euros: EUR = toEUR(85);
// dollars = euros; // Error — different brands

Type Assertions Are Escape Hatches

as assertions tell the compiler to trust you. They are not runtime checks:

const value = someFunction() as string; // No runtime check!

If someFunction() returns a number, you will get a runtime error. Prefer type narrowing over type assertions whenever possible.

Index Signatures and undefined

Without noUncheckedIndexedAccess, accessing an object with an index signature does not add undefined:

interface Cache {
  [key: string]: string;
}

const cache: Cache = {};
const value = cache["missing"]; // string, but actually undefined at runtime!

Enable noUncheckedIndexedAccess to make this string | undefined.

Part 9: What Lies Ahead

The TypeScript 7.0 Transition

The transition from TypeScript 6.0 to 7.0 will be the most significant upgrade most TypeScript developers experience. The language is unchanged, but the tooling pipeline changes fundamentally. Teams should take these steps:

Audit your tsconfig for deprecated options now. Upgrade to TypeScript 6.0 and resolve all deprecation warnings. Test with @typescript/native-preview (tsgo --noEmit) in your CI pipeline. Identify any custom plugins, transformers, or tools that depend on the TSServer protocol or TypeScript's JavaScript API. Monitor the TypeScript 7.0 iteration plan for the stable release date.

ECMAScript Proposals to Watch

Several in-progress ECMAScript proposals will affect TypeScript when they reach Stage 3 or 4:

The Pattern Matching proposal would add a match expression to JavaScript, similar to Rust's match or Scala's pattern matching. TypeScript would provide type narrowing within each pattern arm.

The Type Annotations proposal (ECMAScript type comments) would add syntax for type annotations directly to JavaScript. If adopted, it could eventually mean that TypeScript's type syntax becomes part of JavaScript itself — though the types would be ignored at runtime, just like comments. This is conceptually similar to how Node.js's type stripping works today, but standardized.

The Pipe Operator proposal (|>) would enable functional-style composition. TypeScript would need to infer types through pipe chains.

The Broader Trend: Native-Speed JavaScript Tooling

TypeScript 7's Go rewrite is part of a larger trend in the JavaScript ecosystem. esbuild is written in Go. SWC and Biome are written in Rust. Rolldown (the Vite bundler) is written in Rust. Oxc (a JavaScript/TypeScript toolchain) is written in Rust. The era of writing JavaScript developer tools in JavaScript is ending. These native-speed tools reduce build times from minutes to seconds, and the performance gains compound in large codebases and CI/CD pipelines.

Conclusion

TypeScript has come an extraordinarily long way from its 2012 debut as "JavaScript with types." It has become the default language for frontend development, a major force in backend Node.js development, and increasingly used in mobile and edge computing. Its type system is among the most expressive of any mainstream language, capable of catching entire categories of bugs at compile time while remaining fully compatible with the vast JavaScript ecosystem.

The story of TypeScript in 2026 is one of convergence. The language is converging with JavaScript as more TypeScript syntax becomes natively supported in Node.js and potentially in the ECMAScript standard itself. The tooling is converging on native speed as the Go rewrite promises 10x faster builds. And the defaults are converging on strictness as TypeScript 6.0 makes strict: true the default for all new projects.

Whether you are just starting with TypeScript or have been using it for years, there has never been a better time to invest in understanding it deeply. The language is stable, the ecosystem is mature, the tooling is about to get dramatically faster, and the community is larger than ever. Every line of TypeScript you write today will benefit from the performance improvements, editor enhancements, and ecosystem refinements that are coming in the months ahead.

What Is Version Control, and Why Does It Exist?

Before version control systems existed, developers maintained multiple copies of their source code by hand — renaming folders to things like project-v2-final-FINAL-fixed and hoping they could remember which copy was which. When two developers needed to work on the same file, they would shout across the office or send emails with zipped attachments. This was expensive, error-prone, and utterly unsustainable.

Version control systems solve this by tracking every change to every file over time, allowing multiple people to work on the same codebase simultaneously, and providing the ability to revert to any previous state. Git is the dominant version control system today, with approximately 85% market share among software development teams.

A Brief History: From Locks to Distributed Merging

Version control evolved through three generations, each expanding the ability to work in parallel.

First generation (1970s–1980s): Systems like SCCS and RCS used a lock-edit-unlock model. Only one person could edit a file at a time. Everyone else had to wait. This was safe but slow.

Second generation (1990s–2000s): Systems like CVS, Subversion (SVN), and Team Foundation Version Control (TFVC — the version control component of TFS/Azure DevOps) introduced a centralized server model with merge-based concurrent editing. Multiple people could edit the same file simultaneously, and the system would merge their changes. But you needed a network connection to the central server for most operations — committing, viewing history, branching.

Third generation (2005–present): Distributed systems like Git and Mercurial gave every developer a complete copy of the entire repository, including its full history. You can commit, branch, view history, and diff entirely offline. You synchronize with teammates by pushing and pulling changesets between repositories. Linus Torvalds created Git in 2005 specifically for Linux kernel development, where thousands of developers needed to work independently across time zones without a single point of failure.

How Git Thinks: Snapshots, Not Diffs

Most version control systems store data as a list of file-based changes (deltas). Git is fundamentally different — it thinks of its data as a series of snapshots of the entire project at each point in time. When you commit, Git takes a snapshot of every file in your staging area and stores a reference to that snapshot. If a file has not changed, Git does not store it again; it stores a pointer to the previous identical file.

Every piece of data in Git is checksummed with SHA-1 (or SHA-256 in newer versions) before it is stored. This means Git knows if any file has been corrupted or tampered with. You cannot change the contents of any file or directory without Git knowing.

The Three States

Every file in a Git working directory exists in one of three states:

Modified means you have changed the file in your working directory but have not staged it yet.

Staged means you have marked a modified file to be included in your next commit snapshot.

Committed means the data is safely stored in your local Git database.

This gives rise to the three main sections of a Git project:

1. Working Directory — the actual files on your disk
2. Staging Area (also called the "index") — a file that stores information about what will go into your next commit
3. Git Directory (the .git folder) — where Git stores the metadata and object database for your project

The basic Git workflow is: you modify files in your working directory, you stage the changes you want to include, and then you commit, which takes the staged snapshot and stores it permanently in the Git directory.

Part 2: Every Command You Need

Setup and Configuration

Before your first commit, configure your identity:

# Set your name and email (stored in commits)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch name to 'main'
git config --global init.defaultBranch main

# Set default editor (for commit messages)
git config --global core.editor "code --wait"  # VS Code
git config --global core.editor "vim"           # Vim
git config --global core.editor "notepad"       # Notepad on Windows

# Enable colored output
git config --global color.ui auto

# Set line ending behavior
git config --global core.autocrlf true   # Windows (converts LF to CRLF)
git config --global core.autocrlf input  # Mac/Linux (converts CRLF to LF on commit)

# View all configuration
git config --list --show-origin

Git configuration has three levels, each overriding the previous:

• System (/etc/gitconfig) — applies to every user on the machine
• Global (~/.gitconfig) — applies to your user account
• Local (.git/config in a repository) — applies to that specific repository

Creating and Cloning Repositories

# Initialize a new repository in the current directory
git init

# Initialize a new repository in a new directory
git init my-project

# Clone an existing repository
git clone https://github.com/user/repo.git

# Clone into a specific directory
git clone https://github.com/user/repo.git my-local-name

# Clone only the most recent commit (shallow clone, saves bandwidth)
git clone --depth 1 https://github.com/user/repo.git

# Clone a specific branch
git clone --branch develop https://github.com/user/repo.git

Staging and Committing

# Check the status of your files
git status

# Short status (more compact output)
git status -s

# Stage a specific file
git add README.md

# Stage multiple specific files
git add file1.cs file2.cs file3.cs

# Stage all changes in a directory
git add src/

# Stage all changes in the entire repository
git add .

# Stage all tracked files that have been modified (ignores new untracked files)
git add -u

# Interactively stage parts of files (choose which hunks to stage)
git add -p

# Unstage a file (remove from staging area, keep changes in working directory)
git restore --staged README.md

# Discard changes in working directory (DANGEROUS — cannot be undone)
git restore README.md

# Commit staged changes with a message
git commit -m "Add user authentication module"

# Commit with a multi-line message
git commit -m "Add user authentication module" -m "Implements JWT-based auth with refresh tokens.
Closes #42."

# Stage all tracked modified files AND commit in one step
git commit -am "Fix null reference in OrderService"

# Amend the most recent commit (change message or add forgotten files)
git add forgotten-file.cs
git commit --amend -m "Add user authentication module (with tests)"

# Amend without changing the message
git commit --amend --no-edit

# Create an empty commit (useful for triggering CI)
git commit --allow-empty -m "Trigger CI rebuild"

Viewing History

# View commit log
git log

# Compact one-line format
git log --oneline

# Show a graph of branches
git log --oneline --graph --all

# Show the last 5 commits
git log -5

# Show commits that changed a specific file
git log -- src/Program.cs

# Show commits by a specific author
git log --author="Alice"

# Show commits containing a search term in the message
git log --grep="authentication"

# Show commits between two dates
git log --after="2026-01-01" --before="2026-03-01"

# Show the diff introduced by each commit
git log -p

# Show stats (files changed, insertions, deletions)
git log --stat

# Show a pretty custom format
git log --pretty=format:"%h %ad | %s%d [%an]" --date=short

# Find which commit introduced a specific line of code
git log -S "connectionString" --oneline

# Show who last modified each line of a file (blame)
git blame src/Services/AuthService.cs

# Show blame for a specific range of lines
git blame -L 10,20 src/Services/AuthService.cs

Branching

Branches in Git are incredibly lightweight — a branch is simply a pointer (a 41-byte file) to a specific commit. Creating a branch is nearly instantaneous regardless of repository size.

# List local branches
git branch

# List all branches (including remote-tracking branches)
git branch -a

# List branches with their last commit
git branch -v

# Create a new branch (does NOT switch to it)
git branch feature/user-profile

# Create a new branch AND switch to it
git checkout -b feature/user-profile
# Modern equivalent (Git 2.23+):
git switch -c feature/user-profile

# Switch to an existing branch
git checkout main
# Modern equivalent:
git switch main

# Rename a branch
git branch -m old-name new-name

# Rename the current branch
git branch -m new-name

# Delete a branch (only if fully merged)
git branch -d feature/user-profile

# Force delete a branch (even if not merged — DANGEROUS)
git branch -D feature/user-profile

# Delete a remote branch
git push origin --delete feature/user-profile

Merging

# Merge a branch into the current branch
git merge feature/user-profile

# Merge with a merge commit even if fast-forward is possible
git merge --no-ff feature/user-profile

# Abort a merge in progress (if there are conflicts)
git merge --abort

# Continue a merge after resolving conflicts
git add .  # Stage the resolved files
git merge --continue
# Or equivalently:
git commit

Fast-forward merge happens when the target branch has no new commits since the feature branch was created. Git simply moves the pointer forward. No merge commit is created.

Three-way merge happens when both branches have diverged. Git creates a new "merge commit" with two parents.

Merge conflicts occur when the same lines in the same file were modified differently in both branches. Git marks these in the file:

<<<<<<< HEAD
    return user.GetFullName();
=======
    return $"{user.FirstName} {user.LastName}";
>>>>>>> feature/user-profile

You resolve the conflict by editing the file to the desired final state, removing the markers, staging the file, and completing the merge.

Rebasing

Rebase is an alternative to merging. Instead of creating a merge commit, it replays your commits on top of the target branch, creating a linear history.

# Rebase current branch onto main
git rebase main

# Interactive rebase — edit, squash, reorder, or drop commits
git rebase -i main

# Interactive rebase of the last 3 commits
git rebase -i HEAD~3

# Abort a rebase in progress
git rebase --abort

# Continue after resolving a conflict during rebase
git add .
git rebase --continue

# Skip a problematic commit during rebase
git rebase --skip

In interactive rebase (git rebase -i), you get an editor showing commits with action keywords:

pick abc1234 Add user model
pick def5678 Add user service
pick ghi9012 Fix typo in user service

# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like squash, but discard this commit's message
# d, drop = remove commit

The golden rule of rebasing: Never rebase commits that have been pushed to a shared branch that others are working from. Rebasing rewrites commit history — if someone else has based their work on the original commits, their history will diverge from yours, causing confusion and pain.

Remote Repositories

# List remotes
git remote -v

# Add a remote
git remote add origin https://github.com/user/repo.git

# Add a second remote (e.g., a fork)
git remote add upstream https://github.com/original/repo.git

# Change a remote's URL
git remote set-url origin https://github.com/user/new-repo.git

# Remove a remote
git remote remove upstream

# Fetch changes from a remote (does NOT merge)
git fetch origin

# Fetch from all remotes
git fetch --all

# Pull (fetch + merge) from the remote
git pull origin main

# Pull with rebase instead of merge
git pull --rebase origin main

# Push to a remote
git push origin main

# Push and set upstream tracking
git push -u origin feature/user-profile

# Push all branches
git push --all origin

# Push tags
git push --tags

# Force push (DANGEROUS — overwrites remote history)
git push --force origin feature/user-profile

# Force push with safety (only overwrites if remote hasn't changed)
git push --force-with-lease origin feature/user-profile

Stashing

Stash temporarily shelves changes so you can work on something else:

# Stash all modified tracked files
git stash

# Stash with a description
git stash push -m "WIP: halfway through refactoring auth"

# Stash including untracked files
git stash -u

# List all stashes
git stash list

# Apply the most recent stash (keeps it in stash list)
git stash apply

# Apply a specific stash
git stash apply stash@{2}

# Apply and remove from stash list
git stash pop

# Drop a specific stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

# Create a branch from a stash
git stash branch new-branch-name stash@{0}

Tagging

Tags are permanent bookmarks for specific commits, typically used for releases:

# List tags
git tag

# List tags matching a pattern
git tag -l "v1.*"

# Create a lightweight tag (just a pointer)
git tag v1.0.0

# Create an annotated tag (stores tagger info, date, message)
git tag -a v1.0.0 -m "Release version 1.0.0"

# Tag a specific commit
git tag -a v1.0.0 abc1234 -m "Release version 1.0.0"

# Push a specific tag
git push origin v1.0.0

# Push all tags
git push origin --tags

# Delete a local tag
git tag -d v1.0.0

# Delete a remote tag
git push origin --delete v1.0.0

Undoing Things

# Undo the last commit, keep changes staged
git reset --soft HEAD~1

# Undo the last commit, keep changes in working directory (unstaged)
git reset --mixed HEAD~1  # --mixed is the default

# Undo the last commit, DISCARD all changes (DANGEROUS)
git reset --hard HEAD~1

# Reset a single file to the last committed version
git checkout HEAD -- src/Program.cs
# Modern equivalent:
git restore src/Program.cs

# Create a new commit that reverses a previous commit
# (safe for shared branches — doesn't rewrite history)
git revert abc1234

# Revert a merge commit (must specify which parent to keep)
git revert -m 1 abc1234

# Recover a "lost" commit (Git keeps everything for ~30 days)
git reflog
git checkout abc1234  # or git cherry-pick abc1234

Cherry-Picking

Apply a specific commit from one branch to another:

# Apply a single commit to the current branch
git cherry-pick abc1234

# Apply multiple commits
git cherry-pick abc1234 def5678

# Cherry-pick without committing (just stage the changes)
git cherry-pick --no-commit abc1234

# Abort a cherry-pick
git cherry-pick --abort

Advanced: Bisect, Clean, Archive

# Binary search for a bug-introducing commit
git bisect start
git bisect bad          # Current commit is broken
git bisect good v1.0.0  # This tag was known good
# Git checks out the middle commit. Test it, then:
git bisect good  # if this commit works
git bisect bad   # if this commit is broken
# Repeat until Git identifies the exact commit
git bisect reset  # Return to your original branch

# Remove untracked files
git clean -n    # Dry run (show what would be deleted)
git clean -f    # Actually delete untracked files
git clean -fd   # Delete untracked files and directories
git clean -fX   # Delete only ignored files (clean build artifacts)

# Create an archive of the repository
git archive --format=zip HEAD > project.zip
git archive --format=tar.gz --prefix=project/ HEAD > project.tar.gz

The .gitignore File

.gitignore tells Git which files and directories to never track:

# Compiled output
bin/
obj/
publish/
*.dll
*.exe
*.pdb

# IDE files
.vs/
.vscode/
*.user
*.suo
.idea/

# OS files
.DS_Store
Thumbs.db

# Environment and secrets
.env
appsettings.Development.json

# NuGet packages
packages/

# Python
__pycache__/
*.pyc
.venv/

# Node
node_modules/

# Logs
*.log

# Negate a pattern (force include something that would otherwise be ignored)
!important.log

Patterns work as follows:

• *.log matches any file ending in .log
• bin/ matches a directory named bin anywhere in the repo
• /bin/ matches bin only at the repository root
• **/logs matches logs directories anywhere in the hierarchy
• ! negates a pattern (force includes something)

Git Aliases

Create shortcuts for frequently used commands:

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage "restore --staged"
git config --global alias.last "log -1 HEAD"
git config --global alias.lg "log --oneline --graph --all --decorate"
git config --global alias.amend "commit --amend --no-edit"

Now git lg gives you a beautiful branch graph, git co main switches to main, and git amend amends the last commit without changing the message.

Git Hooks

Git hooks are scripts that run automatically at certain points in the Git workflow. They live in .git/hooks/ (local, not committed) or can be managed with tools like Husky or pre-commit.

Common hooks:

• pre-commit — runs before a commit is created (lint, format, run fast tests)
• commit-msg — validates the commit message format
• pre-push — runs before pushing (run full test suite)
• post-merge — runs after a merge (restore NuGet packages, run migrations)

Example pre-commit hook that runs dotnet format:

#!/bin/sh
# .git/hooks/pre-commit

dotnet format --verify-no-changes
if [ $? -ne 0 ]; then
    echo "Code formatting issues found. Run 'dotnet format' to fix."
    exit 1
fi

Part 3: Branching Workflows

Gitflow (The Heavyweight)

Gitflow, popularized by Vincent Driessen in 2010, uses multiple long-lived branches:

• main (or master) — always reflects production
• develop — integration branch for the next release
• feature/* — one branch per feature, branched from and merged back to develop
• release/* — preparation for a production release, branched from develop, merged to both main and develop
• hotfix/* — urgent production fixes, branched from main, merged to both main and develop

Gitflow was designed for projects with scheduled releases and multiple supported versions. It provides strict control but at the cost of significant complexity. Dave Farley, co-author of Continuous Delivery, has argued publicly that Gitflow contradicts CI/CD principles because it delays integration and introduces complexity that slows teams down.

GitHub Flow (The Lightweight)

GitHub Flow is a simplified model:

1. main is always deployable
2. Create a branch from main for your work
3. Make commits on your branch
4. Open a pull request
5. Get code review
6. Merge to main
7. Deploy

This is simpler than Gitflow but still relies on feature branches that can become long-lived if the developer does not merge frequently.

Trunk-Based Development (The Streamlined)

Trunk-based development is the simplest model. There is one branch: main (the trunk). All developers commit to the trunk at least once every 24 hours. There are no long-lived branches. For teams that need code review, short-lived feature branches (lasting hours or at most a day or two) are used, but they are merged to trunk quickly.

This is what we are going to argue for in Part 4.

Part 4: The Case for Trunk-Based Development

This section is for the team that is hesitant. You have been using TFS (Team Foundation Server, now Azure DevOps) for years. Your workflow involves multiple long-lived branches — a develop branch, release branches, feature branches that live for weeks or months, and hotfix branches. You have code spanning multiple sprints. You know your current workflow. It works, mostly. Why change?

Because the evidence says you should.

The Evidence: DORA and Accelerate

The DevOps Research and Assessment (DORA) program, founded by Dr. Nicole Forsgren, Gene Kim, and Jez Humble and now part of Google Cloud, is the largest and longest-running academically rigorous research investigation into software delivery performance. Since 2014, their annual State of DevOps reports have surveyed tens of thousands of professionals across thousands of organizations.

Their findings, published in the book Accelerate: The Science of Lean Software and DevOps (2018), are unambiguous: trunk-based development is a statistically significant predictor of higher software delivery performance.

DORA measures performance using five key metrics: deployment frequency (how often you deploy to production), lead time for changes (how long from commit to production), change failure rate (what percentage of deployments cause failures), failed deployment recovery time (how quickly you fix failures), and reliability (how consistently your service meets performance goals).

Their research has consistently shown that speed and stability are not tradeoffs — elite performers do well across all five metrics, while low performers do poorly across all of them. This directly contradicts the intuition that moving faster means more breakage.

Elite performers who meet their reliability targets are 2.3 times more likely to practice trunk-based development than their peers. Elite performing teams deploy multiple times per day, have change lead times under 26 hours, maintain change failure rates below 1%, and recover from failures in less than 6 hours.

The research is clear: organizations that practice trunk-based development with continuous integration achieve higher delivery throughput AND higher stability than organizations using long-lived feature branches.

Why Long-Lived Branches Are an Antipattern

Every day a branch lives, it accumulates divergence from the trunk. This divergence creates three escalating problems.

Merge conflicts grow exponentially. When two developers both modify the same module over the course of a sprint, the number of potential conflicts grows with each passing day. A branch that lives for two weeks will have significantly more conflicts than one that lives for two hours. These are not just textual conflicts that Git can flag — they are semantic conflicts where the code merges cleanly but the behavior is wrong. Your tests might pass individually on each branch but fail when the branches are combined. The longer you wait to integrate, the harder and riskier the integration becomes.

Feedback is delayed. When your code sits on a feature branch for three weeks, nobody else sees it. Nobody uses it. Nobody discovers that it conflicts with what they are building. Nobody discovers that it breaks a subtle assumption in another module. You do not learn about these problems until merge day, when it is hardest and most expensive to fix them. Thierry de Pauw, writing about trunk-based development benefits, makes this point forcefully: when you work on trunk, your work-in-progress gets used by your whole team before any actual user sees it, and they find bugs that they would never find if you were isolated on a feature branch.

Integration becomes a terrifying event. When you merge a branch that has been alive for weeks, the merge is large, risky, and stressful. This is what the DevOps Handbook calls "deployment pain" — the anxiety that comes with pushing large batches of changes. Teams that experience this pain naturally merge less often, which makes each merge even larger and more painful. It is a vicious cycle.

Martin Fowler, in his comprehensive article on branching patterns, observes that "feature branching is a poor man's modular architecture, instead of building systems with the ability to easily swap in and out features at runtime/deploytime they couple themselves to the source control providing this mechanism through manual merging." In other words, long-lived branches are often a symptom of poor architecture, not a solution to it.

"But Our Features Span Multiple Sprints!"

This is the most common objection, and it reveals a fundamental misunderstanding. Trunk-based development does not mean you cannot work on large features. It means you do not use long-lived branches to isolate that work. Instead, you use two techniques: feature flags and branch by abstraction.

Feature Flags

A feature flag (also called a feature toggle) is a conditional in your code that controls whether a feature is visible to users. You merge your work-in-progress to trunk behind a flag. The code is in production, running through CI, being integrated with everyone else's work — but users do not see it until you flip the flag.

In a .NET application, this can be as simple as:

// A simple feature flag using configuration
public class FeatureFlags
{
    public bool EnableNewCheckoutFlow { get; set; }
    public bool EnableAdvancedSearch { get; set; }
    public bool EnableBulkImport { get; set; }
}

// In Program.cs / Startup
builder.Services.Configure<FeatureFlags>(
    builder.Configuration.GetSection("Features"));

// In your service or controller
public class CheckoutService
{
    private readonly FeatureFlags _flags;

    public CheckoutService(IOptions<FeatureFlags> flags) =>
        _flags = flags.Value;

    public async Task<Order> ProcessCheckout(Cart cart)
    {
        if (_flags.EnableNewCheckoutFlow)
            return await ProcessNewCheckout(cart);
        else
            return await ProcessLegacyCheckout(cart);
    }
}

// appsettings.json (production — flag off)
{
  "Features": {
    "EnableNewCheckoutFlow": false,
    "EnableAdvancedSearch": false,
    "EnableBulkImport": true
  }
}

// appsettings.Development.json (local dev — flag on)
{
  "Features": {
    "EnableNewCheckoutFlow": true,
    "EnableAdvancedSearch": true,
    "EnableBulkImport": true
  }
}

Martin Fowler categorizes feature flags into several types: release toggles (to hide incomplete features), experiment toggles (for A/B testing), ops toggles (to disable features under load), and permission toggles (to enable features for specific users). Release toggles — the type most relevant to trunk-based development — should be short-lived. Once a feature is complete and released, remove the flag. Pete Hodgson, writing on martinfowler.com, warns that feature flags have a carrying cost and should be treated as inventory — teams should proactively work to keep the number of active flags as low as possible. Knight Capital Group's famous $460 million loss is a cautionary tale about what happens when old feature flags are not cleaned up.

Branch by Abstraction

Branch by abstraction, a technique named by Paul Hammant and documented extensively by Martin Fowler, is for large-scale infrastructure changes — replacing a database, swapping an ORM, rewriting a major subsystem. The idea is to create an abstraction layer (an interface) between the code that uses a component and the component itself, then gradually swap out the implementation behind that abstraction.

Here is a concrete .NET example. Suppose you are migrating from Dapper to Entity Framework:

// Step 1: Create the abstraction
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id);
    Task<IReadOnlyList<Order>> GetRecentAsync(int count);
    Task CreateAsync(Order order);
    Task UpdateAsync(Order order);
}

// Step 2: Wrap the existing Dapper implementation
public class DapperOrderRepository : IOrderRepository
{
    private readonly IDbConnection _db;

    public DapperOrderRepository(IDbConnection db) => _db = db;

    public async Task<Order?> GetByIdAsync(Guid id) =>
        await _db.QueryFirstOrDefaultAsync<Order>(
            "SELECT * FROM Orders WHERE Id = @Id", new { Id = id });

    // ... other methods using Dapper
}

// Step 3: Build the new EF implementation alongside it
public class EfOrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public EfOrderRepository(AppDbContext context) => _context = context;

    public async Task<Order?> GetByIdAsync(Guid id) =>
        await _context.Orders.FindAsync(id);

    // ... other methods using EF
}

// Step 4: Use a feature flag to switch between them
builder.Services.AddScoped<IOrderRepository>(sp =>
{
    var flags = sp.GetRequiredService<IOptions<FeatureFlags>>().Value;
    return flags.UseEntityFramework
        ? sp.GetRequiredService<EfOrderRepository>()
        : sp.GetRequiredService<DapperOrderRepository>();
});

Every step is a small, mergeable commit to trunk. At no point is the codebase broken. You can release at any time. The old and new implementations coexist. Once the migration is complete and verified, you remove the old implementation, the flag, and optionally the abstraction layer.

Jez Humble describes how his team at ThoughtWorks used this technique to replace both an ORM (iBatis to Hibernate) and a web framework (Velocity/JsTemplate to Ruby on Rails) for the Go continuous delivery tool — all while continuing to release the application regularly.

"But What About Production Hotfixes?"

This is actually easier with trunk-based development, not harder.

In a Gitflow model, a hotfix requires: creating a branch from main, making the fix, merging back to main, tagging a release, and then merging back to develop (and possibly to every active release branch and feature branch). Miss a branch and you have a fix that is in production but not in development.

In trunk-based development: you make the fix on trunk (or a very short-lived branch that is merged to trunk within hours), and it deploys through your normal pipeline. There is only one branch, so there is no question of whether the fix is everywhere — it is.

If you need to patch an older release, you use release branches — but these are not long-lived development branches. They are cut from trunk at release time and receive only cherry-picked critical fixes. They are maintenance branches, not development branches.

# Cut a release branch when ready to release
git checkout -b release/1.0 main
git tag v1.0.0

# Later, if a hotfix is needed:
# First, fix it on trunk
git checkout main
git commit -am "Fix critical payment processing bug (#789)"

# Then cherry-pick to the release branch
git checkout release/1.0
git cherry-pick abc1234
git tag v1.0.1

"We're Not Google. We Can't Do This."

This is a common reflexive objection, and it is backwards. Google has 35,000 developers working in a single monorepo trunk. If trunk-based development scales to that, it certainly scales to your team.

But more importantly, trunk-based development actually scales down better than Gitflow. A small team benefits enormously from the simplicity. You do not need to maintain multiple long-lived branches, you do not need complex merge strategies, and you do not need to understand a complicated branching model. There is one branch. Everyone commits to it. Done.

Netflix, Microsoft (for many products), Google, Facebook (Meta), Amazon, Etsy, and Flickr all practice trunk-based development at scale. Etsy famously deploys to production more than 50 times per day.

Thierry de Pauw documents that trunk-based development has been successfully adopted by highly regulated industries including healthcare, gambling, and finance. The objection that "this cannot work for regulated industries" or "this cannot work for large systems" has been empirically disproven.

"Our Developers Are Not Ready for This."

In a long-lived-branch workflow, developer mistakes are hidden on isolated branches until merge day, when they become everyone's problem simultaneously. In trunk-based development, mistakes are caught immediately because CI runs on every commit and the whole team sees the changes within hours.

The trunk-based model is actually more forgiving, not less. If you break something, you find out in minutes (because CI caught it or a teammate noticed), not in weeks (because the branch finally merged). The blast radius of any single commit is small because commits are small.

The real question is not whether your developers are ready but whether you trust them. Thierry de Pauw makes a profound point: pull requests in a corporate setting essentially indicate that the team owns the codebase but is not allowed to contribute. This creates a low-trust environment. Trunk-based development, where everyone commits to trunk, creates a high-trust environment. It reduces fear and blame. It is the team that owns quality, not individuals.

Practical Steps to Adopt Trunk-Based Development

If you are currently using long-lived branches and want to migrate, do not try to change everything at once. Here is a gradual adoption path:

Week 1–2: Shorten branch lifetimes. Adopt a team rule: no branch lives longer than two days. If your work takes longer than that, break it into smaller pieces. Use feature flags to hide incomplete work.

Week 3–4: Improve CI. Your CI pipeline must be fast and reliable. If it takes 30 minutes to run, developers will avoid committing frequently. Aim for a pipeline that completes in under 10 minutes. Run unit tests on every commit. Run integration tests on every merge to trunk.

Week 5–6: Add feature flags infrastructure. Start simple — configuration-based flags in appsettings.json. You do not need a commercial feature flag service. As your needs grow, consider tools like Microsoft.FeatureManagement (free, open source).

// Using Microsoft.FeatureManagement (MIT licensed, free)
// Install: dotnet add package Microsoft.FeatureManagement.AspNetCore

builder.Services.AddFeatureManagement();

// In appsettings.json:
{
  "FeatureManagement": {
    "NewDashboard": false,
    "BetaSearch": true
  }
}

// In a controller or Razor page:
public class DashboardController : Controller
{
    private readonly IFeatureManager _features;

    public DashboardController(IFeatureManager features) =>
        _features = features;

    public async Task<IActionResult> Index()
    {
        if (await _features.IsEnabledAsync("NewDashboard"))
            return View("DashboardV2");
        else
            return View("Dashboard");
    }
}

Week 7–8: Delete long-lived branches. Merge or close every branch that is more than a few days old. Going forward, all new work happens on trunk (or very short-lived branches from trunk).

Ongoing: Build the muscle. Trunk-based development is a skill. It gets easier with practice. Developers learn to make smaller, more focused commits. They learn to think about how to decompose large features into small, independently deployable pieces. This is not just a version control technique — it is a design discipline that makes your software more modular and your team more effective.

Configuration for a Trunk-Based .NET Repository

Here is how to configure a repository to enforce trunk-based practices:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-dotnet@v5
        with:
          dotnet-version: '10.0.x'

      - name: Restore
        run: dotnet restore

      - name: Build
        run: dotnet build --no-restore

      - name: Test
        run: dotnet test --no-build --verbosity normal

      - name: Format check
        run: dotnet format --verify-no-changes

On GitHub, configure branch protection rules for main:

• Require pull request reviews before merging (1 reviewer is enough — keep it lightweight)
• Require status checks to pass (CI must be green)
• Require branches to be up to date before merging
• Automatically delete head branches after merge

These rules ensure quality without creating bottlenecks.

Part 5: Git Configuration Reference

Useful Global Configuration

# Rebase by default when pulling (avoids unnecessary merge commits)
git config --global pull.rebase true

# Auto-stash before rebase (saves uncommitted work automatically)
git config --global rebase.autoStash true

# Always push the current branch
git config --global push.default current

# Show more context in diffs
git config --global diff.context 5

# Use histogram diff algorithm (better results for many code changes)
git config --global diff.algorithm histogram

# Remember conflict resolutions (if you resolve the same conflict twice, Git remembers)
git config --global rerere.enabled true

# Prune remote-tracking branches on fetch
git config --global fetch.prune true

# Sign commits with GPG (optional but recommended for open source)
git config --global commit.gpgsign true
git config --global user.signingkey YOUR_GPG_KEY_ID

# Better diff for C# files
git config --global diff.csharp.xfuncname "^[ \t]*(((static|public|internal|private|protected|new|virtual|sealed|override|unsafe|async|partial)[ \t]+)*[][<>@.~_[:alnum:]]+[ \t]+[<>@._[:alnum:]]+[ \t]*\\(.*\\))[ \t]*[{;]?"

Commit Message Convention

A good commit message convention improves readability and enables automated changelogs. The Conventional Commits specification is widely adopted:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types include feat (new feature), fix (bug fix), docs (documentation), style (formatting), refactor, test, chore (build system, CI), and perf (performance improvement).

Examples:

feat(auth): add JWT refresh token rotation

Implements automatic refresh token rotation on each use.
Old refresh tokens are invalidated immediately.

Closes #142

fix(checkout): prevent double-charge on retry

The payment service was not checking for idempotency keys
when a user retried a failed payment.

chore(ci): add dotnet format check to PR pipeline

Part 6: Summary and Further Reading

Git is a powerful tool, but like any tool, how you use it matters more than which features it has. The branching model you choose profoundly affects your team's velocity, quality, and happiness.

The evidence from a decade of DORA research is clear: trunk-based development with continuous integration leads to higher performance on every metric that matters — speed, stability, and recovery. Long-lived branches create integration risk, delay feedback, and slow you down. Feature flags and branch by abstraction give you every capability that long-lived branches provide, without the cost.

You do not need to be Google to benefit. You just need to trust your team, invest in CI, and commit to small, frequent changes. The hardest part is the cultural shift. The technology is the easy part — you already have everything you need in Git.

Sources and Further Reading

• Forsgren, Nicole, Jez Humble, and Gene Kim. Accelerate: The Science of Lean Software and DevOps. IT Revolution Press, 2018. The foundational research text.
• DORA Research Program. dora.dev/research. Ongoing annual State of DevOps reports.
• DORA Metrics Guide. dora.dev/guides/dora-metrics-four-keys. Authoritative definitions of the five key metrics.
• Humble, Jez, and David Farley. Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation. Addison-Wesley, 2010.
• Kim, Gene, Jez Humble, Patrick Debois, and John Willis. The DevOps Handbook. IT Revolution Press, 2016.
• Hammant, Paul. trunkbaseddevelopment.com. The definitive reference site for trunk-based development practices and techniques.
• Fowler, Martin. "Branch by Abstraction." martinfowler.com/bliki/BranchByAbstraction.html.
• Fowler, Martin. "Patterns for Managing Source Code Branches." martinfowler.com/articles/branching-patterns.html. Comprehensive taxonomy of branching strategies.
• Fowler, Martin. "Continuous Integration." martinfowler.com/articles/continuousIntegration.html. Updated 2024 article on CI principles.
• Hodgson, Pete. "Feature Toggles (aka Feature Flags)." martinfowler.com/articles/feature-toggles.html. Comprehensive guide to feature flag categories and management.
• de Pauw, Thierry. "On the Benefits of Trunk-Based Development." thinkinglabs.io. July 2025. A practitioner's summary of TBD benefits.
• Atlassian. "Trunk-Based Development." atlassian.com/continuous-delivery/continuous-integration/trunk-based-development.
• AWS Prescriptive Guidance. "Advantages and Disadvantages of the Trunk Strategy." docs.aws.amazon.com.
• LaunchDarkly. "Elite Performance with Trunk-Based Development." launchdarkly.com. Analysis of DORA data showing elite performers are 2.3x more likely to use TBD.
• Toptal. "Trunk-Based Development vs. Git Flow." toptal.com. Updated February 2026. Practical comparison with pros and cons.

If you have ever built a website with HTML and CSS, you already understand the core idea behind Avalonia UI: you write a declarative markup language that describes your user interface, and a runtime engine renders it on screen. The difference is that instead of running inside a web browser, Avalonia renders directly onto the operating system's graphics surface using a GPU-accelerated engine. Your application is a native binary — not a browser tab.

Avalonia is an open-source, MIT-licensed UI framework for .NET. It lets you write applications in C# (or F#) with a XAML-based markup language and deploy them to Windows, macOS, Linux, iOS, Android, WebAssembly, and even bare-metal embedded Linux devices. The core framework has been in development since 2013, when Steven Kirk created it as a spiritual successor to Windows Presentation Foundation (WPF) at a time when WPF appeared abandoned by Microsoft.

Today, Avalonia has over 30,000 stars on GitHub, more than 87 million NuGet downloads, and is used in production by companies including JetBrains (their Rider IDE uses Avalonia for parts of its UI), Unity, GitHub, Schneider Electric, and Devolutions. It is one of the most active .NET open-source projects in the ecosystem.

Why Not Just Use a Web Browser?

You might wonder: if we already know HTML and CSS, why learn another UI framework? There are several compelling reasons.

First, native performance. A Blazor WebAssembly app (like this very website) runs inside a browser engine, which itself runs inside your operating system. Avalonia cuts out the middleman — your C# code compiles to native machine code, and the UI renders directly through GPU-accelerated pipelines. The result is dramatically faster startup, lower memory usage, and smoother animations.

Second, offline-first by default. Native applications do not need a web server. They work on airplanes, in basements, and in places without connectivity.

Third, platform integration. Native apps can access the file system, system tray, notifications, Bluetooth, USB devices, and other hardware that web applications cannot (or can only access through limited, permission-gated APIs).

Fourth, pixel-perfect consistency. Because Avalonia draws every pixel itself (rather than wrapping native platform controls), your application looks identical on every platform. There are no surprises when a button renders differently on Android versus iOS.

How Avalonia Compares to Other .NET UI Frameworks

There are several .NET UI frameworks competing for developer attention in 2026. Here is how they compare at a high level.

WPF (Windows Presentation Foundation) is Microsoft's original XAML-based desktop framework. It is mature and powerful but only runs on Windows. If you know WPF, Avalonia will feel very familiar — the API is intentionally close to WPF, though it is not a 1:1 copy. Avalonia has improvements in its styling system, property system, and template model.

.NET MAUI (Multi-platform App UI) is Microsoft's official cross-platform framework. Unlike Avalonia, MAUI wraps native platform controls — a Button on Android is an actual Android Button widget, while a Button on iOS is a UIButton. This means your app looks "native" on each platform, but it also means you are at the mercy of each platform's quirks. MAUI has struggled with adoption, bugs, and slow updates. In early 2026, developers reported significant regressions in the .NET 9 to .NET 10 transition.

Uno Platform is another cross-platform option that targets UWP/WinUI APIs. It is capable but has a different design philosophy from Avalonia.

Avalonia takes the "drawn UI" approach, similar to Flutter. It renders everything itself using SkiaSharp (the same Skia library that powers Chrome and Flutter), giving you complete control over every pixel. This approach provides more visual consistency across platforms at the cost of not looking "native" by default — though Avalonia ships with a Fluent theme that closely matches modern Windows/macOS aesthetics.

Getting Started: Your First Avalonia Application

Prerequisites

You need the .NET SDK installed. As of this writing, .NET 10 is the current LTS release. You can verify your installation:

dotnet --version
# Should output something like 10.0.104

Installing the Templates

Avalonia provides project templates through the dotnet new system:

dotnet new install Avalonia.Templates

This installs several templates. The one you will use most often is avalonia.mvvm, which sets up a project with the Model-View-ViewModel pattern:

dotnet new avalonia.mvvm -o MyFirstAvaloniaApp
cd MyFirstAvaloniaApp
dotnet run

That is it. You should see a window appear with a greeting message. If you are on Linux, it works. If you are on macOS, it works. If you are on Windows, it works. Same code, same binary (well, same source — the binary is platform-specific).

Understanding the Project Structure

After running the template, your project looks like this:

MyFirstAvaloniaApp/
├── MyFirstAvaloniaApp.csproj
├── Program.cs
├── App.axaml
├── App.axaml.cs
├── ViewLocator.cs
├── ViewModels/
│   ├── ViewModelBase.cs
│   └── MainWindowViewModel.cs
├── Views/
│   ├── MainWindow.axaml
│   └── MainWindow.axaml.cs
└── Assets/
    └── avalonia-logo.ico

Notice the .axaml file extension. This stands for "Avalonia XAML" and is used instead of plain .xaml to avoid conflicts with WPF and UWP XAML files in IDE tooling. The syntax inside is nearly identical to WPF XAML, with some improvements.

The Project File

Your .csproj file targets .NET 10 and references the Avalonia NuGet packages:

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

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <BuiltInComInteropSupport>true</BuiltInComInteropSupport>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Avalonia" Version="11.3.0" />
    <PackageReference Include="Avalonia.Desktop" Version="11.3.0" />
    <PackageReference Include="Avalonia.Themes.Fluent" Version="11.3.0" />
    <PackageReference Include="Avalonia.Fonts.Inter" Version="11.3.0" />
    <PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.0" />

    <!-- Condition below is used to add dependencies for previewer -->
    <PackageReference Include="Avalonia.Diagnostics" Version="11.3.0"
                      Condition="'$(Configuration)' == 'Debug'" />
  </ItemGroup>

</Project>

The AvaloniaUseCompiledBindingsByDefault property is important — it tells the XAML compiler to use compiled bindings by default, which are faster than reflection-based bindings and catch errors at build time rather than runtime. In Avalonia 12, this becomes true by default even if you do not set it.

Program.cs — The Entry Point

using Avalonia;
using System;

namespace MyFirstAvaloniaApp;

sealed class Program
{
    // The entry point. Don't use any Avalonia, third-party APIs
    // or any SynchronizationContext-reliant code before AppMain
    // is called; things won't be initialized yet and stuff
    // might break.
    [STAThread]
    public static void Main(string[] args) =>
        BuildAvaloniaApp()
            .StartWithClassicDesktopLifetime(args);

    // Avalonia configuration; also used by the visual designer.
    public static AppBuilder BuildAvaloniaApp() =>
        AppBuilder.Configure<App>()
            .UsePlatformDetect()
            .WithInterFont()
            .LogToTrace();
}

This is conceptually similar to a web application's Program.cs where you configure services and middleware. Here you configure the Avalonia application builder. UsePlatformDetect() automatically selects the correct rendering backend for your operating system. WithInterFont() loads the Inter font family. LogToTrace() sends log output to System.Diagnostics.Trace.

App.axaml — The Application Root

<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="MyFirstAvaloniaApp.App"
             RequestedThemeVariant="Default">
    <!-- "Default" follows system theme; use "Dark" or "Light" to force -->

    <Application.DataTemplates>
        <local:ViewLocator />
    </Application.DataTemplates>

    <Application.Styles>
        <FluentTheme />
    </Application.Styles>
</Application>

Two namespace declarations are required in every AXAML file:

• xmlns="https://github.com/avaloniaui" — the Avalonia UI namespace (equivalent to the default HTML namespace)
• xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" — the XAML language namespace (for things like x:Class, x:Name, x:Key)

The <FluentTheme /> element loads a modern Fluent Design theme that looks good on all platforms. Avalonia also ships with a "Simple" theme if you prefer a more minimal starting point.

AXAML Fundamentals: The Markup Language

If you know HTML, AXAML will feel somewhat familiar. Both are XML-based markup languages for describing visual elements. But there are important conceptual differences.

Elements Are Controls

In HTML, a <div> is a generic container. In AXAML, every element maps to a specific .NET class. A <Button> is an instance of Avalonia.Controls.Button. A <TextBlock> is an instance of Avalonia.Controls.TextBlock. There is no generic "div" equivalent — instead, you use layout panels like <StackPanel>, <Grid>, <DockPanel>, and <WrapPanel>.

A Simple Window

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="MyFirstAvaloniaApp.Views.MainWindow"
        Title="My First Avalonia App"
        Width="600" Height="400">

    <StackPanel Margin="20" Spacing="10">
        <TextBlock Text="Hello, Avalonia!"
                   FontSize="24"
                   FontWeight="Bold" />

        <TextBlock Text="This is a cross-platform .NET application."
                   Foreground="Gray" />

        <Button Content="Click Me"
                HorizontalAlignment="Left" />
    </StackPanel>

</Window>

Compare this to equivalent HTML:

<div style="margin: 20px; display: flex; flex-direction: column; gap: 10px;">
    <h1 style="font-size: 24px; font-weight: bold;">Hello, Avalonia!</h1>
    <p style="color: gray;">This is a cross-platform .NET application.</p>
    <button>Click Me</button>
</div>

The structure is similar, but AXAML uses attributes for properties (FontSize="24") instead of CSS. We will see later how Avalonia has its own styling system that separates style from structure, similar to how CSS works.

Data Binding — Connecting UI to Code

Data binding is the mechanism that connects your AXAML markup to your C# code. If you have used JavaScript frameworks like React or Vue, data binding is conceptually similar to reactive state — when the underlying data changes, the UI automatically updates.

Here is a simple example. First, the ViewModel (the C# code):

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace MyFirstAvaloniaApp.ViewModels;

public partial class MainWindowViewModel : ViewModelBase
{
    [ObservableProperty]
    private string _greeting = "Hello, Avalonia!";

    [ObservableProperty]
    private int _clickCount;

    [RelayCommand]
    private void IncrementCount()
    {
        ClickCount++;
        Greeting = $"You clicked {ClickCount} time(s)!";
    }
}

The [ObservableProperty] attribute (from CommunityToolkit.Mvvm) is a source generator that automatically creates a public property with change notification. When ClickCount changes, any UI element bound to it automatically updates. The [RelayCommand] attribute generates an ICommand property that can be bound to a button.

Now, the AXAML that binds to this ViewModel:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:vm="using:MyFirstAvaloniaApp.ViewModels"
        x:Class="MyFirstAvaloniaApp.Views.MainWindow"
        x:DataType="vm:MainWindowViewModel"
        Title="My First Avalonia App"
        Width="600" Height="400">

    <Design.DataContext>
        <!-- Provides design-time data for the IDE previewer -->
        <vm:MainWindowViewModel />
    </Design.DataContext>

    <StackPanel Margin="20" Spacing="10"
                HorizontalAlignment="Center"
                VerticalAlignment="Center">

        <TextBlock Text="{Binding Greeting}"
                   FontSize="24"
                   FontWeight="Bold"
                   HorizontalAlignment="Center" />

        <TextBlock Text="{Binding ClickCount, StringFormat='Count: {0}'}"
                   HorizontalAlignment="Center"
                   Foreground="Gray" />

        <Button Content="Click Me"
                Command="{Binding IncrementCountCommand}"
                HorizontalAlignment="Center" />
    </StackPanel>

</Window>

Key things to notice:

• xmlns:vm="using:MyFirstAvaloniaApp.ViewModels" declares a namespace prefix so we can reference our C# types in AXAML
• x:DataType="vm:MainWindowViewModel" tells the compiled binding system what type to expect as the DataContext. This enables build-time validation of your bindings.
• {Binding Greeting} is a markup extension that binds the Text property to the Greeting property on the ViewModel
• {Binding IncrementCountCommand} binds the button's Command to the auto-generated command from [RelayCommand]
• <Design.DataContext> provides a ViewModel instance for the IDE's live previewer — it does not affect runtime behavior

Layout System: Panels and Containers

Avalonia provides several layout panels, each with a different strategy for arranging child controls. If you are coming from CSS, think of these as pre-built display modes.

StackPanel — Flexbox Column/Row

StackPanel arranges children in a single line, either vertically (default) or horizontally:

<!-- Vertical stack (like CSS flex-direction: column) -->
<StackPanel Spacing="10">
    <TextBlock Text="First" />
    <TextBlock Text="Second" />
    <TextBlock Text="Third" />
</StackPanel>

<!-- Horizontal stack (like CSS flex-direction: row) -->
<StackPanel Orientation="Horizontal" Spacing="10">
    <Button Content="One" />
    <Button Content="Two" />
    <Button Content="Three" />
</StackPanel>

Grid — CSS Grid Equivalent

Grid divides space into rows and columns. This is the most powerful and commonly used layout panel:

<Grid RowDefinitions="Auto,*,Auto"
      ColumnDefinitions="200,*"
      Margin="10">

    <!-- Header spanning both columns -->
    <TextBlock Grid.Row="0" Grid.ColumnSpan="2"
               Text="Application Header"
               FontSize="20" FontWeight="Bold"
               Margin="0,0,0,10" />

    <!-- Sidebar -->
    <ListBox Grid.Row="1" Grid.Column="0"
             Margin="0,0,10,0">
        <ListBoxItem Content="Dashboard" />
        <ListBoxItem Content="Settings" />
        <ListBoxItem Content="Profile" />
    </ListBox>

    <!-- Main content area -->
    <Border Grid.Row="1" Grid.Column="1"
            Background="#f0f0f0"
            CornerRadius="8"
            Padding="20">
        <TextBlock Text="Main content goes here"
                   VerticalAlignment="Center"
                   HorizontalAlignment="Center" />
    </Border>

    <!-- Footer spanning both columns -->
    <TextBlock Grid.Row="2" Grid.ColumnSpan="2"
               Text="© 2026 My App"
               HorizontalAlignment="Center"
               Margin="0,10,0,0"
               Foreground="Gray" />
</Grid>

Row and column definitions use a size syntax:

• Auto — sizes to fit content (like CSS auto)
• * — takes remaining space proportionally (like CSS 1fr)
• 2* — takes twice the remaining space (like CSS 2fr)
• 200 — fixed pixel size

DockPanel — Edge Docking

DockPanel docks children to the edges of the container. The last child fills the remaining space:

<DockPanel>
    <!-- Top toolbar -->
    <Menu DockPanel.Dock="Top">
        <MenuItem Header="File">
            <MenuItem Header="Open" />
            <MenuItem Header="Save" />
            <Separator />
            <MenuItem Header="Exit" />
        </MenuItem>
        <MenuItem Header="Edit">
            <MenuItem Header="Undo" />
            <MenuItem Header="Redo" />
        </MenuItem>
    </Menu>

    <!-- Bottom status bar -->
    <Border DockPanel.Dock="Bottom"
            Background="#e0e0e0" Padding="5">
        <TextBlock Text="Ready" FontSize="12" />
    </Border>

    <!-- Left sidebar -->
    <Border DockPanel.Dock="Left"
            Width="200" Background="#f5f5f5"
            Padding="10">
        <TextBlock Text="Navigation" />
    </Border>

    <!-- Remaining space = main content -->
    <Border Padding="20">
        <TextBlock Text="Main Content Area" />
    </Border>
</DockPanel>

WrapPanel — Flex Wrap

WrapPanel arranges children left to right, wrapping to the next line when space runs out:

<WrapPanel Orientation="Horizontal">
    <Button Content="Tag 1" Margin="4" />
    <Button Content="Tag 2" Margin="4" />
    <Button Content="Tag 3" Margin="4" />
    <Button Content="Long Tag Name" Margin="4" />
    <Button Content="Another" Margin="4" />
    <!-- These will wrap to the next line if the container is too narrow -->
</WrapPanel>

UniformGrid — Equal-Size Grid

UniformGrid creates a grid where every cell is the same size:

<UniformGrid Columns="3" Rows="2">
    <Button Content="1" />
    <Button Content="2" />
    <Button Content="3" />
    <Button Content="4" />
    <Button Content="5" />
    <Button Content="6" />
</UniformGrid>

Styling: Avalonia's CSS-Like System

Avalonia has a styling system that is conceptually closer to CSS than WPF's styling. Styles use selectors (similar to CSS selectors) to target controls.

Basic Styles

<Window.Styles>
    <!-- Target all TextBlocks -->
    <Style Selector="TextBlock">
        <Setter Property="FontFamily" Value="Inter" />
        <Setter Property="FontSize" Value="14" />
    </Style>

    <!-- Target buttons with the "primary" class -->
    <Style Selector="Button.primary">
        <Setter Property="Background" Value="#0078d4" />
        <Setter Property="Foreground" Value="White" />
        <Setter Property="CornerRadius" Value="4" />
        <Setter Property="Padding" Value="16,8" />
    </Style>

    <!-- Hover state (like CSS :hover) -->
    <Style Selector="Button.primary:pointerover /template/ ContentPresenter">
        <Setter Property="Background" Value="#106ebe" />
    </Style>

    <!-- Target by name (like CSS #id) -->
    <Style Selector="TextBlock#PageTitle">
        <Setter Property="FontSize" Value="28" />
        <Setter Property="FontWeight" Value="Bold" />
    </Style>
</Window.Styles>

<!-- Usage -->
<StackPanel>
    <TextBlock x:Name="PageTitle" Text="Dashboard" />
    <Button Classes="primary" Content="Save Changes" />
    <Button Content="Cancel" />
</StackPanel>

Notice the CSS-like selector syntax:

• TextBlock — targets all TextBlock controls (like CSS element selectors)
• Button.primary — targets Buttons with the "primary" class (like CSS .primary)
• TextBlock#PageTitle — targets by name (like CSS #id)
• :pointerover — pseudo-class for mouse hover (like CSS :hover)
• /template/ — navigates into a control's template (unique to Avalonia)

Styles in External Files

Just like CSS can be in external files, Avalonia styles can live in separate .axaml files:

<!-- Styles/AppStyles.axaml -->
<Styles xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Style Selector="Button.danger">
        <Setter Property="Background" Value="#dc2626" />
        <Setter Property="Foreground" Value="White" />
    </Style>

    <Style Selector="Button.danger:pointerover /template/ ContentPresenter">
        <Setter Property="Background" Value="#b91c1c" />
    </Style>

</Styles>

Then include it in your App.axaml:

<Application.Styles>
    <FluentTheme />
    <StyleInclude Source="/Styles/AppStyles.axaml" />
</Application.Styles>

The MVVM Pattern: Separating Concerns

MVVM (Model-View-ViewModel) is the standard architecture pattern for Avalonia applications. It is analogous to MVC in web development but tailored for data-binding UI frameworks.

• Model — your domain objects and business logic (like your database entities and services in a web app)
• View — the AXAML markup and code-behind (like your Razor/HTML templates)
• ViewModel — the intermediary that exposes data and commands to the View (like a page model or controller)

A Complete MVVM Example: Todo List

Here is a full example of a todo list application demonstrating MVVM:

Model:

namespace MyApp.Models;

public class TodoItem
{
    public string Title { get; set; } = "";
    public bool IsCompleted { get; set; }
}

ViewModel:

using System.Collections.ObjectModel;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using MyApp.Models;

namespace MyApp.ViewModels;

public partial class TodoViewModel : ViewModelBase
{
    [ObservableProperty]
    private string _newItemTitle = "";

    public ObservableCollection<TodoItem> Items { get; } = new()
    {
        new TodoItem { Title = "Learn Avalonia", IsCompleted = false },
        new TodoItem { Title = "Build an app", IsCompleted = false },
        new TodoItem { Title = "Deploy everywhere", IsCompleted = false }
    };

    [RelayCommand(CanExecute = nameof(CanAddItem))]
    private void AddItem()
    {
        Items.Add(new TodoItem { Title = NewItemTitle });
        NewItemTitle = "";
    }

    private bool CanAddItem() =>
        !string.IsNullOrWhiteSpace(NewItemTitle);

    // The source generator knows to re-evaluate CanAddItem
    // when NewItemTitle changes because of this attribute:
    partial void OnNewItemTitleChanged(string value) =>
        AddItemCommand.NotifyCanExecuteChanged();

    [RelayCommand]
    private void RemoveItem(TodoItem item) =>
        Items.Remove(item);

    [RelayCommand]
    private void ToggleItem(TodoItem item) =>
        item.IsCompleted = !item.IsCompleted;
}

View (AXAML):

<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:vm="using:MyApp.ViewModels"
             xmlns:m="using:MyApp.Models"
             x:Class="MyApp.Views.TodoView"
             x:DataType="vm:TodoViewModel">

    <DockPanel Margin="20">
        <!-- Header -->
        <TextBlock DockPanel.Dock="Top"
                   Text="Todo List"
                   FontSize="24" FontWeight="Bold"
                   Margin="0,0,0,16" />

        <!-- Input area -->
        <Grid DockPanel.Dock="Top"
              ColumnDefinitions="*,Auto"
              Margin="0,0,0,16">
            <TextBox Grid.Column="0"
                     Text="{Binding NewItemTitle}"
                     Watermark="What needs to be done?"
                     Margin="0,0,8,0" />
            <Button Grid.Column="1"
                    Content="Add"
                    Command="{Binding AddItemCommand}"
                    Classes="primary" />
        </Grid>

        <!-- Todo list -->
        <ListBox ItemsSource="{Binding Items}"
                 x:DataType="vm:TodoViewModel">
            <ListBox.ItemTemplate>
                <DataTemplate x:DataType="m:TodoItem">
                    <Grid ColumnDefinitions="Auto,*,Auto">
                        <CheckBox Grid.Column="0"
                                  IsChecked="{Binding IsCompleted}"
                                  Margin="0,0,8,0" />
                        <TextBlock Grid.Column="1"
                                   Text="{Binding Title}"
                                   VerticalAlignment="Center" />
                        <Button Grid.Column="2"
                                Content="✕"
                                Command="{Binding
                                    $parent[ListBox].((vm:TodoViewModel)DataContext).RemoveItemCommand}"
                                CommandParameter="{Binding}"
                                Classes="danger"
                                Padding="4,2" />
                    </Grid>
                </DataTemplate>
            </ListBox.ItemTemplate>
        </ListBox>
    </DockPanel>

</UserControl>

Notice the $parent[ListBox] syntax in the Remove button's command binding. This navigates up the visual tree to find the ListBox, then accesses its DataContext (the TodoViewModel). This is how you reach the parent ViewModel from within an ItemTemplate. In HTML/JavaScript terms, this is similar to how you might call a parent component's method from a child component in React.

Desktop vs. Mobile: Why You Need Different Layouts

This is one of the most important sections of this article. If you are coming from web development, you are accustomed to responsive design — writing one set of HTML and CSS that adapts to different screen sizes using media queries. Avalonia can do something similar, but there are fundamental differences between desktop and mobile that go beyond screen size.

The Core Differences

Input model. Desktop users have a mouse with hover states, right-click context menus, precise cursor positioning, and keyboard shortcuts. Mobile users have touch with tap, swipe, pinch-to-zoom, and no hover state. A button that is 24 pixels wide works fine with a mouse cursor but is impossibly small for a human finger.

Screen real estate. A desktop monitor might be 1920×1080 or larger. A phone screen is typically 360-430 points wide in portrait mode. You simply cannot show the same information density on both.

Navigation paradigm. Desktop apps typically use menus, toolbars, and side panels that are always visible. Mobile apps use bottom navigation bars, hamburger menus, and full-screen page transitions where only one "page" is visible at a time.

Safe areas. Mobile devices have notches, rounded corners, and system gesture zones that your content must avoid. Desktop windows do not have these constraints.

Platform conventions. iOS users expect a bottom tab bar and back-swipe navigation. Android users expect a top app bar with a back button. Desktop users expect a menu bar and keyboard shortcuts. Violating these conventions makes your app feel foreign.

Strategy 1: Platform-Specific Styles with OnPlatform

Avalonia provides the OnPlatform markup extension that works like a compile-time switch statement. The compiler generates branches for all platforms, but only the matching branch executes at runtime:

<TextBlock Text="{OnPlatform Default='Hello!',
                              Android='Hello from Android!',
                              iOS='Hello from iPhone!'}" />

You can use this for any property, not just strings:

<Button Padding="{OnPlatform '8,4', Android='16,12', iOS='16,12'}"
        FontSize="{OnPlatform 14, Android=16, iOS=16}"
        CornerRadius="{OnPlatform 4, iOS=20}" />

More powerfully, you can load entirely different style sheets per platform:

<!-- In App.axaml -->
<Application.Styles>
    <FluentTheme />

    <OnPlatform>
        <On Options="Android, iOS">
            <StyleInclude Source="/Styles/Mobile.axaml" />
        </On>
        <On Options="Default">
            <StyleInclude Source="/Styles/Desktop.axaml" />
        </On>
    </OnPlatform>
</Application.Styles>

Strategy 2: Form Factor Detection with OnFormFactor

OnFormFactor distinguishes between Desktop and Mobile form factors at runtime:

<TextBlock Text="{OnFormFactor 'Desktop mode', Mobile='Mobile mode'}" />

<!-- Different margins for different form factors -->
<StackPanel Margin="{OnFormFactor '20', Mobile='12'}">
    <!-- content -->
</StackPanel>

Strategy 3: Container Queries (Introduced in Avalonia 11.3)

This is the most exciting responsive design feature in Avalonia. Container Queries work similarly to CSS Container Queries — instead of checking the viewport size, you check the size of a specific container control. This lets you build truly reusable components that adapt to the space available to them, regardless of the overall screen size.

Here is a practical example — a product card that switches between horizontal and vertical layouts:

<Border x:Name="CardContainer"
        Container.Name="card"
        Container.Sizing="Width">

    <Border.Styles>
        <!-- Vertical (narrow) layout -->
        <ContainerQuery Name="card" Query="max-width:400">
            <Style Selector="StackPanel#CardContent">
                <Setter Property="Orientation" Value="Vertical" />
            </Style>
            <Style Selector="Image#ProductImage">
                <Setter Property="Width" Value="NaN" />
                <Setter Property="Height" Value="200" />
            </Style>
        </ContainerQuery>

        <!-- Horizontal (wide) layout -->
        <ContainerQuery Name="card" Query="min-width:400">
            <Style Selector="StackPanel#CardContent">
                <Setter Property="Orientation" Value="Horizontal" />
            </Style>
            <Style Selector="Image#ProductImage">
                <Setter Property="Width" Value="200" />
                <Setter Property="Height" Value="NaN" />
            </Style>
        </ContainerQuery>
    </Border.Styles>

    <StackPanel x:Name="CardContent" Spacing="12">
        <Image x:Name="ProductImage"
               Source="/Assets/product.jpg"
               Stretch="UniformToFill" />
        <StackPanel Spacing="4" VerticalAlignment="Center">
            <TextBlock Text="Product Name" FontWeight="Bold" />
            <TextBlock Text="$29.99" Foreground="Green" />
            <TextBlock Text="A great product description..."
                       TextWrapping="Wrap" />
        </StackPanel>
    </StackPanel>
</Border>

You can combine multiple conditions with and for AND logic and , for OR logic:

<!-- Both width and height conditions must be met -->
<ContainerQuery Name="panel" Query="min-width:600 and min-height:400">
    <Style Selector="UniformGrid#ContentGrid">
        <Setter Property="Columns" Value="3" />
    </Style>
</ContainerQuery>

<!-- Either condition triggers the styles -->
<ContainerQuery Name="panel" Query="max-width:300, max-height:200">
    <Style Selector="UniformGrid#ContentGrid">
        <Setter Property="Columns" Value="1" />
    </Style>
</ContainerQuery>

Important rules for Container Queries:

1. You must declare a control as a container by setting Container.Name and Container.Sizing on it
2. Styles inside a ContainerQuery cannot affect the container itself or its ancestors (this prevents infinite layout loops)
3. ContainerQuery elements must be direct children of a control's Styles property — they cannot be nested inside other Style elements

Strategy 4: Completely Separate Views

For maximum control, you can use entirely different AXAML files for desktop and mobile. This is the approach many production applications take:

Views/
├── Desktop/
│   ├── MainView.axaml
│   ├── SettingsView.axaml
│   └── DetailView.axaml
├── Mobile/
│   ├── MainView.axaml
│   ├── SettingsView.axaml
│   └── DetailView.axaml
└── Shared/
    ├── ProductCard.axaml
    └── LoadingSpinner.axaml

You then use a view locator or conditional logic in your App to load the correct views:

// In your ViewLocator or App setup
public Control Build(object? data)
{
    if (data is null) return new TextBlock { Text = "No data" };

    var isMobile = OperatingSystem.IsAndroid() ||
                   OperatingSystem.IsIOS();

    var name = data.GetType().FullName!
        .Replace("ViewModel", "View");

    // Insert platform folder
    var platformFolder = isMobile ? "Mobile" : "Desktop";
    name = name.Replace(".Views.", $".Views.{platformFolder}.");

    var type = Type.GetType(name);

    if (type is not null)
        return (Control)Activator.CreateInstance(type)!;

    return new TextBlock { Text = $"View not found: {name}" };
}

Practical Example: Master-Detail on Desktop vs. Mobile

Here is a concrete example showing how the same feature (a contacts list with detail view) needs fundamentally different UI on desktop versus mobile.

Desktop Version — side-by-side layout with the list always visible:

<!-- Views/Desktop/ContactsView.axaml -->
<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:vm="using:MyApp.ViewModels"
             x:Class="MyApp.Views.Desktop.ContactsView"
             x:DataType="vm:ContactsViewModel">

    <Grid ColumnDefinitions="300,*">
        <!-- Left: always-visible contact list -->
        <Border Grid.Column="0"
                BorderBrush="#e0e0e0"
                BorderThickness="0,0,1,0">
            <DockPanel>
                <TextBox DockPanel.Dock="Top"
                         Text="{Binding SearchText}"
                         Watermark="Search contacts..."
                         Margin="8" />

                <ListBox ItemsSource="{Binding FilteredContacts}"
                         SelectedItem="{Binding SelectedContact}">
                    <ListBox.ItemTemplate>
                        <DataTemplate>
                            <StackPanel Orientation="Horizontal"
                                        Spacing="8" Margin="4">
                                <Ellipse Width="32" Height="32"
                                         Fill="#0078d4" />
                                <StackPanel VerticalAlignment="Center">
                                    <TextBlock Text="{Binding Name}"
                                               FontWeight="SemiBold" />
                                    <TextBlock Text="{Binding Email}"
                                               FontSize="12"
                                               Foreground="Gray" />
                                </StackPanel>
                            </StackPanel>
                        </DataTemplate>
                    </ListBox.ItemTemplate>
                </ListBox>
            </DockPanel>
        </Border>

        <!-- Right: detail panel -->
        <ScrollViewer Grid.Column="1" Padding="20">
            <StackPanel Spacing="12"
                        IsVisible="{Binding SelectedContact,
                            Converter={x:Static ObjectConverters.IsNotNull}}">
                <TextBlock Text="{Binding SelectedContact.Name}"
                           FontSize="28" FontWeight="Bold" />
                <TextBlock Text="{Binding SelectedContact.Email}" />
                <TextBlock Text="{Binding SelectedContact.Phone}" />
                <TextBlock Text="{Binding SelectedContact.Notes}"
                           TextWrapping="Wrap" />
            </StackPanel>
        </ScrollViewer>
    </Grid>

</UserControl>

Mobile Version — full-screen list that pushes to a full-screen detail:

<!-- Views/Mobile/ContactsView.axaml -->
<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:vm="using:MyApp.ViewModels"
             x:Class="MyApp.Views.Mobile.ContactsView"
             x:DataType="vm:ContactsViewModel">

    <Panel>
        <!-- Contact list (full screen) -->
        <DockPanel IsVisible="{Binding !IsDetailVisible}">
            <TextBox DockPanel.Dock="Top"
                     Text="{Binding SearchText}"
                     Watermark="Search contacts..."
                     Margin="12"
                     Padding="16,12"
                     FontSize="16" />

            <ListBox ItemsSource="{Binding FilteredContacts}"
                     SelectedItem="{Binding SelectedContact}">
                <ListBox.ItemTemplate>
                    <DataTemplate>
                        <!-- Larger touch targets for mobile -->
                        <StackPanel Orientation="Horizontal"
                                    Spacing="12"
                                    Margin="12,8">
                            <Ellipse Width="48" Height="48"
                                     Fill="#0078d4" />
                            <StackPanel VerticalAlignment="Center">
                                <TextBlock Text="{Binding Name}"
                                           FontSize="16"
                                           FontWeight="SemiBold" />
                                <TextBlock Text="{Binding Email}"
                                           FontSize="14"
                                           Foreground="Gray" />
                            </StackPanel>
                        </StackPanel>
                    </DataTemplate>
                </ListBox.ItemTemplate>
            </ListBox>
        </DockPanel>

        <!-- Detail view (full screen, overlays list) -->
        <DockPanel IsVisible="{Binding IsDetailVisible}">
            <!-- Back button -->
            <Button DockPanel.Dock="Top"
                    Content="← Back"
                    Command="{Binding GoBackCommand}"
                    Padding="16,12"
                    FontSize="16"
                    Background="Transparent"
                    HorizontalAlignment="Left" />

            <ScrollViewer Padding="16">
                <StackPanel Spacing="16">
                    <TextBlock Text="{Binding SelectedContact.Name}"
                               FontSize="24" FontWeight="Bold" />
                    <TextBlock Text="{Binding SelectedContact.Email}"
                               FontSize="16" />
                    <TextBlock Text="{Binding SelectedContact.Phone}"
                               FontSize="16" />
                    <TextBlock Text="{Binding SelectedContact.Notes}"
                               FontSize="16"
                               TextWrapping="Wrap" />
                </StackPanel>
            </ScrollViewer>
        </DockPanel>
    </Panel>

</UserControl>

The key differences in the mobile version:

• Larger text (FontSize="16" everywhere) for readability
• Larger touch targets (48px avatars, 16px padding on buttons)
• Full-screen navigation instead of side-by-side panels
• An explicit "Back" button since there is no always-visible list
• IsDetailVisible boolean that toggles between list and detail views

Both views share the exact same ContactsViewModel — the business logic does not change, only the presentation.

Platform-Specific Code in C#

Sometimes you need to execute different code depending on the platform. The .NET OperatingSystem class provides static methods:

public void ConfigurePlatformFeatures()
{
    if (OperatingSystem.IsWindows())
    {
        // Set up Windows-specific features like jump lists
    }
    else if (OperatingSystem.IsMacOS())
    {
        // Configure macOS menu bar
    }
    else if (OperatingSystem.IsLinux())
    {
        // Linux-specific setup
    }
    else if (OperatingSystem.IsAndroid())
    {
        // Android permissions, status bar color, etc.
    }
    else if (OperatingSystem.IsIOS())
    {
        // iOS setup, safe areas, etc.
    }
    else if (OperatingSystem.IsBrowser())
    {
        // WebAssembly-specific setup
    }
}

Building for Each Platform

Desktop (Windows, macOS, Linux)

The default template targets desktop. Build and run with:

dotnet run

To publish a self-contained binary:

# Windows
dotnet publish -c Release -r win-x64 --self-contained

# macOS (Apple Silicon)
dotnet publish -c Release -r osx-arm64 --self-contained

# Linux
dotnet publish -c Release -r linux-x64 --self-contained

Android

Add the Android target to your project. The Avalonia templates include an Android head project:

dotnet new avalonia.xplat -o MyCrossApp

This creates a solution with separate head projects for each platform:

MyCrossApp/
├── MyCrossApp/                    # Shared code (ViewModels, Models)
├── MyCrossApp.Desktop/            # Desktop entry point
├── MyCrossApp.Android/            # Android entry point
├── MyCrossApp.iOS/                # iOS entry point
└── MyCrossApp.Browser/            # WebAssembly entry point

The Android project's MainActivity.cs:

using Android.App;
using Android.Content.PM;
using Avalonia;
using Avalonia.Android;

namespace MyCrossApp.Android;

[Activity(
    Label = "MyCrossApp",
    Theme = "@style/MyTheme.NoActionBar",
    Icon = "@drawable/icon",
    MainLauncher = true,
    ConfigurationChanges = ConfigChanges.Orientation
                         | ConfigChanges.ScreenSize
                         | ConfigChanges.UiMode)]
public class MainActivity : AvaloniaMainActivity<App>
{
    protected override AppBuilder CustomizeAppBuilder(AppBuilder builder) =>
        base.CustomizeAppBuilder(builder)
            .WithInterFont();
}

Build and deploy to an Android device:

dotnet build -t:Run -f net10.0-android

iOS

The iOS entry point is similar:

using Avalonia;
using Avalonia.iOS;
using Foundation;
using UIKit;

namespace MyCrossApp.iOS;

[Register("AppDelegate")]
public partial class AppDelegate : AvaloniaAppDelegate<App>
{
    protected override AppBuilder CustomizeAppBuilder(AppBuilder builder) =>
        base.CustomizeAppBuilder(builder)
            .WithInterFont();
}

Build for iOS (requires macOS with Xcode):

dotnet build -t:Run -f net10.0-ios

WebAssembly

The Browser project uses Avalonia's WebAssembly support:

using Avalonia;
using Avalonia.Browser;
using MyCrossApp;

internal sealed partial class Program
{
    private static Task Main(string[] args) =>
        BuildAvaloniaApp()
            .WithInterFont()
            .StartBrowserAppAsync("out");

    public static AppBuilder BuildAvaloniaApp() =>
        AppBuilder.Configure<App>();
}

Build and serve:

dotnet run --project MyCrossApp.Browser

Common Controls Reference

Here is a quick reference of the most commonly used controls, with AXAML examples:

Text Display and Input

<!-- Read-only text -->
<TextBlock Text="Static text" FontSize="16" />

<!-- Selectable text -->
<SelectableTextBlock Text="You can select and copy this text" />

<!-- Single-line input -->
<TextBox Text="{Binding Name}"
         Watermark="Enter your name"
         MaxLength="100" />

<!-- Multi-line input -->
<TextBox Text="{Binding Notes}"
         AcceptsReturn="True"
         TextWrapping="Wrap"
         Height="120" />

<!-- Password input -->
<TextBox Text="{Binding Password}"
         PasswordChar="●"
         RevealPassword="{Binding ShowPassword}" />

<!-- Numeric input -->
<NumericUpDown Value="{Binding Quantity}"
               Minimum="0" Maximum="100"
               Increment="1" />

Selection Controls

<!-- Checkbox -->
<CheckBox IsChecked="{Binding AgreeToTerms}"
          Content="I agree to the terms and conditions" />

<!-- Radio buttons -->
<StackPanel Spacing="8">
    <RadioButton GroupName="Size" Content="Small"
                 IsChecked="{Binding IsSmall}" />
    <RadioButton GroupName="Size" Content="Medium"
                 IsChecked="{Binding IsMedium}" />
    <RadioButton GroupName="Size" Content="Large"
                 IsChecked="{Binding IsLarge}" />
</StackPanel>

<!-- Dropdown (ComboBox) -->
<ComboBox ItemsSource="{Binding Countries}"
          SelectedItem="{Binding SelectedCountry}"
          PlaceholderText="Select a country" />

<!-- Slider -->
<Slider Value="{Binding Volume}"
        Minimum="0" Maximum="100"
        TickFrequency="10"
        IsSnapToTickEnabled="True" />

<!-- Toggle switch -->
<ToggleSwitch IsChecked="{Binding DarkMode}"
              OnContent="Dark"
              OffContent="Light" />

<!-- Date picker -->
<DatePicker SelectedDate="{Binding BirthDate}" />

Data Display

<!-- List with data binding -->
<ListBox ItemsSource="{Binding Customers}"
         SelectedItem="{Binding SelectedCustomer}">
    <ListBox.ItemTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding Name}" />
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>

<!-- Tree view -->
<TreeView ItemsSource="{Binding RootFolders}">
    <TreeView.ItemTemplate>
        <TreeDataTemplate ItemsSource="{Binding Children}">
            <TextBlock Text="{Binding Name}" />
        </TreeDataTemplate>
    </TreeView.ItemTemplate>
</TreeView>

<!-- Tab control -->
<TabControl>
    <TabItem Header="General">
        <TextBlock Text="General settings here" Margin="10" />
    </TabItem>
    <TabItem Header="Advanced">
        <TextBlock Text="Advanced settings here" Margin="10" />
    </TabItem>
    <TabItem Header="About">
        <TextBlock Text="Version 1.0" Margin="10" />
    </TabItem>
</TabControl>

Progress and Status

<!-- Determinate progress -->
<ProgressBar Value="{Binding DownloadProgress}"
             Maximum="100"
             ShowProgressText="True" />

<!-- Indeterminate (spinning) -->
<ProgressBar IsIndeterminate="True" />

<!-- Expander (collapsible section) -->
<Expander Header="Advanced Options" IsExpanded="False">
    <StackPanel Spacing="8" Margin="0,8,0,0">
        <CheckBox Content="Enable logging" />
        <CheckBox Content="Verbose output" />
    </StackPanel>
</Expander>

Dialogs and Overlays

Avalonia does not have a built-in modal dialog system like web browsers' alert() and confirm(). Instead, you typically use the window system:

// Show a message dialog
var dialog = new Window
{
    Title = "Confirm Delete",
    Width = 400,
    Height = 200,
    WindowStartupLocation = WindowStartupLocation.CenterOwner,
    Content = new StackPanel
    {
        Margin = new Thickness(20),
        Spacing = 16,
        Children =
        {
            new TextBlock
            {
                Text = "Are you sure you want to delete this item?",
                TextWrapping = TextWrapping.Wrap
            },
            new StackPanel
            {
                Orientation = Avalonia.Layout.Orientation.Horizontal,
                Spacing = 8,
                HorizontalAlignment = HorizontalAlignment.Right,
                Children =
                {
                    new Button { Content = "Cancel" },
                    new Button { Content = "Delete", Classes = { "danger" } }
                }
            }
        }
    }
};

await dialog.ShowDialog(parentWindow);

Or you can use a community library like DialogHost.Avalonia for overlay-style dialogs.

What Is Coming in Avalonia 12

Avalonia 12 is currently in preview (Preview 1 was released in February 2026) and is expected to reach stable release in Q4 2026. The two guiding themes are Performance and Stability.

Performance and Stability Focus

Unlike Avalonia 11, which was a massive release adding multiple new platforms and a completely new compositional renderer, Avalonia 12 is deliberately conservative. The goal is a rock-solid foundation that the ecosystem can build on for years. Some of the largest enterprise users are already running nightly builds in production to access Android performance improvements.

On the Android platform specifically, Avalonia 12 includes a new dispatcher implementation based on Looper and MessageQueue that improves scheduling reliability. GPU and CPU underutilisation at high refresh rates has been addressed. Multiple activities with Avalonia content are now supported.

Breaking Changes You Need to Know

Minimum target is now .NET 8. Support for netstandard2.0 and .NET Framework 4.x has been dropped. According to Avalonia's telemetry, these targets account for less than 4% of projects. The team has committed to supporting .NET 8 for the full lifecycle of Avalonia 12.

SkiaSharp 3.0 is required. SkiaSharp 2.88 support has been removed.

Compiled bindings are now the default. The AvaloniaUseCompiledBindingsByDefault property is now true by default. Any {Binding} usage in AXAML maps to {CompiledBinding}. This means your bindings are faster and errors are caught at build time, but it also means you must specify x:DataType on your views.

Binding plugins removed. The binding plugin system (including the data annotations validation plugin) has been removed. This was effectively unused by most developers and conflicted with popular frameworks like CommunityToolkit.Mvvm.

Window decorations overhaul. A new WindowDrawnDecorations class replaces the old TitleBar, CaptionButtons, and ChromeOverlayLayer types. The SystemDecorations property has been renamed to WindowDecorations. This enables themeable, fully-drawn window chrome.

Selection behavior unified. Touch and pen input now triggers selection on pointer release (not press), matching native platform conventions.

TopLevel changes. A TopLevel object is no longer necessarily at the root of the visual hierarchy. Code that casts the top Visual to TopLevel will break. Use TopLevel.GetTopLevel(visual) instead.

Migration from Avalonia 11

If you have been addressing deprecation warnings in Avalonia 11, migration should be straightforward. The team has published a complete breaking changes guide. Here is a practical migration checklist:

<!-- Before (Avalonia 11) -->
<Window SystemDecorations="Full" ... >

<!-- After (Avalonia 12) -->
<Window WindowDecorations="Full" ... >

// Before (Avalonia 11)
var topLevel = (TopLevel)visual.GetVisualRoot()!;

// After (Avalonia 12)
var topLevel = TopLevel.GetTopLevel(visual)!;

<!-- Before (Avalonia 11) — might work without x:DataType -->
<TextBlock Text="{Binding Name}" />

<!-- After (Avalonia 12) — x:DataType required for compiled bindings -->
<UserControl x:DataType="vm:MyViewModel" ...>
    <TextBlock Text="{Binding Name}" />
</UserControl>

WebView Going Open Source

One of the most exciting announcements for Avalonia 12 is that the WebView control is going open source. Previously, WebView was a commercial-only feature in Avalonia's Accelerate product. The WebView uses native platform web rendering (Edge WebView2 on Windows, WebKit on macOS/iOS, WebView on Android) rather than bundling Chromium, keeping your application lean.

The Avalonia team acknowledged that embedding web content has become a baseline requirement for many applications — OAuth flows, documentation rendering, rich content display — and gating it behind a commercial licence was no longer the right decision. The open-source WebView will ship in an upcoming Avalonia 12 pre-release.

New Table Control

Avalonia 12 will include a new read-only Table control for displaying tabular data. This is entirely open-source and free. For complex data grids with editing, sorting, and advanced features, the existing open-source TreeDataGrid remains available (and can be forked), or commercial offerings provide additional capabilities.

Beyond Avalonia 12: The Rendering Revolution

The Vello Experiment

Avalonia's rendering has been built on SkiaSharp since the project's earliest days. SkiaSharp provides .NET bindings for Skia, Google's 2D graphics library that also powers Chrome and (formerly) Flutter. It is mature, stable, and well-understood.

But Avalonia is now exploring GPU-first rendering as a next step. Among several approaches being investigated, Vello — a modern graphics engine written in Rust — has shown particularly interesting early results.

Vello is "GPU-first" by design. Traditional rendering pipelines (including Skia) perform most work on the CPU and use the GPU primarily for final compositing. Vello inverts this model, pushing nearly all rendering computation to the GPU using compute shaders.

Early stress testing shows tens of thousands of animated vector paths running at smooth 120 FPS. In certain workloads, the Avalonia team observed Vello performing up to 100x faster than SkiaSharp. Even when running through a Skia-compatibility shim built on top of Vello, they saw 8x speed improvements.

The community has already started building on this. Wiesław Šoltés has published VelloSharp, a .NET binding library for Vello with Avalonia integration packages, including chart controls and canvas controls powered by Vello rendering.

However, Vello is not a drop-in replacement. SkiaSharp will remain the default renderer for the foreseeable future. The Vello work will ship as experimental backends during the Avalonia 12 lifecycle.

The Impeller Partnership with Google

In a surprising move, the Avalonia team announced a partnership with Google's Flutter engineers to bring Impeller — Flutter's next-generation GPU-first renderer — to .NET.

Impeller was created to solve real-world performance challenges Flutter encountered with Skia, particularly shader compilation "jank" (visible stuttering the first time a shader is compiled on a device). It pre-compiles all shader pipelines at build time, eliminating runtime compilation entirely.

Why Impeller over Vello? Early testing revealed an important tradeoff: while Vello achieved identical frame rates to Impeller in benchmarks, it required roughly twelve times more power to do so. For battery-powered mobile devices, that difference is significant.

Flutter's production benchmarks with Impeller show impressive improvements: faster SVG and path rendering, improved Gaussian blur throughput, frame times for complex clipping reduced from 450ms with Skia to 11ms with Impeller, no shader compilation stutter, and around 100MB less memory usage.

The Impeller integration is experimental and all development is happening in public. The goal is to benefit not just Avalonia but the entire .NET ecosystem.

Avalonia MAUI: Bringing Linux and WASM to .NET MAUI

In another ambitious initiative, the Avalonia team is building handlers that let .NET MAUI applications run on Linux and WebAssembly — two platforms that Microsoft's MAUI does not support. The first preview was announced in March 2026, running on .NET 11 (itself in preview).

The approach works by building a single set of Avalonia-based handlers that map MAUI controls to Avalonia equivalents. Because Avalonia already includes a SkiaSharp-based renderer, it can leverage the existing Microsoft.Maui.Graphics and SkiaSharp.Controls.Maui libraries. This means many MAUI controls work with minimal changes.

This work has also been driving improvements back into Avalonia itself, with new controls like SwipeView and API enhancements like letter-spacing support propagated to every control.

Licensing and Costs

This is an important topic for the Observer Magazine audience, since our philosophy is that everything should be free — no "free for non-commercial" caveats.

Avalonia UI core framework: MIT license, free forever. You can build and ship commercial applications with it, no payment required, no restrictions. This is not changing.

Avalonia Accelerate is the commercial tooling suite built around the framework. It includes a rewritten Visual Studio extension, Dev Tools (a runtime inspector), and Parcel (a packaging tool). Accelerate has a Community Edition that is free for individual developers, small organizations (fewer than 250 people / less than €1M revenue), and educational institutions. Enterprise organizations need a paid license only if they want to use these new Accelerate tools — they can always use the core framework and the legacy open-source tooling for free.

JetBrains Rider and VS Code extensions remain free regardless of organization size.

For our project, we can use Avalonia without any cost, forever. The core framework, the community tooling, and the IDE extensions for Rider and VS Code are all free.

Setting Up an Avalonia Project with Modern .NET Practices

Here is how to set up an Avalonia project using the same modern .NET practices we use in Observer Magazine — .slnx solution format, Directory.Build.props, and central package management:

global.json

{
  "sdk": {
    "version": "10.0.104",
    "rollForward": "latestFeature"
  }
}

Directory.Build.props

<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
  </PropertyGroup>
</Project>

Directory.Packages.props

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <AvaloniaVersion>11.3.0</AvaloniaVersion>
    <CommunityToolkitVersion>8.4.0</CommunityToolkitVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Avalonia" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="Avalonia.Desktop" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="Avalonia.iOS" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="Avalonia.Android" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="Avalonia.Browser" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="Avalonia.Themes.Fluent" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="Avalonia.Fonts.Inter" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="Avalonia.Diagnostics" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="CommunityToolkit.Mvvm"
                    Version="$(CommunityToolkitVersion)" />

    <!-- Testing -->
    <PackageVersion Include="Avalonia.Headless.XUnit" Version="$(AvaloniaVersion)" />
    <PackageVersion Include="xunit.v3" Version="3.2.2" />
    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
  </ItemGroup>
</Project>

Solution File (MyApp.slnx)

<Solution>
  <Folder Name="/Solution Items/">
    <File Path="Directory.Build.props" />
    <File Path="Directory.Packages.props" />
    <File Path="global.json" />
  </Folder>
  <Folder Name="/src/">
    <Project Path="src/MyApp/MyApp.csproj" />
    <Project Path="src/MyApp.Desktop/MyApp.Desktop.csproj" />
    <Project Path="src/MyApp.Android/MyApp.Android.csproj" />
    <Project Path="src/MyApp.iOS/MyApp.iOS.csproj" />
    <Project Path="src/MyApp.Browser/MyApp.Browser.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/MyApp.Tests/MyApp.Tests.csproj" />
  </Folder>
</Solution>

Testing Avalonia Applications

Avalonia supports headless testing — running your UI without a visible window. This is perfect for CI/CD pipelines:

using Avalonia.Headless.XUnit;
using MyApp.ViewModels;
using MyApp.Views;
using Xunit;

namespace MyApp.Tests;

public class MainWindowTests
{
    [AvaloniaFact]
    public void MainWindow_Should_Render_Title()
    {
        var window = new MainWindow
        {
            DataContext = new MainWindowViewModel()
        };

        window.Show();

        // Find the title TextBlock by name
        var title = window.FindControl<TextBlock>("PageTitle");
        Assert.NotNull(title);
        Assert.Equal("Dashboard", title.Text);
    }

    [AvaloniaFact]
    public void Button_Click_Should_Increment_Counter()
    {
        var vm = new MainWindowViewModel();
        var window = new MainWindow { DataContext = vm };

        window.Show();

        Assert.Equal(0, vm.ClickCount);

        vm.IncrementCountCommand.Execute(null);

        Assert.Equal(1, vm.ClickCount);
    }
}

The [AvaloniaFact] attribute (from Avalonia.Headless.XUnit) sets up the Avalonia runtime in headless mode before each test.

Putting It All Together: A Production Architecture

Here is a summary architecture for a production cross-platform Avalonia application:

MyProductionApp/
├── global.json
├── Directory.Build.props
├── Directory.Packages.props
├── MyApp.slnx
│
├── src/
│   ├── MyApp/                          # Shared library
│   │   ├── MyApp.csproj
│   │   ├── App.axaml                   # Application root
│   │   ├── App.axaml.cs
│   │   ├── ViewLocator.cs
│   │   ├── Models/                     # Domain objects
│   │   ├── ViewModels/                 # MVVM ViewModels
│   │   ├── Services/                   # Business logic
│   │   │   ├── IDataService.cs
│   │   │   ├── SqliteDataService.cs
│   │   │   └── ApiDataService.cs
│   │   ├── Views/
│   │   │   ├── Desktop/                # Desktop-specific views
│   │   │   ├── Mobile/                 # Mobile-specific views
│   │   │   └── Shared/                 # Shared components
│   │   └── Styles/
│   │       ├── Desktop.axaml
│   │       └── Mobile.axaml
│   │
│   ├── MyApp.Desktop/                  # Desktop entry point
│   │   ├── MyApp.Desktop.csproj
│   │   └── Program.cs
│   │
│   ├── MyApp.Android/                  # Android entry point
│   │   ├── MyApp.Android.csproj
│   │   └── MainActivity.cs
│   │
│   ├── MyApp.iOS/                      # iOS entry point
│   │   ├── MyApp.iOS.csproj
│   │   └── AppDelegate.cs
│   │
│   └── MyApp.Browser/                  # WebAssembly entry point
│       ├── MyApp.Browser.csproj
│       └── Program.cs
│
└── tests/
    └── MyApp.Tests/
        ├── MyApp.Tests.csproj
        ├── ViewModelTests/
        └── ViewTests/

The shared library (MyApp) contains all your views, view models, models, and services. The platform-specific projects (MyApp.Desktop, MyApp.Android, etc.) are thin wrappers that just configure the platform entry point and reference the shared library.

Conclusion

Avalonia UI occupies a unique position in the .NET ecosystem. It is the only framework that gives you pixel-perfect consistency across Windows, macOS, Linux, iOS, Android, and WebAssembly from a single codebase, using familiar XAML-based tooling. The MIT license means you can use it for anything, forever, at no cost.

The current stable release (11.3) is production-ready and used by major companies. Container Queries bring modern responsive design patterns to native application development. The OnPlatform and OnFormFactor markup extensions make it straightforward to customize behavior per platform and device type.

Avalonia 12 (currently in preview, targeting Q4 2026 stable release) doubles down on performance and stability, with significant Android improvements, compiled bindings by default, a new open-source WebView, and a new Table control. The upcoming rendering revolution — with experimental Vello backends and the Impeller partnership with Google — points toward a future where Avalonia applications run faster than ever on modern GPU hardware.

If you are a web developer looking to build native cross-platform applications without leaving the .NET ecosystem, Avalonia is the most compelling option available today. The learning curve from web development is manageable — AXAML is conceptually similar to HTML, Avalonia's styling system borrows heavily from CSS concepts, and the MVVM pattern maps naturally to the component-based architecture you already know.

The best way to learn is to build something. Install the templates, create a project, and start experimenting. The community is active on GitHub and the Avalonia documentation continues to improve rapidly.

Welcome to the world of truly cross-platform native development.

Resources

• Official Documentation: docs.avaloniaui.net
• GitHub Repository: github.com/AvaloniaUI/Avalonia (30,000+ stars)
• Sample Projects: github.com/AvaloniaUI/Avalonia.Samples
• Avalonia 12 Breaking Changes: docs.avaloniaui.net/docs/avalonia12-breaking-changes
• Container Queries Documentation: docs.avaloniaui.net/docs/basics/user-interface/styling/container-queries
• Platform-Specific XAML: docs.avaloniaui.net/docs/guides/platforms/platform-specific-code/xaml

Picture this. You are sitting at a red light. Maybe it is a Tuesday morning. Maybe you slept badly. Maybe you are running a little late. The light turns green. And before your foot has even moved toward the gas pedal — honk. The driver behind you, piloting a Ford F-150 the size of a small building, has decided that you are the problem.

What do you do?

Most people instinctively hit the gas. Not because it is safe. Not because they have checked the intersection. But because being honked at feels like being told off by a teacher, and the lizard part of our brain wants to comply and make the discomfort stop.

Here is the thing, though. That green light does not order you to go. It permits you to go.

There is a meaningful difference between those two things — and understanding it might be one of the most useful mental models you ever pick up.

What the Intersection Actually Looks Like

Let us slow the moment down.

The light turns green. The truck honks. You feel the pressure. But what is actually happening in that intersection?

• There may be a car that jumped its red light and is still clearing the box.
• There may be a cyclist coming through on the left that you can see but the truck — sitting higher and further back — cannot.
• There may be a driver doing 80 miles per hour who ran the light entirely and is about to enter the intersection in the next two seconds.

You, in the driver's seat, have information the truck driver does not have. You have the view. You have the angle. You have the responsibility. And crucially, you are the one whose life is on the line if you get it wrong.

The truck driver experiences zero consequences if you pull out and get T-boned. He will be inconvenienced. He might feel bad. But he goes home. You are the one gambling.

So when you take that extra second — or two, or three — to check that it is genuinely clear before you go, that is not timidity. That is not weakness. That is exactly what a careful, thinking person is supposed to do.

Free Will at the Green Light

There is something quietly radical about that pause.

In that moment, you are exercising one of the most underrated things a human being has: the freedom to not be rushed into a decision by someone else's impatience.

You did not ask for that honk. You did not agree to be managed by a stranger. And yet social pressure — even the blunt, anonymous kind that comes from a car horn — is remarkably effective at overriding our own judgment.

Recognising that you have a choice, even when someone is pushing you, is a skill. It does not come naturally to most people. But once you feel it — once you sit in that driver's seat and consciously decide I will go when I am ready and not a moment before — it changes something.

Now Apply It to Everything Else

You might be reading this thinking: fine, interesting driving tip, but what does this have to do with my life?

Everything.

Every day, in work and in life, you are sitting at green lights with someone behind you leaning on the horn. The situations change. The pressure does not.

At Work

Your manager sends a message at 4:58 PM asking for a report "as soon as possible." Your gut says to fire off whatever you have and hit send before 5. But is the report actually ready? Is the data right? Will a rushed report serve you — or will it come back to bite you next week when someone finds the error you missed?

The truck is honking. The light is green. But is the intersection clear?

A better move: take a breath, reply to acknowledge the request, and send the report when it is accurate. A good manager would rather have a correct report at 9 AM than a wrong one at 5 PM. And if they would not — that tells you something important about them.

In a Negotiation

You are buying a house, a car, or signing a contract. The other party says the offer expires tonight. We have three other buyers. You need to decide now.

That is a horn honk. Sometimes it is even true. But more often it is a tactic — pressure designed to make you skip your own due diligence and commit before you have checked the intersection.

The move is the same: pause, look both ways, and proceed only when you are satisfied. Deals that evaporate the moment you ask for a day to think about them are often deals you are better off without.

In Relationships

A friend, a partner, or a family member wants an answer — now. Are you coming to the event? Do you forgive them? Are you in or out? The emotional equivalent of a horn honk is very real, and it works on us even more powerfully than the literal kind.

You are allowed to say: I need a moment to think about this. That is not cruelty. That is self-respect. Anyone who tells you that taking time to make a thoughtful decision is an act of disrespect is, in all likelihood, someone who benefits from your impulsiveness.

In Your Career

A recruiter calls with an offer. The role sounds exciting. The salary is good. They need an answer by end of day. What do you do?

Same as always: look left, look right. Do you know enough about the company culture? Have you actually read the contract? Is there something you cannot see from your position — something the person behind you definitely cannot see?

Taking 24 hours to think about a job offer is completely reasonable. If an employer rescinds an offer because you asked for a day to consider it properly, you just learned something invaluable about how they make decisions — before you ever started working for them.

The Principle, Simply Stated

You do not owe anyone a rushed decision.

You have the right — and often the responsibility — to take the time needed to make a safe and considered choice. The people pressuring you are not in your seat. They do not have your view. They do not bear your consequences.

This does not mean be paralysed. Green lights are not invitations to sit indefinitely. At some point, you do pull out into the intersection, because staying stopped forever is its own kind of failure. The goal is not to be frozen — the goal is to be deliberate.

Check. Think. Decide. Then go.

A Quick Reference: The Green Light Test

When you feel pressured to make a fast decision, run through these before you act:

1. Do I have enough information? If not, what would it take to get it — and how long would that actually require?
2. Who bears the consequences if this goes wrong? If the answer is me, then I should be the one setting the pace.
3. Is this urgency real or manufactured? Real urgency exists. Artificial urgency is a tactic. Learn to tell the difference.
4. What does my gut say — underneath the panic? The noise of someone honking tends to drown out the quieter, wiser voice. Try to hear it.
5. Would I make this same decision if no one were watching or waiting? If the answer is no, you have your answer.

Final Thought

The Ford F-150 driver will survive the extra three seconds it takes you to check the intersection. He will probably not even remember the moment by the time he reaches his destination.

But you will remember — and so will your passengers — whether you made it through safely.

Take the moment. Check the road. Go when you are ready.

That is not hesitation. That is wisdom.

Published in Observer Magazine. We welcome your thoughts — reach out through the contact page or find us on GitHub at ObserverMagazine.

The year 2025 was one of the most consequential in recent memory. From a dramatic change in American leadership and its rippling effects across every domain of public life, to breakthroughs in artificial intelligence that rewrote the rules of entire industries, to geopolitical conflicts that continued to reshape the world order, 2025 demanded attention from start to finish. This article attempts to chronicle every major newsworthy event of the year, organized by topic.

Part 1: United States Politics

The Second Trump Administration Begins

On January 20, 2025, Donald J. Trump was inaugurated as the 47th President of the United States, beginning his second non-consecutive term. The inauguration itself was moved indoors to the Capitol Rotunda due to dangerously cold weather in Washington, D.C. The ceremony was attended by an unusual number of tech industry leaders, including Elon Musk, Jeff Bezos, Mark Zuckerberg, Tim Cook, and Sundar Pichai, reflecting the evolving relationship between Silicon Valley and the new administration.

Executive Orders and Policy Changes

The administration moved with extraordinary speed in its opening days. On the first day alone, President Trump signed dozens of executive orders covering immigration, energy policy, diversity programs, and federal workforce restructuring.

On immigration, the administration declared a national emergency at the southern border, deployed additional military personnel, and began implementing what it described as the largest deportation operation in American history. The "Remain in Mexico" policy was reinstated. Birthright citizenship was challenged through executive order, though this faced immediate legal challenges and was blocked by federal courts.

Federal diversity, equity, and inclusion (DEI) programs were terminated across all government agencies. Federal employees working in DEI roles were placed on administrative leave. Executive orders directed agencies to investigate and potentially penalize private companies and universities that maintained DEI programs, though enforcement proved complex.

The administration withdrew the United States from the Paris Climate Agreement for a second time. Drilling permits on federal lands were expedited. The Keystone XL pipeline permit was reinstated. Multiple environmental regulations from the previous administration were rescinded or paused.

The TikTok Ban and Reprieve

One of the most closely watched policy dramas of early 2025 involved TikTok. A law passed during the Biden administration required ByteDance, TikTok's Chinese parent company, to divest its ownership of TikTok or face a ban in the United States. The deadline arrived on January 19, 2025, the day before inauguration. TikTok briefly went dark for American users. President Trump then signed an executive order granting a 75-day extension, and later additional extensions, to allow negotiations for a potential sale. Throughout 2025, various consortiums of American investors explored acquisition deals, but no final sale was completed by year's end.

The Department of Government Efficiency

Elon Musk led what the administration called the Department of Government Efficiency (DOGE), a task force aimed at dramatically reducing federal spending and workforce. DOGE identified programs it considered wasteful and pushed for their elimination. The effort was controversial, with supporters praising the focus on fiscal responsibility and critics arguing that essential services were being gutted. Federal employee unions challenged many of the actions in court. By mid-2025, DOGE claimed billions in projected savings, though independent analyses disputed the methodology.

Pardons and Legal Matters

President Trump pardoned or commuted sentences for many individuals convicted in connection with the January 6, 2021 Capitol breach. This was one of the most debated actions of the early administration, with supporters characterizing the defendants as political prisoners and critics arguing that pardoning participants in a violent breach of the Capitol undermined rule of law.

Congressional Activity

Republicans held majorities in both the House and Senate, though the margins were thin, particularly in the House. Major legislative efforts included tax reform extending and expanding the 2017 Tax Cuts and Jobs Act provisions, immigration enforcement funding, and defense spending increases. The legislative process was frequently complicated by intra-party disagreements among House Republicans.

Part 2: Geopolitics and International Affairs

The Russia-Ukraine War

The war in Ukraine, which began with Russia's full-scale invasion in February 2022, continued throughout 2025. The conflict had become largely a war of attrition along extensive front lines in eastern and southern Ukraine. Both sides conducted offensive operations with limited territorial gains.

President Trump, who had promised to end the war quickly, appointed a special envoy and engaged in diplomatic efforts with both Kyiv and Moscow. The negotiations were complex and produced no ceasefire by mid-2025. The United States adjusted its military aid packages to Ukraine, and there was significant debate about the appropriate level of continued support.

European allies, concerned about potential changes in American commitment, accelerated their own defense spending and military aid to Ukraine. NATO held emergency consultations, and several European nations significantly increased their defense budgets, with many meeting or exceeding the alliance's 2% of GDP target for the first time.

The Middle East

The conflict in Gaza that erupted in October 2023 continued to dominate Middle East affairs in 2025. Multiple ceasefire negotiations took place. The humanitarian situation in Gaza was severe, with international organizations reporting widespread destruction and civilian suffering.

The Abraham Accords framework continued to evolve. Diplomatic discussions about Saudi Arabia normalizing relations with Israel proceeded, though the Gaza conflict complicated these efforts. Iran's nuclear program remained a major concern, with inspectors reporting advances in enrichment capabilities.

The Houthi attacks on Red Sea shipping, which had disrupted global trade routes since late 2023, continued into 2025. An international naval coalition attempted to protect shipping lanes, but the attacks persisted, forcing many cargo ships to take the longer route around the Cape of Good Hope.

China and the Indo-Pacific

U.S.-China relations remained tense but managed. The Trump administration imposed additional tariffs on Chinese goods, expanded restrictions on technology exports to China (particularly in semiconductors and AI), and maintained a strong naval presence in the South China Sea. China responded with its own retaliatory tariffs and export controls on critical minerals.

Taiwan remained a flashpoint. China conducted military exercises near Taiwan, and the United States continued arms sales to the island. Cross-strait tensions were elevated but did not escalate to direct confrontation.

Other International Events

In South Korea, President Yoon Suk Yeol faced impeachment proceedings following his brief declaration of martial law in December 2024. The Constitutional Court upheld the impeachment in early 2025, making him the second South Korean president to be removed from office.

Canada held elections in 2025 following the resignation of Prime Minister Justin Trudeau in January, who stepped down amid declining poll numbers and intra-party pressure. Mark Carney became the new Liberal Party leader and then Prime Minister, though he faced a challenging political environment with tariff disputes with the United States dominating the agenda.

Part 3: Economy and Finance

Inflation and Interest Rates

The Federal Reserve navigated a complex economic environment in 2025. After cutting rates in the second half of 2024, the Fed paused further cuts in early 2025 as inflation proved persistent. Core inflation remained above the Fed's 2% target for most of the year, influenced by tariff-related price increases on imported goods.

The economy showed resilience in employment numbers, with unemployment remaining low by historical standards. However, consumers reported feeling squeezed by high housing costs, elevated food prices, and the cumulative impact of several years of above-target inflation.

Tariffs and Trade

The Trump administration's tariff policies were among the most consequential economic developments of 2025. Tariffs were imposed or increased on goods from China, Canada, Mexico, and the European Union. The stated goals were to protect American manufacturing, reduce trade deficits, and pressure trading partners on various policy issues including immigration and fentanyl trafficking.

The economic effects were debated intensely. Some domestic manufacturers reported benefits from reduced foreign competition. Importers, retailers, and consumers faced higher prices. Agricultural exporters were concerned about retaliatory tariffs affecting their overseas sales. Financial markets reacted with volatility to each tariff announcement and escalation.

Technology Sector

The technology sector experienced a mixed year. Companies heavily invested in artificial intelligence saw their valuations soar. Nvidia's stock continued its extraordinary run as demand for AI training and inference chips remained insatiable. Microsoft, Google, Amazon, and Meta all reported massive capital expenditure plans for AI infrastructure.

However, the broader tech sector also faced challenges. Layoffs continued at many companies as they restructured around AI capabilities. The advertising market was disrupted by AI-powered tools that changed how content was created and consumed. Regulatory scrutiny of big tech companies continued, with antitrust cases against Google and other companies progressing through the courts.

Cryptocurrency

Cryptocurrency markets rallied significantly in 2025. Bitcoin reached new all-time highs, buoyed by the spot Bitcoin ETFs approved in 2024, institutional adoption, and a generally favorable regulatory stance from the Trump administration. The administration appointed crypto-friendly regulators and signaled support for making the United States a hub for digital asset innovation.

Part 4: Technology

Artificial Intelligence

AI was unquestionably the dominant technology story of 2025, even more so than in the preceding two years.

OpenAI released new models throughout the year, including GPT-4.5 and eventually GPT-5, continuing to push the frontier of language model capabilities. The models demonstrated improved reasoning, reduced hallucination rates, and expanded multimodal capabilities.

Anthropic released Claude 3.5, and later Claude 4, which were noted for their improved instruction following, coding abilities, and safety properties. The company continued to emphasize responsible AI development.

Google DeepMind advanced Gemini with new versions that competed directly with the leading models from OpenAI and Anthropic. Google integrated Gemini deeply into its product suite including Search, Workspace, and Android.

Meta continued its open-source AI strategy with Llama 3 and subsequent models, making powerful AI models freely available to researchers and developers worldwide.

Perhaps the biggest surprise came from DeepSeek, a Chinese AI lab that released models rivaling Western counterparts while reportedly using significantly fewer computational resources and at a fraction of the cost. DeepSeek's R1 reasoning model and its V3 language model demonstrated that the American lead in AI was not as insurmountable as many had assumed. The release sent shockwaves through the AI industry and temporarily rattled the stock prices of AI infrastructure companies.

AI coding assistants became standard developer tools. GitHub Copilot, Cursor, and other tools moved from novelty to essential infrastructure for software development. By mid-2025, surveys showed a majority of professional developers used AI assistance daily.

AI-generated content became ubiquitous. Image generation, video generation, and voice synthesis all improved dramatically. This created both exciting creative possibilities and serious concerns about misinformation, deepfakes, and the economic impact on creative professionals.

Space Exploration

SpaceX continued to push the boundaries of space technology. The Starship rocket, the largest and most powerful ever built, achieved multiple successful orbital flights and landings in 2025. The rapid iteration pace was remarkable compared to traditional aerospace development timelines.

NASA's Artemis program progressed toward its goal of returning humans to the Moon. Artemis II, the crewed lunar flyby mission, was in advanced preparation.

Blue Origin's New Glenn rocket successfully reached orbit in 2025, giving SpaceX its first serious commercial competition in the heavy-lift launch market.

The commercial space station market grew as the International Space Station approached its planned retirement timeline. Multiple companies developed proposals for private orbital habitats.

Consumer Technology

Apple released the iPhone 17 lineup in September 2025, featuring significant AI integration and camera improvements. The Apple Vision Pro, released in February 2024, received a price reduction and expanded to more countries, though mass adoption remained limited by the high price point and limited app ecosystem.

The electric vehicle market continued to grow globally, though the pace of adoption varied by region. Tesla maintained its market leadership but faced increasing competition from Chinese manufacturers like BYD, which surpassed Tesla in total vehicle sales including hybrids.

The foldable phone market expanded with Samsung, Google, and other manufacturers releasing refined models. The form factor moved from novelty to a viable mainstream option.

Cybersecurity

Major cybersecurity incidents continued to make headlines. Critical infrastructure attacks, ransomware campaigns against healthcare systems, and state-sponsored espionage operations all occurred. The increasing sophistication of AI-powered attacks raised alarms, as did the potential for AI to be used in creating more convincing phishing campaigns and social engineering attacks.

Part 5: Science and Health

Climate and Environment

2025 continued the trend of record-breaking global temperatures. Scientists reported that multiple climate indicators reached new extremes. Severe weather events including hurricanes, floods, droughts, and wildfires affected communities worldwide.

The California wildfires in January 2025, particularly the devastating Palisades and Eaton fires in the Los Angeles area, were among the most destructive in the state's history, destroying thousands of structures and causing billions of dollars in damage.

Medicine and Public Health

The post-pandemic era continued to evolve. COVID-19 remained endemic but was no longer a public health emergency. Updated vaccines were available but uptake varied widely. Long COVID continued to be studied, with researchers making progress in understanding its mechanisms.

GLP-1 receptor agonist medications, particularly Ozempic and related drugs originally developed for diabetes, continued their remarkable expansion. New studies throughout 2025 suggested benefits beyond weight loss, including potential cardiovascular benefits, and the drugs became some of the most prescribed medications in history.

Bird flu (H5N1) was a concern throughout 2025, with sporadic human cases reported, primarily among workers in close contact with infected poultry and dairy cattle. Public health agencies monitored the situation closely, concerned about the virus's pandemic potential if it gained efficient human-to-human transmission.

Physics and Astronomy

Researchers continued to refine quantum computing technology, though practical quantum advantage for real-world problems remained elusive for most applications. Several companies and universities reported advances in qubit counts and error correction.

The James Webb Space Telescope continued to produce extraordinary astronomical observations, revolutionizing understanding of early galaxy formation, exoplanet atmospheres, and stellar evolution.

Part 6: Culture and Society

Entertainment

The entertainment industry continued to adapt to streaming economics. The strikes that had shut down Hollywood in 2023 resulted in new contracts, but the industry faced ongoing structural changes as studios grappled with the economics of streaming versus theatrical releases.

Video gaming remained the largest entertainment industry by revenue, with continued growth in mobile gaming, live-service games, and the integration of AI into game development.

Sports

Major sporting events in 2025 included preparation for the 2026 FIFA World Cup to be held across the United States, Canada, and Mexico. Qualification rounds and venue preparations were major stories throughout the year.

In American football, the NFL maintained its position as the most-watched sport in the country.

Social and Cultural Shifts

The debate over AI's impact on employment and creativity intensified. Artists, writers, musicians, and other creative professionals pushed back against AI systems trained on their work without permission or compensation. Several lawsuits progressing through courts in 2025 sought to define the legal boundaries of AI training data usage.

Social media continued to fragment, with users spread across more platforms than ever. X (formerly Twitter) continued to evolve under Elon Musk's ownership. Bluesky, Threads, and Mastodon attracted users looking for alternatives. TikTok's uncertain future in the United States added to the sense of instability.

Part 7: Natural Disasters

California Wildfires

As mentioned above, the January 2025 wildfires in the Los Angeles area were catastrophic. The Palisades Fire and Eaton Fire burned through densely populated areas, destroying entire neighborhoods. The fires were fueled by extreme Santa Ana winds and dry conditions. The recovery and rebuilding effort would take years.

Other Disasters

Severe weather events occurred worldwide throughout the year. Flooding, hurricanes, and heat waves affected millions of people across multiple continents, reinforcing the urgent need for climate adaptation infrastructure.

Conclusion

The year 2025 was defined by change, upheaval, and acceleration. American politics shifted dramatically with the new administration. AI transformed from an impressive technology to an essential infrastructure layer. Geopolitical conflicts persisted without resolution. The economy navigated tariffs, persistent inflation, and technological disruption simultaneously.

As we look back from early 2026, the full consequences of many 2025 developments are still unfolding. The tariff regime's long-term economic effects, the AI revolution's impact on employment and creativity, and the geopolitical realignments set in motion by changing American foreign policy will all continue to shape the world for years to come.

What is clear is that 2025 was not a year of quiet incremental change. It was a year that bent the trajectory of history in multiple directions at once.

It is almost eleven in the morning eastern time as I type this. Hope you are doing well.

This article is written specifically for you: the professional .NET developer who works with enterprise software built on .NET Framework 4.7 (or thereabouts), goes home at the end of the day, and does not spend evenings experimenting with the latest frameworks. You have a life. You have responsibilities. Your relationship with software is professional, not recreational. And now someone at your company is talking about migrating to .NET 10, and you want to understand what that actually means without wading through years of release notes.

Let me be direct: the .NET ecosystem has changed more between .NET Framework 4.7 and .NET 10 than it changed in the entire decade before that. But the changes are overwhelmingly positive, and this guide will walk you through every major shift in plain, practical language.

Part 1: What Even Is .NET 10?

The Great Rename

The single most confusing thing that happened while you were building enterprise software is that Microsoft renamed everything.

Here is the timeline: .NET Framework 1.0 through 4.8 was the original runtime you know and love. It runs on Windows only. It is in maintenance mode — Microsoft still patches security issues, but no new features are being developed for it. Period.

Starting in 2016, Microsoft built a completely new, cross-platform, open-source runtime called .NET Core. It started at version 1.0 and went up to 3.1. Then, to reduce confusion (which, ironically, increased confusion), they dropped the "Core" suffix and jumped the version number to 5, calling it simply ".NET 5." This was followed by .NET 6, 7, 8, 9, and now .NET 10.

So when someone says ".NET 10," they mean the direct successor to .NET Core, not a new version of .NET Framework. It runs on Windows, macOS, and Linux. It is completely open-source. And it is the future of the platform.

.NET 10 is a Long-Term Support (LTS) release, meaning Microsoft will support it with patches and security updates for three years. This matters in enterprise contexts where you need stability guarantees.

What Happened to .NET Framework 4.7?

Your existing .NET Framework 4.7 applications will continue to run on Windows. Microsoft has not removed .NET Framework from Windows and has committed to including it in Windows for the foreseeable future. But it will never get new features. No performance improvements. No new language features. No new APIs. It is done.

This does not mean you need to panic. It means you need a plan.

Part 2: What Changed and Why You Should Care

C# Has Evolved Enormously

If your last experience with C# was version 7 (which shipped with .NET Framework 4.7), you have missed C# versions 8, 9, 10, 11, 12, 13, and 14. Each added features that make code shorter, safer, and more readable.

A few highlights that matter most in enterprise code:

Nullable reference types (C# 8): The compiler now tracks whether a reference variable can be null and warns you about potential null dereference bugs at compile time. This alone prevents an enormous category of runtime NullReferenceException crashes. Enabling this feature in your project is one of the highest-value changes you can make.

Records (C# 9): Immutable data classes can now be declared in a single line. Instead of writing a class with properties, a constructor, Equals, GetHashCode, and ToString overrides (which you probably were not writing correctly anyway), you write public record Person(string Name, int Age); and the compiler generates all of that for you. This is transformative for DTOs and value objects in enterprise code.

Pattern matching (C# 8-14): Switch statements now support complex patterns. You can match on types, property values, and combinations thereof. This makes complex business rule evaluation far more readable than chains of if/else statements.

Top-level statements (C# 9): A console application no longer needs a class with a static void Main method. The entry point is simply code at the top of a file. This is what you see in modern project templates and tutorials. It looks strange at first but is perfectly normal and fully supported.

Raw string literals (C# 11): No more escaping quotes in SQL queries and JSON templates. Triple-quoted strings handle multi-line text and embedded quotes without escape characters.

Primary constructors (C# 12): Classes can now declare constructor parameters directly in the class declaration, eliminating boilerplate field assignments.

ASP.NET Has Been Rewritten

ASP.NET in .NET 10 is not an update of the ASP.NET you know. It was rewritten from scratch as ASP.NET Core. The web server is no longer IIS (though IIS can act as a reverse proxy). The default web server is Kestrel, a lightweight, high-performance, cross-platform HTTP server.

The programming model has changed significantly. There is no more Global.asax. There is no more Web.config for application settings (you use appsettings.json). The request pipeline is built with middleware rather than HTTP modules and handlers. Dependency injection is built into the framework rather than bolted on with third-party containers.

The performance difference is staggering. Benchmarks consistently show ASP.NET Core handling 5 to 10 times more requests per second than classic ASP.NET on the same hardware, while using less memory. For enterprise applications processing thousands of concurrent requests, this translates directly to lower infrastructure costs.

Blazor: C# in the Browser

One of the most significant new capabilities in modern .NET is Blazor, which lets you build interactive web UIs using C# instead of JavaScript. There are multiple hosting models:

Blazor WebAssembly compiles your .NET code to WebAssembly and runs it entirely in the browser. No server needed at runtime. The compiled output is static files (HTML, CSS, JS, WASM) that can be hosted anywhere, including free hosting like GitHub Pages. This is what Observer Magazine itself is built with.

Blazor Server keeps your .NET code on the server and uses SignalR (WebSockets) to maintain a real-time connection with the browser. Every UI interaction sends a message to the server, which processes it and sends back DOM updates. This means faster initial load times (no WASM download) but requires a persistent server connection.

Blazor United (also called Blazor Web App) in .NET 8 and later combines both models. Pages can start with server-side rendering for instant load times and then switch to WebAssembly for offline capability. In .NET 10, this hybrid model is mature and well-tooled.

For enterprise developers, Blazor means your existing C# skills transfer directly to web development. Your business logic, validation rules, and data models can be shared between server and client. Your team does not need to hire JavaScript specialists or maintain a separate frontend codebase.

Entity Framework Core

Entity Framework has also been rewritten as Entity Framework Core (EF Core). It is faster, supports more databases (SQL Server, PostgreSQL, SQLite, MySQL, and more), and has a cleaner API. However, it is not a drop-in replacement for EF6. The API surface is different enough that migration requires code changes.

EF Core 10 includes features like compiled models for faster startup, improved query translation, bulk operations, and excellent support for JSON columns. For enterprise applications with complex data access patterns, EF Core represents a significant improvement in both performance and developer experience.

Native AOT Compilation

Perhaps the most revolutionary technical advancement in .NET 10 is Native Ahead-of-Time (AOT) compilation. Traditional .NET applications ship as Intermediate Language (IL) and are compiled to machine code at runtime by the Just-In-Time (JIT) compiler. Native AOT compiles your entire application to a native binary at publish time. The result is an executable that starts in milliseconds instead of seconds, uses significantly less memory, and does not require the .NET runtime to be installed.

For enterprise scenarios, Native AOT is particularly valuable for microservices and serverless functions where cold start time directly affects user experience and cost.

Part 3: The Modern .NET Ecosystem

Modern Project Files

If you open a modern .NET project file, you might not recognize it. The old verbose .csproj format with hundreds of lines of XML has been replaced by the SDK-style project format, which typically has fewer than 20 lines. The build system is smarter about discovering source files, so you no longer need to list every .cs file in the project file.

The solution file format has also been modernized. The new SLNX format uses clean XML instead of the old proprietary binary format, making it friendly to Git merges and human reading.

Central Package Management (Directory.Packages.props) lets you define NuGet package versions in a single file at the root of your repository, eliminating version drift across projects in a large solution.

Directory.Build.props lets you set common build properties (target framework, nullable reference types, warning levels) for all projects in a repository from one file.

Modern Tooling

The dotnet CLI is now the primary way to create, build, test, and publish .NET applications. You can do everything from the command line: dotnet new, dotnet build, dotnet test, dotnet publish. Visual Studio remains fully supported and is still the preferred IDE for many enterprise developers, but you are no longer tied to it.

JetBrains Rider has become a popular cross-platform alternative to Visual Studio. VS Code with the C# Dev Kit extension is viable for lighter-weight development.

Hot Reload lets you modify code while the application is running and see changes immediately without restarting. This dramatically improves the inner development loop for UI work.

Testing in Modern .NET

The testing ecosystem has matured significantly. xUnit (now at version 3) is the most popular testing framework. bUnit enables unit testing of Blazor components without a browser. The dotnet test runner integrates cleanly with CI/CD pipelines.

In the enterprise context, the built-in dependency injection and interface-based design of ASP.NET Core make applications far more testable than classic ASP.NET applications. You can write integration tests that spin up an in-memory web server and send real HTTP requests to your API without deploying anything.

Part 4: The Broader Technology Landscape in 2025-2026

AI Is Everywhere

You cannot discuss the current technology landscape without addressing AI. Large language models like GPT-4, Claude, and Gemini have transformed software development workflows. AI coding assistants are now standard tooling, not novelties. In your daily work, this means you will increasingly use AI to help write code, debug issues, write documentation, and review pull requests.

For .NET developers specifically, AI integration is straightforward. The Microsoft.Extensions.AI libraries provide standardized interfaces for connecting to AI services from .NET code. Whether you are building an internal tool that uses AI to summarize documents, a customer-facing chatbot, or an application that uses AI for data analysis, the .NET ecosystem has mature support.

Cloud-Native Is the Default

Modern enterprise software is increasingly designed to run in containers on Kubernetes or similar orchestrators. .NET 10 has excellent container support, with tiny container images (especially with Native AOT) and built-in health check endpoints that integrate with Kubernetes liveness and readiness probes.

Even if your current applications run on dedicated servers or VMs, understanding containers is important because it is where the industry is heading. The good news is that containerizing a .NET application is straightforward and often requires only adding a Dockerfile.

Open Source Is the Norm

.NET itself is fully open-source under the MIT license. The entire runtime, compiler, libraries, and most of the ASP.NET framework are developed in the open on GitHub. This is a dramatic shift from the proprietary, Windows-only .NET Framework era.

For enterprise developers, this means you can read the source code of the framework itself when debugging issues. You can file issues and even contribute fixes. And you can be confident that the platform will not be abandoned because the community can maintain it independently if necessary.

Part 5: How to Approach Migration

Do Not Boil the Ocean

The most important advice for migrating from .NET Framework 4.7 to .NET 10 is: do not try to migrate everything at once. Start with a new microservice or a smaller, less critical application. Build your team's familiarity with the new platform on a project where the stakes are lower.

Use the .NET Upgrade Assistant

Microsoft provides a tool called the .NET Upgrade Assistant that automates much of the mechanical migration work. It can update project files, convert Web.config settings to appsettings.json, update NuGet package references, and flag code that uses APIs not available in modern .NET. It is not perfect, but it handles the tedious parts so your team can focus on the genuinely complex migration decisions.

Identify Breaking Changes Early

Some .NET Framework APIs do not exist in modern .NET. The most common pain points are Windows-specific APIs (like System.Drawing on Linux), some WCF service features (replaced by gRPC or REST), and certain AppDomain behaviors. The .NET Portability Analyzer tool can scan your existing code and generate a report of compatibility issues.

Plan for NuGet Package Updates

Many NuGet packages have different versions for .NET Framework and modern .NET. Some packages you depend on may not have been updated at all. Audit your dependencies early and identify any that need replacements.

Embrace the New Patterns Gradually

You do not need to rewrite your application to use minimal APIs, top-level statements, and every new C# feature on day one. Modern .NET supports the controller-based MVC pattern you are familiar with. Start with a project structure that feels comfortable, then adopt new patterns as your team gains confidence.

Part 6: Why This Is Worth Doing

If you have read this far, you might be wondering whether this migration is worth the effort and risk. Here is the honest answer: yes, unequivocally.

Performance: Your applications will run faster and use less memory. In enterprise contexts with thousands of users, this translates to real cost savings on infrastructure.

Security: .NET Framework 4.7 receives only critical security patches. Modern .NET receives active security development with new features like built-in rate limiting, improved cryptography, and regularly updated TLS support.

Developer productivity: Modern C# features, better tooling, and built-in dependency injection make developers measurably more productive. Code reviews go faster because the code is more readable. Bugs are caught earlier because the compiler is smarter.

Hiring: New .NET developers coming out of bootcamps and university programs learn modern .NET. Requiring .NET Framework experience narrows your hiring pool to increasingly senior developers.

Cross-platform: Your applications can run on Linux servers (which are cheaper to operate than Windows Server) and in lightweight containers. You are no longer locked into Windows Server licensing.

Ecosystem momentum: All new .NET libraries, frameworks, and tools target modern .NET. Staying on .NET Framework means an increasingly stale dependency graph.

Conclusion

The jump from .NET Framework 4.7 to .NET 10 is large. There is no sugarcoating that. But every piece of the puzzle — the language improvements, the performance gains, the cross-platform support, the modern tooling, the open-source ecosystem — represents a genuine improvement in your ability to build and maintain quality enterprise software.

You do not need to make this jump in a weekend. You do not need to rewrite everything. But you do need to start. Pick a small project. Install the .NET 10 SDK. Create a new application with dotnet new webapi. Run it. Explore. And when you are ready, use the Upgrade Assistant on something real.

The .NET platform has never been in a better position than it is today. The same C# skills that have served you well for years still apply — they just apply to a faster, more capable, more modern foundation.

Welcome to the future of .NET. It has been waiting for you.

If you have ever deployed an ASP.NET application and noticed that the very first request takes seconds — sometimes tens of seconds — while subsequent requests are blazing fast, you have experienced the infamous "cold start" problem. This post breaks down the entire ASP.NET request lifecycle, explains where that cold start time goes, and shows how modern .NET (up through .NET 10) has systematically attacked this problem from every angle.

Part 1: The Classic ASP.NET Framework Request Lifecycle

To understand why cold starts are slow, you first need to understand what happens when a request arrives at an ASP.NET Framework application running on IIS.

The IIS Pipeline

When IIS receives an HTTP request, it goes through a series of stages before your code ever runs. In Integrated Pipeline Mode (the default since IIS 7), the request flows through a unified pipeline of native IIS modules and managed ASP.NET modules. The key stages are:

BeginRequest is where the pipeline starts. IIS determines which application pool should handle the request and routes it accordingly. If the application pool's worker process (w3wp.exe) is not running — because the pool was recycled or the app was idle — IIS must spin up an entirely new process. This is the first major source of cold start latency.

AuthenticateRequest and AuthorizeRequest handle identity and permissions. These stages load authentication modules (Windows Auth, Forms Auth, etc.) and can involve talking to Active Directory or a database.

ResolveRequestCache checks whether a cached response exists. On a cold start, the cache is empty, so this is a no-op that adds no benefit.

MapRequestHandler determines which handler processes the request. For MVC, this involves the routing engine matching a URL pattern to a controller and action. For Web Forms, this maps to a .aspx page handler.

ExecuteRequestHandler is where your actual application code runs — your controller action, your page lifecycle, your business logic. On a cold start, this is where the bulk of the delay happens because of JIT compilation and dependency initialization (more on this below).

UpdateRequestCache stores the response for future cache hits.

EndRequest performs cleanup and sends the response.

The ASP.NET Page Lifecycle (Web Forms)

If your application uses Web Forms, the ExecuteRequestHandler stage triggers a complex page lifecycle of its own: Init, LoadViewState, Load, PostBack event handling, PreRender, SaveViewState, Render, and Unload. Each of these stages can involve control tree construction, viewstate deserialization, and dynamic compilation of .aspx and .ascx files. On the first request, every page and user control must be compiled from markup into a .NET class, compiled to IL, and then JIT-compiled to native code. This is why a complex Web Forms application can take minutes on its very first request.

The ASP.NET MVC Lifecycle

MVC applications are leaner but still go through significant work on cold start. Routing tables must be built from your RouteConfig (or attribute routes). Controller factories and dependency injection containers must be constructed. The Razor view engine must locate, parse, compile, and JIT-compile every .cshtml file the first time it is accessed. Area registrations, filter providers, model binders, and value providers all need initialization.

Part 2: Why Is the Cold Start So Slow in .NET Framework?

The cold start slowness in classic .NET Framework comes from several compounding factors.

1. JIT Compilation

.NET Framework applications ship as Intermediate Language (IL) bytecode. When a method is called for the first time, the CLR's Just-In-Time compiler translates it to native machine code. This happens method-by-method, on demand. On a cold start, virtually every method in your application's startup path must be JIT-compiled: your Global.asax, your DI container setup, your routing configuration, your first controller, your first Razor view, and every framework method those call into. For a large application with hundreds of types, this can take seconds of raw CPU time.

2. Assembly Loading

The CLR must locate and load assemblies from disk. .NET Framework applications often have dozens of DLLs in their bin folder — your code, NuGet packages, framework libraries. Each DLL must be found on disk, read into memory, and have its metadata parsed. On a traditional spinning hard drive (still common in older server environments), this I/O alone can add hundreds of milliseconds. Even on SSDs, loading 50-100 assemblies sequentially adds up.

3. IIS Application Pool Recycling

By default, IIS recycles application pools every 1740 minutes (29 hours) and shuts them down after 20 minutes of inactivity. When a pool recycles, the next request must go through the entire cold start sequence again: process creation, CLR initialization, assembly loading, JIT compilation, and application initialization. This means users regularly experience cold starts, not just after deployments.

4. Dynamic Compilation of Views

In ASP.NET MVC on .NET Framework, Razor views (.cshtml files) are compiled at runtime by default. The Razor engine reads the file from disk, parses it into C# code, compiles the generated C# to IL, and then the CLR JIT-compiles it to native code. For an application with hundreds of views, this cascade of disk reads, parsing, and compilation is brutally slow on first access.

5. Heavy Initialization in Global.asax

Classic ASP.NET applications perform massive amounts of work in Application_Start: registering routes, configuring dependency injection, setting up Entity Framework models, loading configuration, initializing logging frameworks, building AutoMapper profiles, and more. All of this runs synchronously before the first request can be served. A complex enterprise application might spend 5-30 seconds in Application_Start alone.

6. Entity Framework Model Compilation

Entity Framework (especially versions 4 through 6) must build an in-memory model of your entire database schema the first time a DbContext is used. For large schemas with hundreds of tables and complex relationships, this model compilation can take several seconds. Combined with JIT compilation of EF's own code, the first database query often takes 10-50x longer than subsequent queries.

Part 3: Mitigations for .NET Framework Cold Starts

Developers have historically used several strategies to reduce cold start pain on .NET Framework.

Pre-compilation

The aspnet_compiler.exe tool can pre-compile all views and pages at build time rather than at runtime. Combined with aspnet_merge.exe (which merges the resulting assemblies into a smaller number of DLLs), this eliminates runtime view compilation entirely. You can enable this in MSBuild with /p:PrecompileBeforePublish=true /p:UseMerge=true.

NGen (Native Image Generator)

Running ngen install on your assemblies produces native images that bypass JIT compilation. The CLR loads the pre-compiled native code directly instead of JIT-compiling IL. However, NGen images are machine-specific, fragile (they're invalidated when dependencies change), and don't benefit from runtime profile-guided optimization. Still, for cold starts, NGen can reduce startup time by 30-60%.

IIS Application Initialization Module

The IIS Application Initialization module (available since IIS 8) sends a synthetic request to your application immediately when the app pool starts, rather than waiting for the first real user request. Combined with the "AlwaysRunning" start mode for the application pool, this ensures the cold start happens in the background before any user is affected.

Reducing Idle Timeout and Recycling Frequency

Setting the IIS idle timeout to 0 (never timeout) and extending or disabling periodic recycling prevents the application from shutting down between requests. This trades memory for availability.

Warm-up Scripts

Many teams write HTTP health-check scripts that hit key endpoints after deployment, forcing JIT compilation and cache population before real traffic arrives. This is a brute-force approach but effective.

Pre-building Singletons

Instead of lazily constructing singletons during the first request, you can eagerly resolve all registered singleton services during startup. This front-loads the DI container work so the first real request does not pay the price.

Part 4: The Modern .NET Lifecycle (.NET 6 through .NET 10)

Modern .NET (the cross-platform runtime, not .NET Framework) has fundamentally restructured the application lifecycle. Understanding the differences helps explain why cold starts are dramatically better.

The Minimal Hosting Model

Starting with .NET 6 and refined through .NET 10, the application entry point is a simple Program.cs with a WebApplicationBuilder. There is no more Global.asax, no Startup class split into ConfigureServices and Configure, no complex lifecycle of OWIN middleware registration. The pipeline is built declaratively:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();

var app = builder.Build();
app.UseRouting();
app.MapRazorPages();
app.Run();

This minimal model does less work at startup because the framework itself is more modular. You only pay for what you use.

Kestrel Instead of IIS

Modern ASP.NET Core applications run on Kestrel, a lightweight, cross-platform HTTP server written from scratch for performance. Kestrel does not have IIS's application pool recycling behavior, idle timeouts, or heavy process management overhead. When deployed behind a reverse proxy (NGINX, YARP, or even IIS as a reverse proxy via ANCM), the application process stays alive continuously.

Razor View Compilation at Build Time

Since .NET Core 3.0, Razor views and pages are compiled at build time by default. The Microsoft.NET.Sdk.Razor SDK compiles .cshtml files into C# classes and then into IL during dotnet build, not at runtime. This completely eliminates the runtime view compilation that plagued .NET Framework.

Tiered Compilation

Introduced in .NET Core 3.0 and enabled by default since, Tiered Compilation replaces the single-pass JIT with a two-tier approach. Tier 0 ("Quick JIT") compiles methods very fast but produces lower-quality code. After a method has been called enough times, the runtime recompiles it at Tier 1 with full optimizations. The result: methods are available almost instantly on first call (much faster than the old full-optimization JIT), and hot methods eventually reach peak performance. For cold starts, Tiered Compilation dramatically reduces the time spent in JIT.

ReadyToRun (R2R)

ReadyToRun is a form of ahead-of-time compilation available since .NET Core 3.0. When you publish with <PublishReadyToRun>true</PublishReadyToRun>, the compiler pre-compiles IL to native code for the target platform. Unlike NGen, R2R images are portable across machines with the same OS and architecture. The CLR can load R2R code directly, bypassing Tier 0 JIT entirely. In serverless and containerized environments, R2R typically reduces cold start time by 30-80%.

Trimming

IL trimming (enabled with <PublishTrimmed>true</PublishTrimmed>) removes unused code from your application and its dependencies at publish time. A smaller application means fewer assemblies to load and less code to JIT-compile (if any). This is particularly impactful in Blazor WebAssembly, where the trimmed application must be downloaded to the browser.

Part 5: .NET 10 and Native AOT — The Cold Start Killer

.NET 10, released as an LTS release in late 2025, represents the most significant advancement in cold start performance since .NET's creation.

Native AOT Compilation

Native Ahead-of-Time compilation (<PublishAot>true</PublishAot>) compiles your entire application to a native binary at publish time. There is no IL, no JIT compiler, no CLR runtime to initialize. The resulting binary is a self-contained native executable that starts like a C program.

The performance difference is staggering. Benchmarks show startup times dropping from hundreds of milliseconds to single-digit milliseconds for minimal APIs. One production report documented startup dropping from 70ms to 14ms — an 80% reduction — with memory usage cut by more than 50%. In serverless environments like AWS Lambda, cold start improvements of up to 86% have been measured.

Native AOT achieves this by eliminating several entire categories of cold start work: there is no JIT compilation (code is already native), no IL metadata loading, no tiered compilation infrastructure, and the binary includes only the code your application actually uses (aggressive tree shaking). The resulting binary for a minimal API console app is around 1 MB in .NET 10, down from several MB in .NET 7.

The Trade-offs

Native AOT is not free. It imposes constraints that you must design around:

No runtime reflection — You cannot use Type.GetType(), Activator.CreateInstance(), or other reflection APIs that depend on metadata that has been stripped away. This means libraries like traditional Entity Framework (which relies heavily on reflection), many DI containers, and AutoMapper in its default configuration do not work with Native AOT.

Source generators required — Instead of reflection, .NET 10 uses compile-time source generators. System.Text.Json requires [JsonSerializable] attributes to generate serialization code at compile time. DI containers must use compile-time registration.

Platform-specific binaries — A Native AOT binary compiled on Linux x64 runs only on Linux x64. You need separate publish steps for each target platform.

Longer publish times — The native compiler takes significantly longer than dotnet publish without AOT, because it must compile and optimize the entire application.

Potentially lower peak throughput — The JIT compiler can use runtime profiling data to optimize hot paths in ways the AOT compiler cannot. For long-running server applications, JIT-compiled code may achieve higher steady-state requests per second than AOT-compiled code. You trade peak throughput for instant startup.

Selective AOT in .NET 10

.NET 10 introduces the ability to AOT-compile specific performance-critical assemblies while keeping the rest JIT-compiled. This hybrid approach lets you optimize startup-critical paths with AOT while retaining the flexibility and peak performance of JIT for the rest of your application.

CreateSlimBuilder

For Native AOT scenarios, .NET 10 provides WebApplication.CreateSlimBuilder(), a minimal builder that excludes services not compatible with AOT (like the full MVC framework). This produces even smaller, faster binaries for API-only workloads.

Blazor WebAssembly and AOT

Blazor WebAssembly benefits from AOT as well. The <WasmStripILAfterAOT>true</WasmStripILAfterAOT> property in .NET 10 removes IL from the WASM bundle after AOT compilation, producing significantly smaller downloads. Combined with Blazor's 76% smaller JavaScript bundles in .NET 10, the initial load time for Blazor WASM applications has improved dramatically.

MAUI and Mobile Native AOT

.NET 10 extends Native AOT support to Android (with measured startup improvements from 1+ seconds with Mono AOT down to 271-331ms) and continues existing iOS/Mac Catalyst AOT support. Windows App SDK is expected to gain Native AOT support shortly after the .NET 10 release.

Part 6: The Modern ASP.NET Core Request Pipeline in .NET 10

With all these compilation advances in mind, here is what the modern .NET 10 request lifecycle looks like:

Application Startup

1. Process start — The native binary (if using AOT) or dotnet runtime loads the application. With Native AOT, this is nearly instant. With JIT + R2R, Tiered Compilation ensures Quick JIT handles initial methods in microseconds.

2. Host configuration — WebApplicationBuilder reads configuration from appsettings.json, environment variables, and other providers. The DI container is built with all registered services.

3. Middleware pipeline construction — The middleware pipeline is built in the order you specified. Each Use* call adds a delegate to a chain. The pipeline is constructed once and reused for all requests.

4. Server start — Kestrel begins listening on configured ports.

Per-Request Flow

Once the application is running, each request flows through the middleware pipeline:

1. Kestrel receives the connection — HTTP parsing happens in optimized, allocation-free code using System.IO.Pipelines and Span<T>.

2. Middleware pipeline executes — Each middleware gets a chance to handle the request or pass it to the next middleware. Common middleware includes exception handling, HTTPS redirection, static files, routing, authentication, authorization, and CORS.

3. Routing — The routing middleware matches the request URL to an endpoint. In .NET 10, the routing system uses a highly optimized trie-based data structure that matches endpoints in near-constant time regardless of how many routes are registered.

4. Endpoint execution — The matched endpoint runs. For minimal APIs, this is a simple delegate. For MVC controllers, this involves model binding, action filters, action execution, result filters, and result execution. For Razor Pages, the page handler executes.

5. Response writing — The response flows back through the middleware pipeline in reverse order, allowing each middleware to modify headers or the response body.

Part 7: Practical Recommendations

Based on everything above, here is what you should do depending on your situation.

If you are still on .NET Framework

Migrate. Seriously. The performance, security, and ecosystem benefits of modern .NET are enormous, and .NET Framework 4.8 is in maintenance mode with no new features. If migration is not immediately possible, use pre-compilation, NGen, IIS Application Initialization, and disable idle timeouts.

If you are on .NET 6/8 and cold starts matter

Publish with ReadyToRun (<PublishReadyToRun>true</PublishReadyToRun>). Enable trimming if your dependency graph supports it. Consider Native AOT if your application uses minimal APIs and avoids heavy reflection. Evaluate your startup code for unnecessary synchronous work that can be deferred or made asynchronous.

If you are starting a new project on .NET 10

Design for Native AOT from day one. Use [JsonSerializable] for all JSON types. Avoid reflection-based libraries. Use source generators wherever possible. Test AOT compatibility early with <IsAotCompatible>true</IsAotCompatible>. Use dotnet publish with AOT regularly during development to catch compatibility issues before they accumulate. Take advantage of the new SLNX solution format, Directory.Build.props for shared configuration, and central package management for clean project organization.

For Blazor WebAssembly specifically

Enable AOT compilation and IL stripping. Use lazy loading for assemblies not needed on the initial page. Keep your dependency graph lean — every NuGet package adds to the download size. Pre-render on the server if possible (Blazor Server or Blazor United) to give users an instant first paint while the WASM runtime downloads in the background.

Conclusion

The ASP.NET cold start problem was real and painful for over a decade. It was caused by a perfect storm of just-in-time compilation, dynamic view compilation, heavy framework initialization, and IIS process management. Modern .NET has attacked each of these causes systematically: Tiered Compilation and ReadyToRun reduce JIT overhead, build-time view compilation eliminates runtime Razor compilation, the minimal hosting model reduces initialization work, and Kestrel eliminates IIS recycling. Native AOT in .NET 10 goes even further by eliminating JIT entirely, producing native binaries with startup times measured in milliseconds rather than seconds.

The result is that a well-optimized .NET 10 application can cold-start faster than most Node.js or Python applications — a dramatic reversal from the .NET Framework era. The ecosystem has matured, the tooling is excellent, and the migration path from .NET 8 LTS to .NET 10 LTS is smooth. If cold starts have been holding you back from .NET, it is time to take another look.

Welcome to Observer Magazine. It is great to have you with me here. I hope you enjoy this website.

I have updated the nuget packages. I would love to hear your thoughts about this magazine.

Data-heavy UIs are notoriously hard to make responsive. Wide tables overflow on small screens, and complex layouts need fundamentally different structures on mobile vs. desktop.

Responsive Tables

Our approach uses CSS to transform table rows into stacked cards on small screens:

• On desktop: a traditional <table> with sortable column headers
• On mobile: each row becomes a card with label-value pairs

The key CSS trick is using data-label attributes on <td> elements and displaying them via ::before pseudo-elements when the table header is hidden.

Master-Detail Flow

The master-detail pattern uses CSS Grid:

• On desktop: a two-column layout (list on left, details on right)
• On mobile: the columns stack vertically, with the list on top

No JavaScript media queries needed — it's all pure CSS with Blazor handling the state.

Key Takeaways

1. Use semantic HTML — <table> for tabular data, not divs pretending to be tables.
2. CSS does the heavy lifting — Blazor components stay clean; responsiveness lives in the stylesheet.
3. Test on real devices — Emulators are fine for development, but nothing beats a real phone.

See all these patterns live on the Showcase page.

Blazor WebAssembly (WASM) lets you build interactive web UIs using C# instead of JavaScript. Your .NET code runs directly in the browser via WebAssembly — no plugins, no server needed at runtime.

Why We Chose It

For Observer Magazine, Blazor WASM is ideal because:

• Static hosting — The compiled output is plain HTML, CSS, JS, and WASM files. Perfect for GitHub Pages.
• Full .NET ecosystem — We use the same language, tooling, and libraries as backend .NET developers.
• Performance — After the initial download, navigation is instant. The runtime is ahead-of-time compiled for speed.
• Testability — With bUnit, we can unit-test every component without a browser.

Project Structure

Our project follows a clean layout:

src/ObserverMagazine.Web/     — The Blazor WASM app
tools/ContentProcessor/        — Build-time markdown processor
tests/                         — xUnit + bUnit tests
content/blog/                  — Markdown blog posts

The ContentProcessor runs at build time (in CI) to convert Markdown files into JSON and HTML that the Blazor app fetches at runtime.

Next Steps

Check out the Showcase to see responsive tables and master-detail flows in action, or browse the source code to see how everything fits together.

Welcome to Observer Magazine, a free and open-source web application built with Blazor WebAssembly on .NET 10.

This project serves two purposes:

1. A learning resource for developers exploring Blazor WASM, modern .NET tooling (slnx, Directory.Build.props, central package management), and static site deployment on GitHub Pages.
2. A starting point you can fork and adapt for your own projects — whether that's a personal blog, a product showcase, or a full SaaS application.

What's Inside

• A responsive, accessible UI built entirely in C# and Razor
• A blog engine powered by Markdown files with YAML front matter
• An auto-generated RSS feed
• Showcases of common web patterns: responsive tables, master-detail flows
• Structured logging ready for OpenTelemetry
• A full test suite using xUnit v3 and bUnit

Philosophy

Every dependency we use is truly free — no "free for non-commercial" restrictions. We will never charge money for this software. The code is AGPLv3-licensed and always will be.

Stay tuned for more posts!