Configuration & AOT

The HTTP extension uses Microsoft.Extensions.Configuration for base URI resolution, debug mode, and timeouts. It also supports AOT scenarios through JSON source generation.

Base URI Configuration

Every HTTP request needs a base URI. The route defined in the [Http] attribute is appended to this base URI. Configure it in your appsettings.json or any other IConfiguration provider.

{
    "Mediator": {
        "Http": {
            "MyApp.Contracts.GetUserRequest": "https://users-api.myapp.com",
            "MyApp.Contracts.*": "https://api.myapp.com",
            "*": "https://api.myapp.com"
        }
    }
}

Note

The configuration value is only the base URI. The route on the [Http] attribute is appended to it.

Resolution Order

The HTTP extension resolves the base URI using the following priority (first match wins):

1. Exact contract name - Full type name (namespace + type), e.g. MyApp.Contracts.GetUserRequest
2. Namespace wildcard - Namespace with wildcard, e.g. MyApp.Contracts.*
3. Global wildcard - Matches everything, e.g. *

This allows you to point different contracts or namespaces at different API servers while having a default fallback.

Multiple API Servers

{
    "Mediator": {
        "Http": {
            "MyApp.Users.*": "https://users-api.myapp.com",
            "MyApp.Products.*": "https://products-api.myapp.com",
            "*": "https://api.myapp.com"
        }
    }
}

Debug Mode

When enabled, the HTTP extension logs the full request and response to the console. This is useful during development.

{
    "Mediator": {
        "Http": {
            "*": "https://api.myapp.com",
            "Debug": true
        }
    }
}

Timeout

Configure the default HTTP request timeout in seconds. Defaults to 20 seconds if not set.

{
    "Mediator": {
        "Http": {
            "*": "https://api.myapp.com",
            "Timeout": 30
        }
    }
}

Full Configuration Reference

{
    "Mediator": {
        "Http": {
            "MyApp.Contracts.SlowRequest": "https://slow-api.myapp.com",
            "MyApp.Contracts.*": "https://api.myapp.com",
            "*": "https://api.myapp.com",
            "Debug": true,
            "Timeout": 30
        }
    }
}

AOT & JSON Source Generation

In AOT (Ahead-of-Time) compilation scenarios, System.Text.Json reflection-based serialization is not available. The HTTP extension includes a JSON source generator to handle this.

Why It’s Not Enabled by Default

1. Every API is different and it is difficult to source-generate serialization perfectly
2. If your API surface is large, generating all HTTP contracts plus JSON converters can take a few seconds during build
3. You can mark your own types with [SourceGenerateJsonConverterAttribute] or implement your own ISerializerService

Enabling JSON Source Generation

For OpenAPI-generated contracts, set GenerateJsonConverters to true in your MSBuild item:

<ItemGroup>
    <MediatorHttp Include="OpenApiDoc.json"
                  Namespace="My.Namespace"
                  GenerateJsonConverters="true"
                  Visible="false" />
</ItemGroup>

All HTTP contract types from that OpenAPI document will have source-generated JSON converters.

Manual JSON Source Generation

For hand-written contracts, use the [SourceGenerateJsonConverter] attribute on your types:

[SourceGenerateJsonConverter]
public class MyResponse
{
    public string Name { get; set; }
    public int Count { get; set; }
}

Custom Serialization

If the built-in serialization doesn’t fit your needs, you can implement your own ISerializerService and register it with Mediator:

public class CustomSerializerService : ISerializerService
{
    // Implement serialization/deserialization as needed
}

services.AddSingleton<ISerializerService, CustomSerializerService>();