Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Classes and Object-Oriented Concepts

Builder and fluent interfaces

Reference for the C# builder pattern and fluent interfaces: method chaining, building immutable objects step by step, validation in Build(), and StringBuilder.

A builder assembles a complex object step by step and produces the final, usually immutable, result in one call. A fluent interface is the API style that makes this pleasant: each configuration method returns the builder itself (or a new object), so calls chain: new RequestBuilder().Url(...).Header(...).Build().

Builders help when a type has many optional settings, when construction needs validation across several values, or when you want the finished object to be immutable. In modern C# object initializers, required members, init properties and records cover many simple cases. Reach for a builder when those are not enough.

C#
var pizza = new PizzaBuilder()
    .Size(12)
    .AddTopping("olives")
    .Build();

Try it

C# A fluent builder that validates in Build

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Fluent chaining with StringBuilder and extension methods

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public sealed class ThingBuilder
{
    private int size;
    public ThingBuilder Size(int value) { size = value; return this; }  // fluent step
    public Thing Build() => new Thing(size);                             // final step
}
Part Description
Step methods Set one option and return this, so calls can be chained.
Build() Validates the collected values and creates the finished object. Throws InvalidOperationException (or ArgumentException) if the combination is invalid.
Product class Usually immutable, with an internal or private constructor so only the builder creates it.

Usage notes

  • Copy mutable state in Build(). If the builder keeps a dictionary or list and passes it straight to the product, later builder calls would change the finished object. The example copies the dictionary.
  • Validate in one place. Cross-field rules (a GET without a body) belong in Build(), where all values are known.
  • Builders are not thread-safe unless you make them so, and a builder is normally used once.
  • Fluent does not need mutation. Records with with expressions give an immutable fluent style without a separate builder class.
  • Prefer simpler tools first. Constructors with optional parameters, required members and object initializers are less code for small types.
  • Return types matter. A step that returns void ends the chain. Keep the return type the builder type, or use an interface per step for "step builders" that force an order.
  • LINQ and StringBuilder are fluent APIs you already use; StringBuilder.Append returns the same instance, LINQ operators return new sequences.
  • Naming. The usual conventions are With..., Add..., Set... or the bare property name, and Build() or Create() to finish.