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.
var pizza = new PizzaBuilder() .Size(12) .AddTopping("olives") .Build();
Try it
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.
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
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
withexpressions give an immutable fluent style without a separate builder class. - Prefer simpler tools first. Constructors with optional parameters,
requiredmembers and object initializers are less code for small types. - Return types matter. A step that returns
voidends the chain. Keep the return type the builder type, or use an interface per step for "step builders" that force an order. - LINQ and
StringBuilderare fluent APIs you already use;StringBuilder.Appendreturns the same instance, LINQ operators return new sequences. - Naming. The usual conventions are
With...,Add...,Set...or the bare property name, andBuild()orCreate()to finish.