Imagine configuring an HTTP client with optional timeouts, headers, authentication, retry policies, and logging. A constructor with ten parameters becomes unreadable, especially when most are optional. You end up passing null repeatedly or creating multiple overloaded constructors that duplicate logic. The Builder pattern solves this by letting you construct objects step-by-step using a fluent interface.
Builders separate object construction from its representation. Instead of cramming all configuration into a single constructor call, you chain method calls that clearly express intent: client.WithTimeout(30).WithRetry(3).WithLogging(). Each method sets one aspect of the configuration, and a final Build() call creates the immutable object with all validations applied.
You'll learn when Builder outperforms constructors, how to implement fluent interfaces that read naturally, how to enforce required vs optional properties, and how to validate complex constraints before object creation completes.
Without Builder, you often create multiple constructors to handle different combinations of parameters. This "telescoping constructor" pattern becomes unwieldy as options grow. Each new parameter requires new constructor overloads, and calling code becomes cryptic when you can't tell what each argument represents.
Consider building a Product object with name, price, description, category, tags, and stock level. Some fields are required, others optional. Using only constructors, you'd need overloads for every combination, or one massive constructor with many nullable parameters.
// Telescoping constructors - hard to maintain
public class Product
{
public string Name { get; }
public decimal Price { get; }
public string Description { get; }
public string Category { get; }
public List<string> Tags { get; }
public int StockLevel { get; }
// Minimal required fields
public Product(string name, decimal price)
: this(name, price, string.Empty) { }
// Add description
public Product(string name, decimal price, string description)
: this(name, price, description, "General") { }
// Add category
public Product(string name, decimal price, string description, string category)
: this(name, price, description, category, new List<string>()) { }
// Add tags
public Product(string name, decimal price, string description,
string category, List<string> tags)
: this(name, price, description, category, tags, 0) { }
// All parameters
public Product(string name, decimal price, string description,
string category, List<string> tags, int stockLevel)
{
Name = name ?? throw new ArgumentNullException(nameof(name));
Price = price;
Description = description;
Category = category;
Tags = tags;
StockLevel = stockLevel;
}
}
// Usage is confusing - what does each parameter mean?
var product = new Product("Laptop", 999.99m, "Gaming laptop", "Electronics",
new List<string> { "gaming", "portable" }, 50);This approach explodes as you add more optional parameters. The final constructor call reads like a mystery—you can't tell what each value represents without counting positions or checking the signature. Adding a new optional field requires updating every constructor in the chain. The Builder pattern eliminates this complexity entirely.
A Builder encapsulates construction logic in a separate class with methods for each property. Each method returns the builder itself, enabling method chaining. A final Build() method validates all inputs and constructs the target object. This makes construction explicit, readable, and easy to validate.
The pattern works particularly well when the target object should be immutable after construction. The builder accumulates state mutably, then creates an immutable product. This gives you the best of both worlds: flexible construction and safe sharing.
public class Product
{
public string Name { get; }
public decimal Price { get; }
public string Description { get; }
public string Category { get; }
public List<string> Tags { get; }
public int StockLevel { get; }
// Private constructor forces use of builder
private Product(string name, decimal price, string description,
string category, List<string> tags, int stockLevel)
{
Name = name;
Price = price;
Description = description;
Category = category;
Tags = tags;
StockLevel = stockLevel;
}
public class Builder
{
private string _name;
private decimal _price;
private string _description = string.Empty;
private string _category = "General";
private List<string> _tags = new();
private int _stockLevel = 0;
public Builder WithName(string name)
{
_name = name;
return this;
}
public Builder WithPrice(decimal price)
{
_price = price;
return this;
}
public Builder WithDescription(string description)
{
_description = description;
return this;
}
public Builder WithCategory(string category)
{
_category = category;
return this;
}
public Builder WithTags(params string[] tags)
{
_tags.AddRange(tags);
return this;
}
public Builder WithStock(int level)
{
_stockLevel = level;
return this;
}
public Product Build()
{
// Validation before construction
if (string.IsNullOrWhiteSpace(_name))
throw new InvalidOperationException("Product name is required");
if (_price <= 0)
throw new InvalidOperationException("Price must be positive");
return new Product(_name, _price, _description, _category,
new List<string>(_tags), _stockLevel);
}
}
}
// Usage is clear and expressive
var product = new Product.Builder()
.WithName("Gaming Laptop")
.WithPrice(999.99m)
.WithDescription("High-performance laptop for gaming")
.WithCategory("Electronics")
.WithTags("gaming", "portable", "16GB RAM")
.WithStock(50)
.Build();Each method clearly states what it configures. The fluent chain reads like English, making code self-documenting. Build() centralizes validation, ensuring that invalid products can never be constructed. If you forget a required field, Build() throws a descriptive exception. This makes the API hard to misuse, catching errors at construction time rather than discovering them later during use.
Real-world objects often contain nested structures. An Order contains OrderItems, each with its own complex configuration. Builders can delegate to nested builders, maintaining the fluent interface while handling arbitrarily deep object graphs.
The key is returning the parent builder after configuring nested items. This lets you add multiple items without breaking the chain, then continue configuring the parent object.
public class OrderItem
{
public string ProductName { get; }
public int Quantity { get; }
public decimal UnitPrice { get; }
public OrderItem(string productName, int quantity, decimal unitPrice)
{
ProductName = productName;
Quantity = quantity;
UnitPrice = unitPrice;
}
public decimal Total => Quantity * UnitPrice;
}
public class Order
{
public string CustomerId { get; }
public List<OrderItem> Items { get; }
public string ShippingAddress { get; }
public DateTime OrderDate { get; }
private Order(string customerId, List<OrderItem> items,
string shippingAddress, DateTime orderDate)
{
CustomerId = customerId;
Items = items;
ShippingAddress = shippingAddress;
OrderDate = orderDate;
}
public class Builder
{
private string _customerId;
private readonly List<OrderItem> _items = new();
private string _shippingAddress;
private DateTime _orderDate = DateTime.UtcNow;
public Builder ForCustomer(string customerId)
{
_customerId = customerId;
return this;
}
public Builder AddItem(string productName, int quantity, decimal unitPrice)
{
_items.Add(new OrderItem(productName, quantity, unitPrice));
return this;
}
public Builder ShipTo(string address)
{
_shippingAddress = address;
return this;
}
public Builder OnDate(DateTime date)
{
_orderDate = date;
return this;
}
public Order Build()
{
if (string.IsNullOrWhiteSpace(_customerId))
throw new InvalidOperationException("Customer ID is required");
if (!_items.Any())
throw new InvalidOperationException("Order must contain at least one item");
if (string.IsNullOrWhiteSpace(_shippingAddress))
throw new InvalidOperationException("Shipping address is required");
return new Order(_customerId, new List<OrderItem>(_items),
_shippingAddress, _orderDate);
}
}
}
// Fluent nested construction
var order = new Order.Builder()
.ForCustomer("CUST-123")
.AddItem("Laptop", 1, 999.99m)
.AddItem("Mouse", 2, 29.99m)
.AddItem("Keyboard", 1, 79.99m)
.ShipTo("123 Main St, Seattle, WA 98101")
.Build();The AddItem method demonstrates how to handle collections. Each call adds one item and returns the builder, letting you chain multiple additions naturally. Build() validates the entire object graph, ensuring you can't create an empty order or one missing critical fields. This centralized validation is far simpler than validating in multiple constructors or property setters.
Sometimes you need several predefined configurations. A Director class encapsulates common builder sequences, providing factory-like methods that return pre-configured objects. This reduces duplication when multiple parts of your code need similar setups.
Directors are especially useful for testing, where you often need "typical" objects with sensible defaults but want to override specific fields per test. The director provides the baseline, and tests tweak individual properties.
public class ProductDirector
{
public static Product CreateBasicProduct(string name, decimal price)
{
return new Product.Builder()
.WithName(name)
.WithPrice(price)
.WithCategory("General")
.WithStock(10)
.Build();
}
public static Product CreateElectronicsProduct(string name, decimal price)
{
return new Product.Builder()
.WithName(name)
.WithPrice(price)
.WithCategory("Electronics")
.WithTags("electronics", "warranty")
.WithStock(25)
.Build();
}
public static Product CreatePromotionalProduct(string name, decimal price,
string promoCode)
{
return new Product.Builder()
.WithName($"{name} - PROMO")
.WithPrice(price * 0.8m) // 20% discount
.WithDescription($"Promotional offer - Use code {promoCode}")
.WithCategory("Promotions")
.WithTags("sale", "limited-time", promoCode)
.WithStock(100)
.Build();
}
}
// Usage
var basicProduct = ProductDirector.CreateBasicProduct("Widget", 19.99m);
var laptop = ProductDirector.CreateElectronicsProduct("Gaming Laptop", 1299.99m);
var promoItem = ProductDirector.CreatePromotionalProduct("Headphones", 79.99m,
"SAVE20");Directors don't replace builders; they complement them. When you need a standard configuration, use the director. When you need custom setup, use the builder directly. This pattern is common in test fixtures where you define methods like CreateValidOrder() and CreateOrderWithoutShipping() that return builders pre-configured for specific test scenarios.
Create a working HTTP request builder that demonstrates fluent construction with headers, query parameters, and timeout configuration.
dotnet new console -n BuilderDemocd BuilderDemodotnet run<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
</Project>class HttpRequest
{
public string Url { get; }
public string Method { get; }
public Dictionary<string, string> Headers { get; }
public Dictionary<string, string> QueryParams { get; }
public int TimeoutSeconds { get; }
private HttpRequest(string url, string method,
Dictionary<string, string> headers,
Dictionary<string, string> queryParams,
int timeoutSeconds)
{
Url = url;
Method = method;
Headers = headers;
QueryParams = queryParams;
TimeoutSeconds = timeoutSeconds;
}
public class Builder
{
private string _url = "";
private string _method = "GET";
private readonly Dictionary<string, string> _headers = new();
private readonly Dictionary<string, string> _queryParams = new();
private int _timeoutSeconds = 30;
public Builder ToUrl(string url) { _url = url; return this; }
public Builder UsingMethod(string method) { _method = method; return this; }
public Builder WithHeader(string key, string value)
{
_headers[key] = value; return this;
}
public Builder WithQueryParam(string key, string value)
{
_queryParams[key] = value; return this;
}
public Builder WithTimeout(int seconds)
{
_timeoutSeconds = seconds; return this;
}
public HttpRequest Build()
{
if (string.IsNullOrWhiteSpace(_url))
throw new InvalidOperationException("URL required");
return new HttpRequest(_url, _method,
new Dictionary<string, string>(_headers),
new Dictionary<string, string>(_queryParams),
_timeoutSeconds);
}
}
public override string ToString()
{
var query = QueryParams.Any()
? "?" + string.Join("&", QueryParams.Select(kv => $"{kv.Key}={kv.Value}"))
: "";
var headers = Headers.Any()
? "\nHeaders: " + string.Join(", ", Headers.Select(h => $"{h.Key}={h.Value}"))
: "";
return $"{Method} {Url}{query} (Timeout: {TimeoutSeconds}s){headers}";
}
}
var request = new HttpRequest.Builder()
.ToUrl("https://api.example.com/users")
.UsingMethod("GET")
.WithHeader("Authorization", "Bearer abc123")
.WithHeader("Accept", "application/json")
.WithQueryParam("page", "1")
.WithQueryParam("limit", "20")
.WithTimeout(60)
.Build();
Console.WriteLine(request);GET https://api.example.com/users?page=1&limit=20 (Timeout: 60s)
Headers: Authorization=Bearer abc123, Accept=application/jsonBuilder adds complexity that simple objects don't need. If your class has only 2-3 required parameters and no optional ones, a straightforward constructor is clearer. Don't introduce Builder just because you can—use it when construction complexity justifies the extra abstraction.
Similarly, if your object is mutable by design and clients will set properties after construction anyway, Builder provides little value. Records with init-only properties or object initializers handle simple cases well: new Product { Name = "Widget", Price = 9.99m } works fine when you don't need complex validation or step sequencing.
Builder shines when you need to enforce invariants across multiple properties, construct immutable objects with many optional fields, or provide a fluent API for complex configuration. If your use case doesn't match these needs, simpler patterns like constructors with optional parameters or property initializers will serve you better without the extra indirection.
Use Builder when you have many optional parameters, need validation across multiple properties, or want to enforce construction steps. If your constructor takes more than 4-5 parameters or has complex validation logic that spans multiple fields, Builder makes the code more readable and maintainable than telescoping constructors.
Return this to enable fluent chaining: builder.WithName(x).WithAge(y).Build(). This pattern reads naturally and reduces boilerplate. Only return void if you never want method chaining, but fluent interfaces are the modern standard for builders and significantly improve the developer experience.
Validate in the Build() method before creating the final object. Store values during With* calls, then check all constraints in one place when Build() executes. Throw descriptive exceptions if required fields are missing or invalid. This centralizes validation and makes it easy to test without constructing partial objects.