Trellis API Reference
Trellis is a .NET framework that guides AI to develop structured, maintainable enterprise software. It combines Railway-Oriented Programming and Domain-Driven Design into building blocks where the compiler enforces correctness — errors must be handled, objects cannot be constructed in invalid states, and business logic reads like the specification it was generated from.
A trellis guides growth in the right direction. In a garden, plants grow along the trellis rather than sprawling randomly. In software, Trellis guides AI-generated code into correct, composable patterns — turning a plain-language specification into working, tested software with zero warnings and zero skipped validations.
// Without Trellis — AI scatters validation, misses edge cases, drifts across endpoints
if (string.IsNullOrWhiteSpace(request.Email))
return Results.BadRequest(new { code = "validation.error", detail = "Email is required." });
if (!request.Email.Contains('@'))
return Results.BadRequest(new { code = "validation.error", detail = "Email is invalid." });
return Results.Ok(new User(request.Email.Trim().ToLowerInvariant()));
// With Trellis — AI follows the types, the compiler catches the rest
return EmailAddress.TryCreate(request.Email)
.Map(email => new User(email))
.ToHttpResponse();
New to Trellis? Start with the Introduction, see how AI uses Trellis, or browse the examples.
Core Types
The foundation — zero dependencies beyond the .NET runtime. One using Trellis; makes these available.
| Type | Purpose |
|---|---|
Result<T> |
An operation that succeeds with T or fails with an Error — the core of Railway-Oriented Programming |
Result |
Non-generic result for void operations — succeeds without a value or fails with an Error |
Maybe<T> |
A value that may or may not exist — type-safe alternative to null |
Error |
Typed error hierarchy with built-in HTTP status code mapping |
Pipeline Operations
Chain operations into readable workflows. Each method has sync, Task, and ValueTask overloads.
| Operation | What it does |
|---|---|
Bind |
Chain an operation that returns Result — the railway switch |
Map |
Transform the success value |
Tap |
Run a side effect without changing the result |
Ensure |
Validate a business rule — fail if the predicate is false |
Combine |
Merge multiple results, collecting all errors |
Check |
Run a validation that returns Result, keep the original value on success |
Match |
Unwrap the result by handling both success and failure |
RecoverOnFailure |
Provide a fallback value on failure |
MapOnFailure |
Transform the value on the failure track |
TapOnFailure |
Run a side effect on the failure track |
When |
Execute conditionally based on a predicate |
Learn the pipeline patterns: Core Concepts · Error Handling · Advanced Features
Domain-Driven Design
DDD building blocks for modeling your domain. Also in the Trellis namespace.
| Type | Purpose |
|---|---|
Aggregate<T> |
Consistency boundary with a typed identity and domain events |
Entity<T> |
Domain object with a unique identity |
ValueObject |
Immutable object defined by its attributes, not its identity |
Specification<T> |
Composable business rule that can be combined with And, Or, Not |
Learn more: Aggregate Factory Pattern · Specifications
Value Objects
Base classes in the Trellis namespace; ready-to-use primitives in Trellis.Primitives.
| Base class | Wraps | Example |
|---|---|---|
RequiredString<TSelf> |
Non-empty string |
FirstName, ProductCode |
RequiredGuid<TSelf> |
Non-empty Guid |
OrderId, UserId |
RequiredInt<TSelf> |
Validated int |
Quantity, LineNumber |
RequiredDecimal<TSelf> |
Validated decimal |
Price, Weight |
RequiredEnum<TSelf> |
Validated enum |
OrderStatus, Priority |
ScalarValueObject<TSelf, T> |
Any single primitive | Custom scalar values |
Ready-to-use: EmailAddress, Money, PhoneNumber, Url, Slug, CountryCode, CurrencyCode, Percentage, and more.
Learn more: Primitive Value Objects
Integration Packages
Each integration has its own namespace and pulls in the relevant third-party dependency.
| Namespace | What it does | Guide |
|---|---|---|
Trellis.Asp |
Result<T> → HTTP responses for MVC and Minimal APIs; ASP.NET actor providers (Claims, Entra, Development) |
ASP.NET Core · Authorization |
Trellis.Authorization |
Actor, permission checks, resource authorization |
Authorization |
Trellis.Http |
HttpClient extensions that stay inside the Result pipeline |
HTTP Client |
Trellis.FluentValidation |
FluentValidation output → Trellis Result |
FluentValidation |
Trellis.EntityFrameworkCore |
Value object converters, Maybe<T> queries, safe save |
EF Core |
Trellis.Mediator |
Result-aware pipeline behaviors for Mediator | Mediator |
Trellis.StateMachine |
State machine transitions returning Result<TState> |
State Machines |
Trellis.Testing |
FluentAssertions extensions for Result<T> and Maybe<T> |
Testing |
Tooling
| Package | What it does |
|---|---|
| Trellis.Analyzers | 19+ Roslyn analyzers that catch common mistakes at build time |
| Trellis.Core.Generator | Source generation for RequiredString and related primitives — bundled inside Trellis.Core (no separate package) |
See all analyzer rules: Analyzer Rules
Observability
Built-in OpenTelemetry tracing via ResultsTraceProviderBuilderExtensions and PrimitiveValueObjectTraceProviderBuilderExtensions. Automatic span creation for pipeline operations and value object creation boundaries.
Learn more: Observability & Monitoring
Next Steps
| Goal | Where to go |
|---|---|
| Understand the concepts | Introduction |
| Learn the pipeline operations | Core Concepts |
| See it compared side-by-side | With vs Without Trellis |
| Browse working code | Examples |
| Set up integrations | Integration Overview |
| Run the benchmarks | Performance |