You already use a real Builder every time you write WebApplication.CreateBuilder(args) — this lesson gives that shape its name.

Imagine a Report class with a title, an author, an optional date range, an optional list of chart types, an optional footer note, and a flag for whether to include raw data tables. A constructor covering every combination looks like new Report("Q3 Sales", "J. Smith", start, end, chartTypes, footer, true) — seven positional arguments, most of them optional, and utterly unreadable at the call site. Add an eighth optional field next quarter, and every single call site needs to change, or you write a second, third, and fourth overload just to cover the common combinations. This is the classic telescoping constructor problem: constructors that grow longer and more overloaded every time a new optional piece of configuration is needed.

The Builder Pattern — a Creational pattern, alongside Factory (240) — solves this by separating how an object gets constructed, step by step from what the finished object looks like. Instead of one enormous constructor call, you set pieces one at a time, in readable, named steps, and ask for the finished object only once every piece is in place.

In this lesson, you'll see the telescoping constructor problem Builder was designed to solve — and, just as importantly, you'll see honestly that modern C# already solves a large part of that same problem without a Builder at all. Then you'll learn precisely when a real Builder still earns its keep, and build one from scratch.

What Is It?

The Simple Explanation

A Builder is a separate object whose entire job is assembling another object piece by piece, through a sequence of clearly named steps, and handing back the finished result only when you explicitly ask for it — usually by calling a final .Build() method.

The Technical Definition

The GoF definition: separate the construction of a complex object from its representation, so that the same construction process can create different representations. In practice, that means the object being built (often called the "product") doesn't know how it's being assembled — the Builder owns the assembly sequence, can validate or apply logic at each step, and only produces the finished, ready-to-use object at the very end.

Why Does It Exist? — the Telescoping Constructor Problem

//  THE TELESCOPING CONSTRUCTOR PROBLEM — one overload per "reasonable" combination
public class Report
{
    public Report(string title, string author) { /* ... */ }
    public Report(string title, string author, DateTime start, DateTime end) { /* ... */ }
    public Report(string title, string author, DateTime start, DateTime end, bool includeCharts) { /* ... */ }
    public Report(string title, string author, DateTime start, DateTime end, bool includeCharts, string footer) { /* ... */ }
    // ...and every NEW optional field means another overload, or editing an existing one
    // and hunting down every call site that used it.
}

// At the call site — which bool is which? Which overload is even being called here?
var report = new Report("Q3 Sales", "J. Smith", start, end, true, "Confidential");

Big Picture — an Honest Update: Modern C# Already Solves Part of This

Here's the important, honest twist this lesson has to address directly: in 1994, when the GoF catalog was written, C# didn't exist, and even early C# had no clean way to set several optional properties readably in one expression. That's completely changed. Object initializers, required members (Foundations lesson 057), and primary constructors (Foundations lesson 058) together solve the "object has many optional properties" problem directly, with zero extra classes:

//  MODERN C# — no Builder class needed for "many optional properties"
public class Report
{
    public required string Title { get; init; }
    public required string Author { get; init; }
    public DateTime? StartDate { get; init; }
    public DateTime? EndDate { get; init; }
    public bool IncludeCharts { get; init; } = false;
    public string? Footer { get; init; }
}

// Readable, named, order-independent, and the COMPILER enforces Title and Author:
var report = new Report
{
    Title = "Q3 Sales",
    Author = "J. Smith",
    IncludeCharts = true,
    Footer = "Confidential"
};
// var broken = new Report { Author = "J. Smith" }; //  compile error — missing required 'Title'

When a Real Builder Still Earns Its Keep

Object initializers set properties on an object that already, technically, exists as a single expression. A real Builder is warranted when construction is genuinely a process — something that happens across multiple, distinct steps, not a single flat list of property values:

How It Works — Building a Fluent Builder, Step by Step

Simple Example

public sealed class ReportBuilder
{
    private string? _title;
    private string? _author;
    private readonly List<string> _sections = [];

    public ReportBuilder WithTitle(string title)
    {
        _title = title;
        return this;   // ← enables fluent chaining
    }

    public ReportBuilder WithAuthor(string author)
    {
        _author = author;
        return this;
    }

    public ReportBuilder AddSection(string section)
    {
        _sections.Add(section);
        return this;
    }

    public Report Build()
    {
        if (string.IsNullOrWhiteSpace(_title))
            throw new InvalidOperationException("A report must have a title before it can be built.");
        return new Report(_title, _author ?? "Unknown", _sections.AsReadOnly());
    }
}

// ── Usage — a readable, step-by-step, fluent chain ──
var report = new ReportBuilder()
    .WithTitle("Q3 Sales")
    .WithAuthor("J. Smith")
    .AddSection("Revenue")
    .AddSection("Regional Breakdown")
    .Build();

Code → Meaning → Result: Each fluent call returns the builder itself, so calls chain naturally. Build() is the single point where validation happens (a report needs a title) and where the actual, immutable Report gets constructed. Nothing about ReportBuilder's shape would fit cleanly into a single object initializer, because sections accumulate through repeated calls to AddSection — a genuine multi-step process, not a flat list of properties.

Real-World Example — a QueryBuilder With Progressive Validation

A query builder for a search feature is a case where each step genuinely needs to validate as it goes, and the final shape of the query depends on which steps were called at all:

public sealed record ProductQuery(string? Keyword, decimal? MinPrice, decimal? MaxPrice, string? Category, int PageSize);

public sealed class ProductQueryBuilder
{
    private string? _keyword;
    private decimal? _minPrice;
    private decimal? _maxPrice;
    private string? _category;
    private int _pageSize = 20;

    public ProductQueryBuilder WithKeyword(string keyword)
    {
        if (string.IsNullOrWhiteSpace(keyword))
            throw new ArgumentException("Keyword cannot be blank.", nameof(keyword));
        _keyword = keyword;
        return this;
    }

    public ProductQueryBuilder WithPriceRange(decimal min, decimal max)
    {
        // ── Validation happens progressively, AS each piece is added — not deferred to the end ──
        if (min < 0 || max < min)
            throw new ArgumentException("Invalid price range.");
        _minPrice = min;
        _maxPrice = max;
        return this;
    }

    public ProductQueryBuilder InCategory(string category)
    {
        _category = category;
        return this;
    }

    public ProductQueryBuilder PageSize(int size)
    {
        if (size is < 1 or > 100)
            throw new ArgumentOutOfRangeException(nameof(size), "Page size must be between 1 and 100.");
        _pageSize = size;
        return this;
    }

    public ProductQuery Build() => new(_keyword, _minPrice, _maxPrice, _category, _pageSize);
}

// ── Usage — steps applied conditionally, based on which search filters the user actually chose ──
var builder = new ProductQueryBuilder().PageSize(50);
if (!string.IsNullOrEmpty(searchTerm)) builder.WithKeyword(searchTerm);
if (selectedCategory is not null) builder.InCategory(selectedCategory);
if (minPrice.HasValue && maxPrice.HasValue) builder.WithPriceRange(minPrice.Value, maxPrice.Value);
var query = builder.Build();

Notice what this buys you that an object initializer couldn't: WithPriceRange validates min and max together, at the moment they're added — a rule an object initializer's independent property assignments can't express. And the calling code conditionally invokes only the steps it needs, based on which filters the user actually selected — a genuinely step-based, branching construction process.

Analogy — Building a Custom Sandwich, Not Filling Out a Form

Under the Hood — the Mechanics That Make Fluent Builders Work

Common Confusion

"Isn't an object initializer basically a Builder already?"

No — and the distinction is exactly what this lesson is built around. An object initializer sets properties on an object in one single expression; there's no accumulated state between calls, no way for one property's value to be validated against another's as they're set, and no notion of "steps" happening in sequence at all — it's syntactic sugar over setting properties, not a process. A real Builder maintains its own mutable state across multiple, separate method calls, and can enforce relationships between pieces as they're added. If your "construction" genuinely fits into one flat expression, you don't have a Builder problem — you have an object-initializer-shaped problem, and 057/058 already solve it.

Builder vs. Factory — different questions entirely

Factory (240) answers "which concrete class should be instantiated?" — a decision, usually made instantly, based on some input. Builder answers "how do I assemble this one, already-known type across several steps?" — a process, potentially spanning many method calls over time. You can genuinely combine them — a Factory could internally use a Builder to assemble the object it returns — but they solve different-shaped problems and shouldn't be confused for the same thing just because both are Creational.

Common Mistakes

Mistake 1 — Writing a Builder for an object that's really just "several optional properties"

Hand-rolling a PersonBuilder with .WithName(...), .WithAge(...), .WithEmail(...) for a flat data object with no cross-field validation and no real construction sequence — pure ceremony around what an object initializer already does more simply. Reach for object initializers plus required (057) first; only introduce a Builder once genuine multi-step logic or progressive validation is actually present.

Mistake 2 — Forgetting to validate in Build(), letting an incomplete object escape

A ReportBuilder.Build() that happily returns a Report with no title set, silently, because no check was ever added — the whole point of centralizing construction is lost if the final step doesn't actually enforce the invariants it's supposed to guard. Treat Build() as the one place that must validate every mandatory piece is present before handing back a usable object — exactly as shown in this lesson's examples.

Mistake 3 — Making the finished product itself mutable, defeating the point of a controlled build process

Having Build() return an object with public setters, so code elsewhere can silently mutate it after construction, bypassing every validation rule the Builder carefully enforced. Make the finished product immutable — a record with init-only properties, or a class with a private constructor only the Builder can call — so the guarantees established during building actually hold for the object's entire lifetime.

When Should I Use It?

• Construction genuinely happens across multiple, distinct steps — possibly conditionally, possibly from different parts of the code, before the object is finally assembled.
• Validation or business logic needs to run progressively, as pieces are added — not just once, at the very end.
• You're designing a fluent, discoverable configuration API for other developers — like WebApplicationBuilder itself — where chained, named method calls read more clearly than a giant constructor or options object.

And when it's overkill: if the "problem" is really just "this object has several optional properties," reach for object initializers, required members (057), and primary constructors (058) first — they solve exactly that problem, with less code, no extra class, and no risk of an incomplete object escaping through a forgotten step. A Builder is warranted by genuine process, not merely by property count.

Mental Model

Key Takeaway

Check Your Understanding

You've seen when modern C# already solves the problem Builder was invented for, and when a real Builder still earns its keep. Let's confirm you can tell the two situations apart.

You now know exactly when modern C# already solves your construction problem, and when a real Builder — the same shape as WebApplicationBuilder itself — genuinely earns its place.

dotnetmadeeasy.com — Learn C# and .NET, the right way.