TypedRequestContext

https://github.com/zio-net/typedrequestcontext
Admin
TypedRequestContext is an ASP.NET Core middleware that enables per-endpoint strongly-typed request...
Tokens:9,836
Snippets:77
Trust Score:5.1
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install TypedRequestContext.Propagation NuGet Package (PowerShell)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Installs the optional TypedRequestContext.Propagation NuGet package using the .NET CLI. This package enables features for serializing/deserializing context and header providers for propagation across services and async boundaries.

```powershell
dotnet add package TypedRequestContext.Propagation
```

--------------------------------

### Install TypedRequestContext NuGet Package (PowerShell)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Installs the core TypedRequestContext NuGet package using the .NET CLI. This package provides the middleware, attributes, accessor, and correlation ID functionality.

```powershell
dotnet add package TypedRequestContext
```

--------------------------------

### Registering Typed Request Context

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Demonstrates how to register custom context types with the Typed Request Context system. This is the initial setup step required before using typed contexts.

```csharp
builder.Services.AddTypedRequestContext<CustomerRequestContext>();
```

--------------------------------

### Complete TypedRequestContext Integration Example in C#

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Demonstrates registering TypedRequestContext services, configuring middleware, defining multiple context types, and using them in endpoints. It also shows how to propagate context to downstream HTTP clients.

```csharp
using TypedRequestContext;
using TypedRequestContext.Propagation;

var builder = WebApplication.CreateBuilder(args);

// 1. Register all services
builder.Services.AddTypedRequestContext();
builder.Services.AddTypedRequestContextPropagation();
builder.Services.AddCorrelationId();
builder.Services.AddTypedRequestContext<CustomerRequestContext>();
builder.Services.AddTypedRequestContext<InternalServiceRequestContext>();
builder.Services.AddHttpClient<DownstreamClient>();

var app = builder.Build();

// 2. Configure middleware (AFTER auth)
app.UseAuthentication();
app.UseAuthorization();
app.UseTypedRequestContext();

// 3. Define endpoints with context requirements
var api = app.MapGroup("/api").WithRequestContext<CustomerRequestContext>();

api.MapGet("/orders", async (
    CustomerRequestContext ctx,
    ICorrelationContext correlation,
    DownstreamClient downstream,
    CancellationToken ct) =>
{
    // Context is available via DI
    Console.WriteLine($"[{correlation.CorrelationId}] Fetching orders for tenant {ctx.TenantId}");

    // Propagate context to downstream service
    var response = await downstream.CallDownstreamAsync("/api/inventory", ct);

    return Results.Ok(new
    {
        tenantId = ctx.TenantId,
        userId = ctx.UserId,
        correlationId = correlation.CorrelationId
    });
});

// Override context for internal endpoints
api.MapPost("/internal/sync", async (
    InternalServiceRequestContext ctx,
    ICorrelationContext correlation) =>
{
    Console.WriteLine($"[{correlation.CorrelationId}] Sync from service: {ctx.ServiceName}");
    return Results.Ok();
}).WithRequestContext<InternalServiceRequestContext>();

app.Run();

// Context definitions
public sealed class CustomerRequestContext : ITypedRequestContext
{
    [FromClaim("sub"), RequiredContextValue, PropagationKey("x-user-id")]
    public Guid UserId { get; init; }

    [FromClaim("tenant_id"), RequiredContextValue, PropagationKey("x-tenant-id")]
    public Guid TenantId { get; init; }

    [FromClaim("role"), PropagationKey("x-role")]
    public string? Role { get; init; }
}

public sealed class InternalServiceRequestContext : ITypedRequestContext
{
    [FromHeader("x-service-name"), RequiredContextValue]
    public string ServiceName { get; init; } = default!;
}

// HTTP client with automatic context propagation
public sealed class DownstreamClient(HttpClient http, IPropagationHeadersProvider headers)
{
    public async Task<HttpResponseMessage> CallDownstreamAsync(string endpoint, CancellationToken ct)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, endpoint);
        foreach (var (key, value) in headers.GetCurrentHeaders())
            request.Headers.TryAddWithoutValidation(key, value);
        return await http.SendAsync(request, ct);
    }
}

```

--------------------------------

### Adding Typed Request Context Propagation

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Shows how to install the propagation package and register its services. This enables the serialization and propagation of typed context across service boundaries.

```csharp
using TypedRequestContext;
using TypedRequestContext.Propagation;

builder.Services
    .AddTypedRequestContext()
    .AddTypedRequestContextPropagation();
```

--------------------------------

### Getting Propagation Headers for Outbound Calls

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Demonstrates how to use `IPropagationHeadersProvider` to retrieve headers representing the current typed context, including correlation ID if enabled. These headers can be added to outbound HTTP requests.

```csharp
using TypedRequestContext.Propagation;

public sealed class DownstreamClient(
    HttpClient http,
    IPropagationHeadersProvider headers)
{
    public async Task<HttpResponseMessage> CallAsync(CancellationToken ct)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data");

        foreach (var (key, value) in headers.GetCurrentHeaders())
            request.Headers.TryAddWithoutValidation(key, value);

        return await http.SendAsync(request, ct);
    }
}
```

--------------------------------

### Register TypedRequestContext Services (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Registers the necessary services for TypedRequestContext, including optional correlation ID support and specific typed context types. This setup configures the middleware to extract and manage the defined context objects during the request processing.

```csharp
using TypedRequestContext;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddTypedRequestContext()
    .AddCorrelationId() // optional
    .AddTypedRequestContext<CustomerRequestContext>()
    .AddTypedRequestContext<InternalServiceRequestContext>();

var app = builder.Build();
```

--------------------------------

### Producer: Creating Metadata for Non-HTTP Propagation

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Shows how a producer can use `IPropagationHeadersProvider` to generate a dictionary of headers representing the current typed context. This dictionary can be sent as metadata with messages or events.

```csharp
using TypedRequestContext.Propagation;

public sealed class Producer(IPropagationHeadersProvider headers)
{
    public IReadOnlyDictionary<string, string> CreateMetadata()
        => headers.GetCurrentHeaders();
}
```

--------------------------------

### Defining a Typed Request Context with Propagation Keys

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Illustrates how to define a custom request context class, marking properties for propagation using `[PropagationKey]`. It also shows how to specify source attributes like `[FromClaim]` and `[RequiredContextValue]`.

```csharp
using TypedRequestContext;
using TypedRequestContext.Propagation;

public sealed class CustomerRequestContext : ITypedRequestContext
{
    [FromClaim("sub"), RequiredContextValue, PropagationKey("x-user-id")]
    public Guid UserId { get; init; }

    [FromClaim("tenant_id"), RequiredContextValue, PropagationKey("x-tenant-id")]
    public Guid TenantId { get; init; }

    [FromClaim("role"), PropagationKey("x-role")]
    public string? Role { get; init; }

    // No PropagationKey => stays local; not serialized
    [FromClaim("email")]
    public string? Email { get; init; }
}
```

--------------------------------

### Register Core TypedRequestContext Services

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Registers the essential services for the Typed Request Context framework, including the IRequestContextAccessor and the default attribute-based extractor. This should be called once during application startup. You then register each specific context type using AddTypedRequestContext<T>().

```csharp
using TypedRequestContext;

var builder = WebApplication.CreateBuilder(args);

// Register core framework (once)
builder.Services.AddTypedRequestContext();

// Register each context type you'll use
builder.Services.AddTypedRequestContext<CustomerRequestContext>();
builder.Services.AddTypedRequestContext<InternalServiceRequestContext>();
builder.Services.AddTypedRequestContext<AdminRequestContext>();

// Optional: Add correlation ID support
builder.Services.AddCorrelationId();

var app = builder.Build();

// Add middleware AFTER authentication/authorization
app.UseAuthentication();
app.UseAuthorization();
app.UseTypedRequestContext();

app.Run();
```

--------------------------------

### Deserialize Typed Request Context from Metadata (C#)

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Demonstrates how to use IRequestContextDeserializer<T> to deserialize typed request context from metadata dictionaries for non-HTTP flows. It shows a producer creating metadata and a consumer restoring ambient context.

```csharp
using TypedRequestContext;
using TypedRequestContext.Propagation;

// Producer: Create metadata for queue message
public sealed class OrderProducer(IPropagationHeadersProvider headers)
{
    public async Task PublishOrderAsync(Order order)
    {
        var metadata = headers.GetCurrentHeaders();
        // metadata contains: x-user-id, x-tenant-id, x-role, x-correlation-id

        await messageQueue.PublishAsync(new QueueMessage
        {
            Body = JsonSerializer.Serialize(order),
            Metadata = metadata
        });
    }
}

// Consumer: Restore context from queue message metadata
public sealed class OrderConsumer(
    IRequestContextDeserializer<CustomerRequestContext> deserializer,
    IRequestContextAccessor accessor,
    OrderProcessor processor)
{
    public async Task HandleAsync(QueueMessage message, CancellationToken ct)
    {
        // Deserialize context from message metadata
        var ctx = deserializer.Deserialize(message.Metadata);

        // Set ambient context for downstream services
        accessor.Current = ctx;
        try
        {
            // Services can now inject CustomerRequestContext or use IRequestContextAccessor
            await processor.ProcessOrderAsync(
                JsonSerializer.Deserialize<Order>(message.Body)!, 
                ct);
        }
        finally
        {
            accessor.Current = null;
        }
    }
}
```

--------------------------------

### Extract Request Context from HTTP Headers using FromHeaderAttribute

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Shows how to use the `FromHeaderAttribute` to populate a property from an HTTP request header. This is useful for context values provided by API gateways or upstream services. The `RequiredContextValueAttribute` can be used to ensure the header is present, resulting in an HTTP 403 error if missing.

```csharp
using TypedRequestContext;

public sealed class GatewayRequestContext : ITypedRequestContext
{
    // Required header from API gateway
    [FromHeader("x-tenant-id"), RequiredContextValue]
    public Guid TenantId { get; init; }

    // Optional operation tracking header
    [FromHeader("x-operation-id")]
    public Guid? OperationId { get; init; }

    // Optional request source identifier
    [FromHeader("x-request-source")]
    public string? RequestSource { get; init; }
}
```

--------------------------------

### Consumer: Restoring Typed Context from Metadata

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Illustrates how a consumer can deserialize a typed request context from metadata (e.g., message properties) using `IRequestContextDeserializer`. It then sets the deserialized context into `IRequestContextAccessor.Current`.

```csharp
using TypedRequestContext;
using TypedRequestContext.Propagation;

public sealed class Handler(
    IRequestContextDeserializer<CustomerRequestContext> deserializer,
    IRequestContextAccessor accessor)
{
    public async Task HandleAsync(IReadOnlyDictionary<string, string> metadata, CancellationToken ct)
    {
        var ctx = deserializer.Deserialize(metadata);

        accessor.Current = ctx;
        try
        {
            // Your handler/service code can now inject CustomerRequestContext
            // or use IRequestContextAccessor.GetRequired<CustomerRequestContext>().
            await Task.CompletedTask;
        }
        finally
        {
            accessor.Current = null;
        }
    }
}
```

--------------------------------

### Adding Correlation ID Support

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Explains how to enable the correlation ID feature, which tracks requests across services. It details how the ID is read, generated, and echoed back in the response.

```csharp
builder.Services.AddCorrelationId();
```

--------------------------------

### Handling Missing Required Context Values

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Illustrates the JSON response format when a required context value (like a claim or header) is missing. This response indicates which specific value is absent.

```json
{
  "message": "Required context value 'TenantId' is missing."
}
```

--------------------------------

### IPropagationHeadersProvider for Outbound Calls (C#)

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Provides a lazy way to serialize the current typed request context into propagation headers for outbound calls. It includes 'x-correlation-id' if correlation is enabled.

```csharp
using TypedRequestContext.Propagation;

public sealed class DownstreamClient(
    HttpClient http,
    IPropagationHeadersProvider headers)
{
    public async Task<HttpResponseMessage> CallDownstreamAsync(string endpoint, CancellationToken ct)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, endpoint);

        // Add all propagation headers including correlation ID
        foreach (var (key, value) in headers.GetCurrentHeaders())
        {
            request.Headers.TryAddWithoutValidation(key, value);
        }
        // Headers will include: x-user-id, x-tenant-id, x-role, x-correlation-id

        return await http.SendAsync(request, ct);
    }
}

// Usage in endpoint
app.MapGet("/fetch-data", async (
    DownstreamClient client,
    CustomerRequestContext ctx,
    CancellationToken ct) =>
{
    var response = await client.CallDownstreamAsync("/api/data", ct);
    return Results.Ok(await response.Content.ReadAsStringAsync(ct));
}).WithRequestContext<CustomerRequestContext>();
```

--------------------------------

### Register Custom Serializer and Deserializer for TypedRequestContext (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Shows how to register custom serializer and deserializer implementations for typed request context propagation during service registration. This allows for custom handling of context data across requests.

```csharp
builder.Services.AddTypedRequestContext<MyContext>(b =>
    b.UseSerializer<MySerializer>()
     .UseDeserializer<MyDeserializer>());
```

--------------------------------

### Service Registration

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Registers the core framework services for Typed Request Context, including the IRequestContextAccessor and default attribute-based extractor. This should be called once during service configuration.

```APIDOC
## AddTypedRequestContext Service Registration

Registers core framework services including the `IRequestContextAccessor` singleton and the default attribute-based extractor. Call once during service configuration, then register each context type with `AddTypedRequestContext<T>()`.

### Method
```csharp
builder.Services.AddTypedRequestContext();
```

### Parameters
None

### Request Example
None

### Response
None

### Error Handling
None
```

--------------------------------

### Configure Endpoint Context (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Configures specific endpoints or route groups to require a particular typed request context using the `WithRequestContext<T>()` extension method. This allows for fine-grained control over which context is active for different parts of the application. If both a group and an endpoint specify a context, the endpoint's specification takes precedence.

```csharp
using TypedRequestContext;

var api = app.MapGroup("/api")
     .WithRequestContext<CustomerRequestContext>();

api.MapGet("/orders", GetOrders);

// Endpoint override: same app, different context shape
api.MapPost("/internal/sync", SyncData)
    .WithRequestContext<InternalServiceRequestContext>();
```

--------------------------------

### Attaching Typed Request Context to Endpoints

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Shows how to associate a specific typed request context with an endpoint or a group of endpoints. This ensures the context is available for those specific routes.

```csharp
app.MapGet("/", () => "Hello World").WithRequestContext<CustomerRequestContext>();
```

--------------------------------

### Register Custom Extractor for TypedRequestContext (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Demonstrates how to register a custom request context extractor for a specific context type using the TypedRequestContext library. This allows for custom logic in extracting context values from HttpContext.

```csharp
builder.Services.AddTypedRequestContext<MyContext>(b =>
    b.UseExtractor<MyCustomExtractor>());
```

--------------------------------

### IRequestContextAccessor

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Provides ambient access to the current typed request context via `AsyncLocal` storage. This is useful for services that require looser coupling or should not depend directly on a specific context type.

```APIDOC
## IRequestContextAccessor

Provides ambient access to the current typed request context via `AsyncLocal` storage. Use this interface when you need looser coupling or when services shouldn't depend on a specific context type directly.

### Method
Inject `IRequestContextAccessor` into your services or endpoint handlers.

### Parameters
None

### Request Example
```csharp
// Option 1: Inject typed context directly in endpoint handlers
static IResult GetOrders([FromServices] CustomerRequestContext ctx)
{
    return Results.Ok(new { ctx.TenantId, ctx.UserId, ctx.Role });
}

// Option 2: Inject typed context directly in services
public sealed class BillingService(CustomerRequestContext ctx)
{
    public Guid CurrentTenantId => ctx.TenantId;
    public Guid CurrentUserId => ctx.UserId;
}

// Option 3: Use IRequestContextAccessor for looser coupling
public sealed class AuditService(IRequestContextAccessor accessor)
{
    public void LogAction(string action)
    {
        var ctx = accessor.GetRequired<CustomerRequestContext>();
        Console.WriteLine($"[{ctx.TenantId}] User {ctx.UserId} performed: {action}");
    }

    public void LogIfAvailable(string action)
    {
        if (accessor.Current is CustomerRequestContext ctx)
        {
            Console.WriteLine($"[{ctx.TenantId}] {action}");
        }
    }
}
```

### Response
None

### Error Handling
None
```

--------------------------------

### Typed Request Context Registration with Custom Extractor

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Registers a typed request context with an optional custom extractor. This is useful when context values need to be extracted from route parameters, query strings, cookies, or require custom validation logic.

```APIDOC
## AddTypedRequestContext<T> with Custom Extractor

Registers a typed request context with an optional custom extractor for scenarios where values come from route parameters, query strings, cookies, or require custom validation logic.

### Method
```csharp
builder.Services.AddTypedRequestContext<TContext>(b => b.UseExtractor<TExtractor>());
```

### Parameters
#### Path Parameters
- **TContext** (Type) - The type of the request context to register.
- **TExtractor** (Type) - The type of the custom extractor to use.

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
// Custom extractor implementation
public sealed class CustomContextExtractor : IRequestContextExtractor<CustomContext>
{
    public CustomContext Extract(HttpContext httpContext)
    {
        var userIdHeader = httpContext.Request.Headers["x-custom-user"].FirstOrDefault();
        var tenantFromRoute = httpContext.Request.RouteValues["tenant"]?.ToString();

        return new CustomContext
        {
            UserId = Guid.TryParse(userIdHeader, out var id) ? id : Guid.Empty,
            TenantSlug = tenantFromRoute ?? "default"
        };
    }
}

public sealed class CustomContext : ITypedRequestContext
{
    public Guid UserId { get; init; }
    public string TenantSlug { get; init; } = string.Empty;
}

// Registration with custom extractor
builder.Services.AddTypedRequestContext<CustomContext>(b =>
    b.UseExtractor<CustomContextExtractor>());
```

### Response
None

### Error Handling
None
```

--------------------------------

### Consume Context in Deeper Services (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Shows two methods for accessing the typed request context in services beyond endpoint handlers. The first is direct injection of the typed context, which is registered as scoped. The second uses `IRequestContextAccessor` for looser coupling, enabling optional access or use in libraries that shouldn't depend on specific context types.

```csharp
using TypedRequestContext;

// Option 1: Direct Injection
public sealed class BillingService(CustomerRequestContext ctx)
{
    public Guid TenantId => ctx.TenantId;
}

// Option 2: Using IRequestContextAccessor
public sealed class AuditService(IRequestContextAccessor accessor)
{
    public void Write(string message)
    {
        var ctx = accessor.GetRequired<CustomerRequestContext>();
        // Use ctx.TenantId / ctx.UserId...
    }
}
```

--------------------------------

### Add TypedRequestContext Propagation (C#)

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Enables propagation services for serializing typed context to headers for outbound HTTP calls or other transports. Properties must be decorated with `[PropagationKey]` to be included in serialization.

```csharp
using TypedRequestContext;
using TypedRequestContext.Propagation;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTypedRequestContext();
builder.Services.AddTypedRequestContextPropagation(); // Enable propagation
builder.Services.AddCorrelationId();
builder.Services.AddTypedRequestContext<CustomerRequestContext>();

// Context with propagation keys
public sealed class CustomerRequestContext : ITypedRequestContext
{
    [FromClaim("sub"), RequiredContextValue, PropagationKey("x-user-id")]
    public Guid UserId { get; init; }

    [FromClaim("tenant_id"), RequiredContextValue, PropagationKey("x-tenant-id")]
    public Guid TenantId { get; init; }

    [FromClaim("role"), PropagationKey("x-role")]
    public string? Role { get; init; }

    // No PropagationKey - stays local, not serialized
    [FromClaim("email")]
    public string? Email { get; init; }
}
```

--------------------------------

### Register Custom Serializer/Deserializer for TypedRequestContext (C#)

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Shows how to register custom serializer and deserializer implementations for Typed Request Context to override default propagation behavior. This is useful for specialized wire formats or validation logic, such as encryption.

```csharp
using TypedRequestContext;
using TypedRequestContext.Propagation;

// Custom serializer for encrypted propagation
public sealed class EncryptedSerializer : IRequestContextSerializer<SecureContext>
{
    public IReadOnlyDictionary<string, string> Serialize(SecureContext context)
    {
        var payload = JsonSerializer.Serialize(context);
        var encrypted = Encrypt(payload);
        return new Dictionary<string, string>
        {
            ["x-secure-context"] = encrypted
        };
    }
}

// Custom deserializer for encrypted propagation
public sealed class EncryptedDeserializer : IRequestContextDeserializer<SecureContext>
{
    public SecureContext Deserialize(IReadOnlyDictionary<string, string> metadata)
    {
        if (!metadata.TryGetValue("x-secure-context", out var encrypted))
            throw new InvalidOperationException("Missing secure context header");

        var decrypted = Decrypt(encrypted);
        return JsonSerializer.Deserialize<SecureContext>(decrypted)!;
    }
}

// Registration with custom serializer/deserializer
builder.Services.AddTypedRequestContext<SecureContext>(b =>
    b.UseSerializer<EncryptedSerializer>()
     .UseDeserializer<EncryptedDeserializer>());
```

--------------------------------

### WithRequestContext Endpoint Extension

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Declares the required context type for a single endpoint or an entire route group. The endpoint-level declaration takes precedence over group-level declarations in case of conflicts.

```APIDOC
## WithRequestContext Endpoint Extension

Declares the required context type for a single endpoint or an entire route group. When both group and endpoint specify a context, the endpoint-level declaration wins (last-wins semantics).

### Method
```csharp
app.MapGroup("/group").WithRequestContext<TContext>();
endpoint.WithRequestContext<TContext>();
```

### Parameters
#### Path Parameters
- **TContext** (Type) - The type of the request context to apply.

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
// Apply context to entire route group
var customerApi = app.MapGroup("/api/customers")
    .WithRequestContext<CustomerRequestContext>();

customerApi.MapGet("/", GetCustomers);

// Endpoint-level override within a group
var adminApi = app.MapGroup("/api/admin")
    .WithRequestContext<CustomerRequestContext>();

adminApi.MapGet("/users", GetUsers);

// This endpoint uses InternalServiceRequestContext instead of CustomerRequestContext
adminApi.MapPost("/sync", SyncData)
    .WithRequestContext<InternalServiceRequestContext>();

// Single endpoint without group
app.MapGet("/health", () => Results.Ok())
    .WithRequestContext<HealthCheckContext>();
```

### Response
None

### Error Handling
None
```

--------------------------------

### Register TypedRequestContext with Custom Extractor

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Allows registration of a typed request context with a custom extractor. This is useful when context values need to be derived from route parameters, query strings, cookies, or require custom validation logic.

```csharp
using TypedRequestContext;

// Custom extractor implementation
public sealed class CustomContextExtractor : IRequestContextExtractor<CustomContext>
{
    public CustomContext Extract(HttpContext httpContext)
    {
        var userIdHeader = httpContext.Request.Headers["x-custom-user"].FirstOrDefault();
        var tenantFromRoute = httpContext.Request.RouteValues["tenant"]?.ToString();

        return new CustomContext
        {
            UserId = Guid.TryParse(userIdHeader, out var id) ? id : Guid.Empty,
            TenantSlug = tenantFromRoute ?? "default"
        };
    }
}

public sealed class CustomContext : ITypedRequestContext
{
    public Guid UserId { get; init; }
    public string TenantSlug { get; init; } = string.Empty;
}

// Registration with custom extractor
builder.Services.AddTypedRequestContext<CustomContext>(b =>
    b.UseExtractor<CustomContextExtractor>());
```

--------------------------------

### Apply TypedRequestContext to Endpoints with WithRequestContext

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Enables specifying the required context type for individual endpoints or entire route groups. If both a group and an endpoint declare a context, the endpoint's declaration takes precedence (last-wins).

```csharp
using TypedRequestContext;

var app = builder.Build();

// Apply context to entire route group
var customerApi = app.MapGroup("/api/customers")
    .WithRequestContext<CustomerRequestContext>();

customerApi.MapGet("/", GetCustomers);
customerApi.MapGet("/{id}", GetCustomerById);
customerApi.MapPost("/", CreateCustomer);

// Endpoint-level override within a group
var adminApi = app.MapGroup("/api/admin")
    .WithRequestContext<CustomerRequestContext>();

adminApi.MapGet("/users", GetUsers);

// This endpoint uses InternalServiceRequestContext instead of CustomerRequestContext
adminApi.MapPost("/sync", SyncData)
    .WithRequestContext<InternalServiceRequestContext>();

// Single endpoint without group
app.MapGet("/health", () => Results.Ok())
    .WithRequestContext<HealthCheckContext>();

app.Run();
```

--------------------------------

### Extract Request Context from JWT Claims using FromClaimAttribute

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Illustrates using the `FromClaimAttribute` to specify that a property should be populated from a JWT claim. The attribute takes the claim name as a parameter. When combined with `RequiredContextValueAttribute`, it enforces that the claim must be present, otherwise, an HTTP 401 error is returned.

```csharp
using TypedRequestContext;

public sealed class AuthenticatedContext : ITypedRequestContext
{
    // Extract from JWT "sub" claim - required
    [FromClaim("sub"), RequiredContextValue]
    public Guid UserId { get; init; }

    // Extract from JWT "tenant_id" claim - required
    [FromClaim("tenant_id"), RequiredContextValue]
    public Guid TenantId { get; init; }

    // Extract from JWT "role" claim - optional
    [FromClaim("role")]
    public string? Role { get; init; }

    // Extract from JWT "email" claim - optional
    [FromClaim("email")]
    public string? Email { get; init; }
}
```

--------------------------------

### Implement IRequestContextExtractor Interface (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Provides the interface definition for a custom request context extractor. Implementations of this interface are responsible for extracting typed request context data from the HttpContext.

```csharp
using TypedRequestContext;

public interface IRequestContextExtractor<out T>
    where T : class, ITypedRequestContext
{
    T Extract(HttpContext httpContext);
}
```

--------------------------------

### Define Context Types (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Defines strongly-typed request context classes that implement `ITypedRequestContext`. Attributes like `[FromClaim]` and `[FromHeader]` specify the data source, while `[RequiredContextValue]` enforces the presence of a value. These types represent the 'ambient' request context for specific endpoints or route groups.

```csharp
using TypedRequestContext;

public sealed class CustomerRequestContext : ITypedRequestContext
{
    [FromClaim("sub"), RequiredContextValue]
    public Guid UserId { get; init; }

    [FromClaim("tenant_id"), RequiredContextValue]
    public Guid TenantId { get; init; }

    [FromClaim("role")]
    public string? Role { get; init; }

    [FromHeader("x-operation-id")]
    public Guid? OperationId { get; init; }
}

public sealed class InternalServiceRequestContext : ITypedRequestContext
{
    [FromHeader("x-service-name"), RequiredContextValue]
    public string ServiceName { get; init; } = default!;

    [FromHeader("x-operation-id")]
    public Guid? OperationId { get; init; }
}
```

--------------------------------

### Add TypedRequestContext Middleware (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Adds the TypedRequestContext middleware to the ASP.NET Core pipeline. It's crucial to place this middleware after authentication and authorization middleware to ensure that claims are available for context extraction.

```csharp
using TypedRequestContext;

app.UseAuthentication();
app.UseAuthorization();

app.UseTypedRequestContext();
```

--------------------------------

### Consuming Correlation ID

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Demonstrates how to inject and use the `ICorrelationContext` to access the current correlation ID within a service. This is useful for logging and tracing.

```csharp
using TypedRequestContext;

public sealed class LoggingService(ICorrelationContext correlation)
{
    public string CurrentId => correlation.CorrelationId;
}
```

--------------------------------

### Enforce Required Context Values with RequiredContextValueAttribute

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Demonstrates the use of `RequiredContextValueAttribute` to mark properties that must have a value. If a property marked as required is missing its value (either from a JWT claim or an HTTP header), the middleware will short-circuit the request. Missing claim values result in a 401 Unauthorized response, while missing header values result in a 403 Forbidden response, both including a JSON error message.

```csharp
using TypedRequestContext;

public sealed class StrictContext : ITypedRequestContext
{
    // Missing claim returns 401: { "message": "Required context value 'UserId' is missing." }
    [FromClaim("sub"), RequiredContextValue]
    public Guid UserId { get; init; }

    // Missing header returns 403: { "message": "Required context value 'TenantId' is missing." }
    [FromHeader("x-tenant-id"), RequiredContextValue]
    public Guid TenantId { get; init; }

    // Optional - no error if missing, value will be null
    [FromHeader("x-trace-id")]
    public string? TraceId { get; init; }
}
```

--------------------------------

### Access TypedRequestContext via IRequestContextAccessor

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Provides ambient access to the current typed request context using AsyncLocal storage. This is useful for services that require looser coupling or should not directly depend on a specific context type.

```csharp
using TypedRequestContext;
using Microsoft.AspNetCore.Mvc;

// Option 1: Inject typed context directly in endpoint handlers
static IResult GetOrders([FromServices] CustomerRequestContext ctx)
{
    return Results.Ok(new { ctx.TenantId, ctx.UserId, ctx.Role });
}

// Option 2: Inject typed context directly in services
public sealed class BillingService(CustomerRequestContext ctx)
{
    public Guid CurrentTenantId => ctx.TenantId;
    public Guid CurrentUserId => ctx.UserId;
}

// Option 3: Use IRequestContextAccessor for looser coupling
public sealed class AuditService(IRequestContextAccessor accessor)
{
    public void LogAction(string action)
    {
        var ctx = accessor.GetRequired<CustomerRequestContext>();
        Console.WriteLine($"[{ctx.TenantId}] User {ctx.UserId} performed: {action}");
    }

    public void LogIfAvailable(string action)
    {
        if (accessor.Current is CustomerRequestContext ctx)
        {
            Console.WriteLine($"[{ctx.TenantId}] {action}");
        }
    }
}
```

--------------------------------

### Consume Context in Endpoint Handlers (C#)

Source: https://github.com/zio-net/typedrequestcontext/blob/main/README.md

Demonstrates how to access the typed request context within an endpoint handler using dependency injection. The context type is registered as scoped when `AddTypedRequestContext<T>()` is called, making it readily available for injection.

```csharp
using Microsoft.AspNetCore.Mvc;

static IResult GetOrders([FromServices] CustomerRequestContext ctx)
{
    return Results.Ok(new { ctx.TenantId, ctx.UserId, ctx.Role });
}
```

--------------------------------

### Add Correlation ID to TypedRequestContext (C#)

Source: https://context7.com/zio-net/typedrequestcontext/llms.txt

Registers the correlation ID module to read 'x-correlation-id' from requests or fallback to Activity.Current.TraceId, echoing it in response headers. It also enables consuming the correlation ID within services and logging.

```csharp
using TypedRequestContext;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTypedRequestContext();
builder.Services.AddCorrelationId(); // Enable correlation ID
builder.Services.AddTypedRequestContext<CustomerRequestContext>();

var app = builder.Build();

app.UseTypedRequestContext();

// Consume correlation ID in services
app.MapGet("/orders", (ICorrelationContext correlation, CustomerRequestContext ctx) =>
{
    Console.WriteLine($"Processing request {correlation.CorrelationId} for tenant {ctx.TenantId}");
    return Results.Ok(new { correlationId = correlation.CorrelationId });
}).WithRequestContext<CustomerRequestContext>();

// Use in logging service
public sealed class LoggingService(ICorrelationContext correlation)
{
    public void Log(string message)
    {
        Console.WriteLine($"[{correlation.CorrelationId}] {message}");
    }
}
```
Tokens:
Raw