Skip to main content

Configuration: Environments & Transports

Configure Dispatch for different deployment environments, transport brokers, health monitoring, and observability.

Before You Start​

Configuration from appsettings.json​

Bind configuration from your settings file. DispatchOptions supports nested options for cross-cutting concerns:

appsettings.json
{
  "Dispatch": {
    "DefaultTimeout": "00:00:30",
    "EnableMetrics": true,
    "Security": {
      "EnableEncryption": false,
      "EnableValidation": true
    },
    "Observability": {
      "Enabled": true,
      "EnableTracing": true,
      "EnableMetrics": true
    },
    "Resilience": {
      "DefaultRetryCount": 3,
      "EnableCircuitBreaker": false
    },
    "Caching": {
      "Enabled": false,
      "DefaultExpiration": "00:05:00"
    }
  }
}
// Program.cs
builder.Services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly);
});

// Bind all Dispatch options from appsettings (including nested options)
builder.Services.Configure<DispatchOptions>(
    builder.Configuration.GetSection("Dispatch"));

Transport Configuration​

Configure transports through the AddDispatch() builder using Use{Transport}() methods:

Single Transport​

builder.Services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly);

    // Configure transport through the builder (recommended)
    dispatch.UseRabbitMQ(rmq => rmq.HostName("localhost"));
});

All five transports follow the same pattern:

builder.Services.AddDispatch(dispatch =>
{
    dispatch.UseKafka(kafka => kafka.BootstrapServers("localhost:9092"));
    dispatch.UseAzureServiceBus(asb => asb.ConnectionString("..."));
    dispatch.UseAwsSqs(sqs => sqs.Region("us-east-1"));
    dispatch.UseGooglePubSub(pubsub => pubsub.ProjectId("my-project"));
    dispatch.UseRabbitMQ(rmq => rmq.HostName("localhost"));
});

:::tip Standalone methods still work You can also register transports directly on IServiceCollection if preferred:

builder.Services.AddKafkaTransport(options => { /* ... */ });

The builder Use{Transport}() methods are thin wrappers that delegate to these standalone methods. :::

See Transports for transport-specific setup guides.

Named Transports​

Register multiple instances of the same transport with different names:

builder.Services.AddDispatch(dispatch =>
{
    dispatch.UseKafka(kafka => kafka.BootstrapServers("localhost:9092"));
    dispatch.UseKafka("analytics", kafka => kafka.BootstrapServers("analytics:9092"));
});

Multi-Transport Routing​

builder.Services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly);

    // Transports
    dispatch.UseKafka(kafka => kafka.BootstrapServers("localhost:9092"));
    dispatch.UseRabbitMQ(rmq => rmq.HostName("localhost"));

    // Configure routing
    dispatch.UseRouting(routing =>
    {
        routing.Transport
            .Route<OrderCreatedEvent>().To("kafka")
            .Route<PaymentProcessedEvent>().To("rabbitmq")
            .Default("rabbitmq");
    });
});

Environment-Specific Configuration​

Development vs Production​

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly);

    if (builder.Environment.IsDevelopment())
    {
        // Development: add debug middleware
        dispatch.UseMiddleware<DebugMiddleware>();
    }
});

// Environment-specific transport
if (builder.Environment.IsDevelopment())
{
    // In development: messages dispatch in-process (no broker needed)
    // No transport registration means in-process dispatch by default
}
else
{
    builder.Services.AddKafkaTransport(options =>
    {
        options.BootstrapServers = builder.Configuration["Kafka:Servers"];
    });
}

Using IConfiguration​

builder.Services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly);
});

// Bind from configuration
builder.Services.AddOptions<DispatchOptions>()
    .Bind(builder.Configuration.GetSection("Dispatch"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

Health Checks​

Add health checks for Dispatch components:

builder.Services.AddHealthChecks()
    .AddTransportHealthChecks();

var app = builder.Build();
app.MapHealthChecks("/health");

Observability Configuration​

OpenTelemetry Integration​

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddSource("Excalibur.Dispatch");
        tracing.AddOtlpExporter();
    })
    .WithMetrics(metrics =>
    {
        metrics.AddDispatchMetrics();
        metrics.AddOtlpExporter();
    });

Logging Configuration​

builder.Logging.AddConfiguration(builder.Configuration.GetSection("Logging"));

// In appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Excalibur.Dispatch": "Debug",
      "Excalibur.Dispatch.Pipeline": "Trace"
    }
  }
}

See Also​