Builder

Think of ordering a custom sandwich at a deli. You do not shout all 10 ingredients at once and hope the person behind the counter remembers them all. Instead, you go step by step: "I want wheat bread, then turkey, then Swiss cheese, then lettuce..." and at the end you say "that's it, make it." That "make it" moment is .Build().

Builder is a creational pattern that constructs complex objects step by step. Instead of passing 10 parameters to a constructor (where you forget which null means what), you call named methods like .SetName(), .WithEmail(), then finalize with .Build(). Each method is self-documenting, so you always know what you are configuring.

It solves three problems: (1) Telescoping constructors — too many overloads. (2) No validation — invalid object state isn't caught until runtime. (3) Mutability — objects can be changed after creation. The builder addresses all three: named methods replace positional params, Build() validates before creating, and the product is immutable.

Think of building a house. You have four key roles: the blueprint (Builder interface) describes what steps exist (lay foundation, build walls, add roof). The construction crew (ConcreteBuilder) actually performs those steps and keeps track of progress. The architect (Director) decides the order: "foundation first, then walls, then roof." And the house (Product) is the finished result you move into.

Builder — the interface declaring the construction steps. ConcreteBuilder — implements the steps, accumulates state, and provides Build(). Director — orchestrates which steps are called and in what order. Product — the complex object being constructed, typically immutable.

In modern .NET, the Director is often omitted — the client chains fluent methods directly on the builder. But the Director role is still useful when you have predefined "recipes" like BuildGamingPC() vs BuildBudgetPC() that call builder methods in specific sequences.

(1) WebApplicationBuilder — configures services, logging, config, then .Build() → WebApplication. (2) StringBuilder — appends string fragments, then .ToString(). (3) IHostBuilderThe generic host builder for non-web .NET applications — configures DI, logging, and configuration for background services and console apps. — configures generic host for background services. Others: ConfigurationBuilder, UriBuilderSystem.UriBuilder — safely constructs URIs by setting Scheme, Host, Port, Path, Query as typed properties rather than concatenating strings., SqlConnectionStringBuilder, IEndpointConventionBuilderThe fluent builder returned by MapGet/MapPost in minimal APIs — lets you chain .RequireAuthorization(), .WithTags(), .CacheOutput() etc..

A fluent interface is an API design where each method returns the object itself (return this), enabling method chaining: builder.A().B().C().Build(). It's the dominant implementation style for modern builders because it's readable and discoverable via IntelliSense.

Fluent interface is a technique; Builder is a pattern. Not all fluent interfaces are Builders (LINQ is fluent but not a Builder), and not all Builders are fluent (the GoF version isn't).

Imagine buying a hammer to hang a single picture frame. You don't need a full carpentry workshop for that. Builder is the same way: it is a powerful tool, but not every construction job needs it.

Don't use Builder when: (1) the object has 1-3 parameters — a simple constructor is fine, named arguments make it readable. (2) No validation is needed — object initializers like new Foo { A = 1 } work great. (3) The object is a simple DTO with no invariants or business rules. (4) C# record with required members handles your needs. (5) You only need to change one field on an existing object — use with-expression instead of round-tripping through a builder.

A good rule of thumb: if you can describe the constructor call to a teammate without them getting confused, you do not need a builder. Builders shine when the construction is complex enough that a plain constructor becomes unreadable or error-prone.

Think of it with a restaurant analogy. Builder is like a custom burger counter: you build one meal step by step (pick the bun, add patty, choose toppings, finalize). Abstract Factory is like choosing a cuisine: if you pick "Italian," every dish on the menu is Italian (pasta, wine, tiramisu). The factory ensures everything belongs together; the builder ensures one complex thing is built correctly.

Builder focuses on constructing one complex object step by step. Abstract Factory focuses on creating families of related objects that must be consistent. Builder is about the construction process; Abstract Factory is about product compatibility.

Builder often produces one big Product. Abstract Factory produces multiple small Products that belong to the same family. Builder validates at Build() time; Abstract Factory guarantees consistency by restricting which factory creates which products.

Imagine a recipe where you absolutely must preheat the oven before putting in the cake batter. If you skip preheating, the cake is ruined. A regular builder lets you call methods in any order, so it cannot prevent someone from adding batter before preheating. A Step Builder fixes this by using the type system as a guard rail.

A Step BuilderA Builder variant where each build phase returns a different interface type — the compiler enforces that required steps happen in order and optional steps only appear after required ones. uses different interface types for each build phase. Step 1 returns IStep2, which returns IStep3, etc. The compiler will not let you skip steps or call them out of order because each step only exposes the methods for the next step. After you call the method on IStep1, your variable's type changes to IStep2, and only IStep2's methods are visible in IntelliSense.

Use it when: build order matters (cannot set WHERE before FROM in SQL), required steps must happen before optional ones, or you want compile-time rather than runtime validation of the build sequence.

Three approaches: (1) Validate in Build() — throw if required fields are null. Simple but runtime-onlyErrors are only caught when the code runs, not when it compiles. Build() validation is runtime — you only discover missing fields when Build() is called.. (2) Required params in constructor — new OrderBuilder(customerId, productId) forces required fields upfront, optional via fluent methods. (3) Step Builder — return type changes per step, compile-time enforcementErrors are caught by the compiler before the code runs. Step Builder's typed interfaces make wrong step order a compiler error, not a runtime exception..

(1) Make the Product's constructor internal — only the Builder can create it. (2) Use readonly fieldsC# fields marked readonly can only be assigned in the constructor or field initializer. They prevent accidental mutation after construction. or init-only propertiesC# 9+ feature: properties that can only be set during object initialization (constructor or object initializer). Read-only afterwards.. (3) Use C# record types which are immutable by default. (4) Expose collections as IReadOnlyList<T>. (5) Make defensive copiesCreating a new copy of a mutable collection in the constructor so the caller's reference can't be used to mutate the object's internal state after construction. in the constructor — don't store the builder's mutable list directly.

Think of a head chef in a restaurant. The chef does not cook the food directly (that is the cook's job, a.k.a. the builder). But the chef knows the recipe: "For the special, start with the sauce, then sear the steak, then plate with garnish." The recipe is reusable across different cooks (builders). The Director is that head chef: it holds the recipe and tells the builder which steps to perform and in what order.

The Director encapsulatesEncapsulation — hiding implementation details behind an interface. The Director hides the construction algorithm so clients don't need to know the step sequence. a specific construction sequence — it knows which steps to call and in what order. Without a Director, the client must know the sequence. The Director is still relevant when you have predefined configurations (e.g., BuildGamingPC, BuildBudgetPC) that should be reusable.

In practice, modern .NET either uses the client as the director (fluent chains) or uses factory methods that encapsulate the build sequence: Order.CreateGiftOrder(...) internally uses a builder. The Director is basically a factory method that takes a builder. It is still useful; it just often takes the form of a static method rather than a separate class.

This question trips up many candidates because the natural instinct is "I want to reuse objects, so Scoped or Singleton." But builders are the exception. They accumulate mutable state that is specific to one build operation. Sharing them means sharing that state.

TransientDI lifetime where a new instance is created every time the service is requested. AddTransient<T>() — ideal for stateful, short-lived objects like builders. — always. Builders are mutable and stateful. SingletonDI lifetime where one instance is shared across the entire application. AddSingleton<T>() — dangerous for builders because concurrent requests share mutable state. = race conditions (two threads writing to the same builder). ScopedDI lifetime where one instance is created per HTTP request (or scope). AddScoped<T>() — still risky for builders if multiple usages occur within one request. = state leaks between usages in the same scope (generating two reports in one request means the second inherits the first's data). Better yet, don't register builders in DI at all — just new them. Builders are simple, have no dependencies, and are meant to be short-lived.

If a builder needs injected dependencies (rare), register a builder factory as Singleton that creates fresh builder instances: IBuilderFactory.Create(). The factory lives forever; the builders it creates are disposable and short-lived.

Object initializer: new Foo { A = 1, B = 2 }. Good for simple DTOs, no validation, object is mutable. Builder: validation in Build(), immutable product, cross-field rules, can transform inputs. Use initializers for simple data carriers; use Builder for domain objects with invariants.

C# 11's required keyword narrows the gap — it enforces property assignment at compile time — but still can't do cross-field validation or immutability.

A Test Data BuilderA Builder specifically designed for unit tests that provides sensible defaults for all properties. Tests only override the fields relevant to the scenario, keeping tests focused and readable. provides sensible defaults so each test only overrides what's relevant to that scenario. This avoids the "arrange monster" where every test manually sets 15 properties.

public class OrderTestBuilder
{
    private string _customerId = "C-DEFAULT";
    private string _product = "Widget";
    private decimal _price = 9.99m;
    private int _qty = 1;
    private string? _coupon;

    public OrderTestBuilder WithCustomer(string id) { _customerId = id; return this; }
    public OrderTestBuilder WithProduct(string p, decimal price) { _product = p; _price = price; return this; }
    public OrderTestBuilder WithQuantity(int q) { _qty = q; return this; }
    public OrderTestBuilder WithCoupon(string code) { _coupon = code; return this; }

    public Order Build() => new()
    {
        CustomerId = _customerId, Product = _product,
        Price = _price, Quantity = _qty, CouponCode = _coupon
    };
}

// Tests are now one-liners:
var order = new OrderTestBuilder().WithCoupon("SAVE10").Build();
var bulkOrder = new OrderTestBuilder().WithQuantity(500).Build();

Nested Builder (Josh Bloch style): The Builder is a static nested class inside the Product. Advantage: it can access the Product's private constructor, ensuring only the Builder can create instances. Usage: Order.Builder().WithCustomer("C1").Build().

Separate Builder: Lives in its own file. Advantage: better separation of concerns, easier to test, doesn't bloat the Product class. The Product needs an internal constructor for the builder to call.

Rule of thumb: Use nested if the Product and Builder are tightly coupled and the Product should be creatable ONLY via Builder. Use separate when multiple builders might produce the same Product type (like Classic GoF with Director).

required ensures a property is set during initialization — compile-time enforcement, zero boilerplate. But it has limits:

required can: enforce that a property is assigned (not null/default). required cannot: enforce cross-field rules ("if express shipping, address is required"), validate values ("email must contain @"), or produce immutable objects with complex construction logic.

// ✓ required is enough — simple DTO, no invariants
public class CreateUserRequest
{
    public required string Name { get; init; }
    public required string Email { get; init; }
}

// ✗ required is NOT enough — cross-field rules needed
// → Use Builder: OrderBuilder validates "express → address required"

IOptions<T>.NET's built-in configuration binding pattern. Maps appsettings.json sections to strongly-typed C# classes. Supports reload (IOptionsSnapshot), validation (DataAnnotations), and named options. binds configuration from external sources (appsettings.json, env vars) to a POCO. Builder constructs objects programmatically with step-by-step logic.

Use Options when: values come from config files/env vars, you need hot-reload (IOptionsSnapshot), or you want DataAnnotation validation. Use Builder when: construction involves computation, transformation, or cross-field business rules that go beyond simple property mapping.

They overlap for configuration objects — IConfigurationBuilder is literally a Builder that feeds into the Options pipeline.

This is one of the trickier C# patterns, so let's build up to it. Say you have a BaseBuilder with shared methods like WithName(), and a UserBuilder that inherits from it and adds WithAge(). You want fluent chaining: new UserBuilder().WithName("Alice").WithAge(30).

The problem: If WithName() returns BaseBuilder, the chain breaks at .WithAge() because the compiler sees a BaseBuilder at that point, and BaseBuilder does not have a WithAge() method. The solution is called CRTP (Curiously Recurring Template Pattern), where the base class takes its own subclass as a generic parameter: BaseBuilder<TSelf>. Now WithName() returns TSelf (the actual subclass type), and the chain preserves the concrete type.

public abstract class BaseBuilder<TSelf> where TSelf : BaseBuilder<TSelf>
{
    protected string Name = "";
    public TSelf WithName(string n) { Name = n; return (TSelf)this; }
}

public class UserBuilder : BaseBuilder<UserBuilder>
{
    private int _age;
    public UserBuilder WithAge(int a) { _age = a; return this; }
    public User Build() => new(Name, _age);
}

// ✓ Chain preserves UserBuilder type:
var user = new UserBuilder().WithName("Alice").WithAge(30).Build();

If you have ever written a .NET web app, you have already used the Builder pattern without realizing it. WebApplication.CreateBuilder(args) returns a WebApplicationBuilder, and everything you do between that line and .Build() is configuration. You are using a builder.

WebApplicationBuilder aggregates several sub-builders internally: ConfigurationManager handles app settings, IServiceCollection handles dependency injection registrations, and ILoggingBuilder handles logging providers. Properties like builder.Services give you direct access to configure DI; builder.Configuration lets you add config sources from JSON files, environment variables, or command-line args.

When you call Build(), a lot happens behind the scenes: it compiles all service registrations into an IServiceProvider (the DI container), merges all configuration sources into a single IConfiguration root, sets up the HTTP pipeline, and returns an immutable WebApplication ready to run. This is a "big bang" operation: everything comes together at Build time. After Build(), you cannot add more services or change configuration.

This is a favorite trick question in interviews. The interviewer wants to see if you reach for locks and synchronization, or if you step back and question the premise. The correct senior answer is usually: "don't share builders between threads." Each thread gets its own builder instance. Problem solved without any complexity.

Builders are inherently mutable and sequential. That is their whole job: accumulate state, then produce a product. Making them thread-safeCode that works correctly when accessed by multiple threads simultaneously. Achieved through locks, immutability, or thread-local storage. with locks defeats their purpose and adds unnecessary complexity. The locks also hurt performance because threads wait for each other, and the error-prone synchronization code is harder to test than the builder itself.

If you absolutely must share build state across threads (rare), use an immutable builder pattern where each method returns a new builder instance (via record + with) instead of mutating this. Each method returns a fresh copy, so no thread can observe partial state. Think of it like a Google Docs version history: each edit creates a new version, and nobody can corrupt another user's view.

Note: ImmutableArray.CreateBuilder() is a mutable builder for an immutable product. The builder itself is not thread-safe; only the resulting ImmutableArray is.

Sometimes you need to create many similar objects that differ in only one or two fields. Building each one from scratch through the full builder process would be wasteful. Instead, you build a "template" once with a Builder, then create variations by cloning it and tweaking a few fields. This is the PrototypeGoF creational pattern that creates new objects by copying an existing object (the prototype). In C#, implemented via ICloneable or record with-expressions. pattern combined with Builder.

In C#, the record type + with-expression is essentially Builder + Prototype baked into the language. You build the template once (Builder), then use with to create cheap variations (Prototype):

// Product must be a record for with-expression support
public sealed record Order(
    string CustomerId, string ProductId,
    string Address, bool ExpressShipping = false,
    bool GiftWrap = false, string? GiftMessage = null);

// Build the base template
var template = new OrderBuilder()
    .ForCustomer("C1").ForProduct("P1")
    .ShipTo("123 Main St").Build();

// Clone with variations (Prototype via record with-expression)
var express = template with { ExpressShipping = true };
var gift = template with { GiftWrap = true, GiftMessage = "Hi!" };

SQL injection is one of the most dangerous web vulnerabilities, and the Builder pattern is naturally suited to prevent it. The key idea: the builder collects the structure of the query (which table, which columns) separately from the user-provided values. When Build() runs, it produces a parameterized query where user input is never directly concatenated into the SQL string. Instead, values become @p0, @p1 parameters that the database engine handles safely.

The builder should also validate inputs. Table names are whitelisted (not user-provided). Column names are checked against a regex to prevent injection through column names. The Build() return type is a tuple: the SQL string plus a dictionary of parameters. This forces the caller to use parameterized queries because the values are separate from the SQL.

public sealed class SafeQueryBuilder
{
    private string _table = "";
    private readonly List<string> _conditions = [];
    private readonly Dictionary<string, object> _params = new();
    private int _paramCount = 0;

    private static readonly HashSet<string> _allowedTables =
        ["Users", "Orders", "Products"]; // whitelist

    public SafeQueryBuilder From(string table)
    {
        if (!_allowedTables.Contains(table))
            throw new ArgumentException($"Table '{table}' is not allowed.");
        _table = table; return this;
    }

    private static readonly Regex _validColumn =
        new(@"^[A-Za-z_][A-Za-z0-9_]{0,127}$", RegexOptions.Compiled);

    public SafeQueryBuilder Where(string column, object value)
    {
        if (!_validColumn.IsMatch(column))
            throw new ArgumentException($"Invalid column name: '{column}'");
        var paramName = $"@p{_paramCount++}";
        _conditions.Add($"[{column}] = {paramName}");
        _params[paramName] = value;
        return this;
    }

    public (string Sql, Dictionary<string, object> Params) Build()
    {
        var sql = $"SELECT * FROM [{_table}]";
        if (_conditions.Count > 0)
            sql += " WHERE " + string.Join(" AND ", _conditions);
        return (sql, new Dictionary<string, object>(_params));
    }
}

var (sql, parms) = new SafeQueryBuilder()
    .From("Users")
    .Where("Name", "O'Brien")    // ✓ Parameterized, not interpolated
    .Where("Active", true)
    .Build();
// sql: "SELECT * FROM Users WHERE Name = @p0 AND Active = @p1"

This comes up a lot in real projects. What happens when a builder step needs to call a database, read from a remote API, or load a file? You cannot just slap async on every fluent method because that breaks method chaining. With async methods, you would need to await each call individually: var b1 = await builder.StepA(); var b2 = await b1.StepB();. The clean one-liner chain is gone.

Approach 1 — Async Build() only (recommended): Keep all fluent methods synchronous. They just store configuration, URLs, paths, and parameters. No I/O. Then make only BuildAsync() async, and do all the I/O there. This preserves the clean chaining syntax: builder.WithTitle("X").WithTemplateUrl("https://...").BuildAsync().

Approach 2 — Async steps with callback registration: For cases where you genuinely need interleaved async steps (e.g., step 2 depends on step 1's async result), register each step as a Func<T, Task<T>> callback. The builder stores these callbacks and executes them sequentially in BuildAsync():

public class ReportBuilder(HttpClient httpClient)
{
    private readonly HttpClient _httpClient = httpClient;
    private readonly List<Func<Report, Task<Report>>> _steps = [];

    public ReportBuilder WithTitle(string t)
    { _steps.Add(r => Task.FromResult(r with { Title = t })); return this; }

    public ReportBuilder WithRemoteTemplate(string url)
    {
        _steps.Add(async r => {
            var template = await _httpClient.GetStringAsync(url);
            return r with { Template = template };
        });
        return this;
    }

    public async Task<Report> BuildAsync()
    {
        var report = new Report();
        foreach (var step in _steps)
            report = await step(report);
        return report;
    }
}

Builder APIs in libraries evolve — new steps are added, old ones deprecated. Key strategies:

(1) New optional methods with sensible defaults: Adding .WithTimeout() that defaults to 30s doesn't break anyone. This is the easiest path.

(2) Extension methods for new capabilities: Put new builder methods in a separate namespace. Callers who import the namespace get new features; others are unaffected.

(3) Interface versioning with Step Builder: Create IBuilderV2 that extends IBuilderV1 with new steps. Old code targets V1, new code targets V2.

(4) [Obsolete] attribute: Mark old methods with [Obsolete("Use WithConnectionString() instead")] — compiler warnings guide migration.

What NOT to do: Change the return type of an existing method, remove a method without [Obsolete] first, or change behavior silently.

Building immutable trees is a classic challenge because of a chicken-and-egg problem: a parent needs its children before it can be constructed (they are part of its IReadOnlyList), but children might also need their parent. The solution is to build bottom-up: construct leaf nodes first, then pass them to their parent's constructor. Recursive builders handle this elegantly.

public sealed record TreeNode(
    string Name,
    IReadOnlyList<TreeNode> Children);

public class TreeNodeBuilder
{
    private string _name = "";
    private readonly List<TreeNodeBuilder> _childBuilders = [];

    public TreeNodeBuilder WithName(string n) { _name = n; return this; }

    public TreeNodeBuilder AddChild(Action<TreeNodeBuilder> configure)
    {
        var child = new TreeNodeBuilder();
        configure(child);
        _childBuilders.Add(child);
        return this;
    }

    public TreeNode Build() => new(
        _name,
        _childBuilders.Select(c => c.Build()).ToList());
}

// Usage — nested lambda pattern:
var tree = new TreeNodeBuilder()
    .WithName("Root")
    .AddChild(c => c.WithName("A")
        .AddChild(gc => gc.WithName("A1"))
        .AddChild(gc => gc.WithName("A2")))
    .AddChild(c => c.WithName("B"))
    .Build();
// Root → [A → [A1, A2], B]

Walking through the code: The key method is AddChild(Action<TreeNodeBuilder> configure). Instead of returning a child builder that the caller manages, it creates a child builder internally and lets the caller configure it through a lambda. This keeps the parent in control. When you call Build() on the root, it calls Build() on each child builder, which calls Build() on their children, and so on. The whole tree is constructed recursively from the leaves up. By the time the root's Build() finishes, every node is a fully immutable TreeNode record with a read-only list of children.

Test Data Builders provide sensible defaults so tests only specify what's relevant. But in large projects, you end up maintaining 50+ builder classes — builder explosion.

Strategies to tame it:

(1) Generic base builder: Use CRTP to share common patterns (WithId, CreatedAt, etc.) across all test builders.

(2) AutoFixtureA .NET library that auto-generates test data. It creates objects with random but valid data, reducing the need for manual Test Data Builders. + customization: Instead of writing builders, use AutoFixture with ICustomization to define rules. It auto-fills properties you don't care about.

// Manual Test Data Builder (50+ classes to maintain):
var order = new OrderTestBuilder().WithCoupon("SAVE10").Build();

// AutoFixture approach (zero builder classes):
var fixture = new Fixture();
fixture.Customize<Order>(c => c
    .With(o => o.CouponCode, "SAVE10")
    .Without(o => o.CancelledAt));
var order = fixture.Create<Order>();

// Hybrid: AutoFixture for simple objects, Builder for complex ones
// with cross-field invariants that AutoFixture can't guarantee.

(3) Object Mother + Builder: A static factory class (Object MotherA pattern where a static factory class provides pre-configured test objects: OrderMother.CreateStandard(), OrderMother.CreateExpressWithCoupon(). Simpler than builders for common scenarios.) provides common scenarios (OrderMother.CreateExpressOrder()), while builders handle the customizable edge cases.

Writing builders by hand is repetitive: for every property, you write a private field, a fluent setter, and include it in Build(). This is exactly the kind of mechanical boilerplate that machines should handle. Roslyn source generatorsA C# compiler feature that runs during compilation and generates additional source files. They inspect your code via syntax/semantic models and emit new classes without reflection or runtime overhead. run during compilation, inspect your Product class, and automatically emit a complete Builder class. No runtime reflection, no performance cost, no maintenance burden.

// You write this:
[GenerateBuilder]
public sealed record Order(
    string CustomerId,
    string Product,
    decimal Price,
    int Quantity = 1,
    string? CouponCode = null);

// Source generator emits (at compile time):
public partial class OrderBuilder
{
    private string _customerId = default!;
    private string _product = default!;
    private decimal _price;
    private int _quantity = 1;
    private string? _couponCode;

    public OrderBuilder WithCustomerId(string v) { _customerId = v; return this; }
    public OrderBuilder WithProduct(string v) { _product = v; return this; }
    public OrderBuilder WithPrice(decimal v) { _price = v; return this; }
    public OrderBuilder WithQuantity(int v) { _quantity = v; return this; }
    public OrderBuilder WithCouponCode(string? v) { _couponCode = v; return this; }

    public Order Build() => new(_customerId, _product, _price, _quantity, _couponCode);
}

How it works: The generator's IIncrementalGenerator receives the syntax tree, finds types marked with [GenerateBuilder], reads their properties/constructor params, and emits With*() methods + Build(). Default parameter values become field initializers.

Limitations: Source generators can't add validation logic automatically (they don't know your business rules). You'd use a partial method hook: partial void Validate(Order order); that developers implement manually.