Request Builder Pattern
CivitaiSharp uses a fluent builder pattern for constructing type-safe, validated queries.
Core Principles
Immutability: Builders are immutable records. Each method returns a new copy with updated configuration.
Lazy Execution: No network activity until you call ExecuteAsync(), FirstOrDefaultAsync(), or GetByIdAsync().
Immediate Validation: Invalid parameters throw immediately, not during execution.
Request Lifecycle
- Entry Point: Access builder via
ApiClient(client.Models,client.Images, etc.) - Configuration: Chain methods to set filters, sorting, options
- Execution: Call async method to send request and retrieve results
Example
var baseQuery = apiClient.Models.WhereType(ModelType.Lora);
// baseQuery is NOT modified - a new instance is created
var animeQuery = baseQuery.WhereTag("anime");
var realisticQuery = baseQuery.WhereTag("realistic");
// All three are independent queries
var baseResult = await baseQuery.ExecuteAsync(resultsLimit: 5);
var animeResult = await animeQuery.ExecuteAsync(resultsLimit: 5);
var realisticResult = await realisticQuery.ExecuteAsync(resultsLimit: 5);
Console.WriteLine($"Base query: {(baseResult.IsSuccess ? baseResult.ValueOrDefault!.Items.Count : 0)} items");
Console.WriteLine($"Anime query: {(animeResult.IsSuccess ? animeResult.ValueOrDefault!.Items.Count : 0)} items");
Console.WriteLine($"Realistic query: {(realisticResult.IsSuccess ? realisticResult.ValueOrDefault!.Items.Count : 0)} items");