Default Bus Configuration

Overview

This document explains the NServiceBus configuration system in FlexBase applications, using the EBusiness sample as a reference. The bus configuration provides a flexible, environment-aware messaging system that supports multiple transport and persistence options.

Architecture Overview

The NServiceBus configuration in FlexBase follows a strategy pattern where different configurations are selected based on the environment and requirements. This allows for seamless transitions between development, staging, and production environments.

Configuration Flow

Environment Detection → Configuration Selection → Transport Setup → Persistence Setup → Routing Configuration

Project Structure

EBusiness.Nsb Project

The EBusiness.Nsb project contains all NServiceBus configuration implementations:

EBusiness.Nsb/
├── EBusiness.Nsb.csproj                    # Project file with NServiceBus packages
├── LearningNsbConfiguration.cs             # Development/Testing transport
├── RabbitMqNsbConfiguration.cs             # Production RabbitMQ transport
├── SqlNsbConfiguration.cs                  # SQL Server transport
├── AzureServiceNsbConfiguration.cs         # Azure Service Bus transport
├── AzureStorageQueueNsbConfiguration.cs    # Azure Storage Queue transport
├── AmazonSQSNsbConfiguration.cs            # Amazon SQS transport
└── MyCustomNsbConfiguration.cs             # Template for custom configurations

Dependencies

The project references multiple FlexBase NServiceBus packages:

<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb" Version="9.2.0" />
<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb.Azure.Storage" Version="9.2.0" />
<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb.Learning" Version="9.2.0" />
<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb.OnPremises.Rabbit" Version="9.2.0" />
<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb.Amazon.SQS" Version="9.2.0" />
<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb.Azure.ServiceBus" Version="9.2.0" />
<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb.SqlTransport" Version="9.2.0" />
<PackageReference Include="Sumeru.Flex.ServiceBus.Nsb.SqlPersistence" Version="9.2.0" />

Configuration Selection Logic

BusEndPointConfig.cs - Environment-Based Selection

The BusEndPointConfig.cs file contains the logic for selecting the appropriate NServiceBus configuration based on the environment:

public static EndpointConfiguration GetEndpoint(IConfiguration configuration, IHostEnvironment env, List<BusRouteConfig> routes)
{
    string endPointName = configuration.GetSection("EndPoint")["Name"];
    
    NsbDefaultEndpointConfiguration endPointConfig;
    
    if (env.IsDevelopment())
    {
        endPointConfig = new LearningNsbConfiguration(endPointName, routes, configuration, env);
    }
    else if (env.IsStaging())
    {
        endPointConfig = new RabbitMqNsbConfiguration(endPointName, routes, configuration, env);
    }
    else if (env.IsProduction())
    {
        endPointConfig = new RabbitMqNsbConfiguration(endPointName, routes, configuration, env);
    }
    else
    {
        endPointConfig = new RabbitMqNsbConfiguration(endPointName, routes, configuration, env);
    }
    
    return endPointConfig;
}

Environment Mapping

Environment
Configuration
Transport
Persistence
Use Case

Development

LearningNsbConfiguration

Learning Transport

Learning Persistence

Local development, testing

Staging

RabbitMqNsbConfiguration

RabbitMQ

SQL Server

Pre-production testing

Production

RabbitMqNsbConfiguration

RabbitMQ

SQL Server

Live production environment

Default

RabbitMqNsbConfiguration

RabbitMQ

SQL Server

Fallback configuration

Transport Configurations

1. Learning Transport (Development)

File: LearningNsbConfiguration.cs

public class LearningNsbConfiguration : NsbBaseConfiguration
{
    public LearningNsbConfiguration(string endpointName, IEnumerable<BusRouteConfig> routes, IConfiguration configuration, IHostEnvironment env, string errorQueueName = "error") 
        : base(endpointName, configuration, env, errorQueueName)
    {
        // Configure persistence
        var persistence = this.UsePersistence<LearningPersistence>();
        
        // Configure transport
        var transport = this.UseTransport<LearningTransport>();
        
        // Configure routing
        var routing = transport.Routing();
        foreach (var route in routes)
        {
            routing.RouteToEndpoint(route.Assembly, route.Destination);
        }
    }
}

Characteristics:

  • File-Based: Stores messages in local file system

  • No Dependencies: No external infrastructure required

  • Development Only: Not suitable for production

  • Auto-Cleanup: Automatically manages message storage

Configuration Requirements:

  • No connection strings required

  • Creates .learningtransport directory automatically

  • Perfect for local development and testing

2. RabbitMQ Transport (Production)

File: RabbitMqNsbConfiguration.cs

public class RabbitMqNsbConfiguration : NsbBaseConfiguration
{
    public RabbitMqNsbConfiguration(string endpointName, IEnumerable<BusRouteConfig> routes, IConfiguration configuration, IHostEnvironment env, string errorQueueName = "error") 
        : base(endPointName, configuration, env, errorQueueName)
    {
        string sqlPersistenceConnectionString = configuration.GetSection("FlexBase")["SqlPersistenceConnectionString"];
        string rabbitMqConnectionString = configuration.GetSection("FlexBase")["RabbitMqConnectionString"];
        
        // Configure persistence
        var persistence = this.UsePersistence<SqlPersistence>();
        persistence.SqlDialect<SqlDialect.MsSqlServer>();
        persistence.ConnectionBuilder(() => new SqlConnection(sqlPersistenceConnectionString));
        
        // Configure transport
        var transport = this.UseTransport<RabbitMQTransport>();
        transport.ConnectionString(rabbitMqConnectionString);
        transport.UseConventionalRoutingTopology(QueueType.Classic);
        
        // Configure routing
        var routing = transport.Routing();
        foreach (var route in routes)
        {
            routing.RouteToEndpoint(route.Assembly, route.Destination);
        }
    }
}

Characteristics:

  • High Performance: Excellent for high-throughput scenarios

  • Reliable: Message durability and delivery guarantees

  • Scalable: Horizontal scaling capabilities

  • Production Ready: Suitable for enterprise environments

Configuration Requirements:

{
  "FlexBase": {
    "SqlPersistenceConnectionString": "Data Source=YourServer;Initial Catalog=YourPersistenceDb;...",
    "RabbitMqConnectionString": "amqp://YourUser:YourPassword@YourRabbitMqHost:YourPort"
  }
}

3. SQL Server Transport

File: SqlNsbConfiguration.cs

public class SqlNsbConfiguration : NsbBaseConfiguration
{
    public SqlNsbConfiguration(string endpointName, IEnumerable<BusRouteConfig> routes, IConfiguration configuration, IHostEnvironment env, string errorQueueName = "error") 
        : base(endPointName, configuration, env, errorQueueName)
    {
        string sqlPersistenceConnectionString = configuration.GetSection("FlexBase")["SqlPersistenceConnectionString"];
        string sqlTransportConnectionString = configuration.GetSection("FlexBase")["SqlTransportConnectionString"];
        
        // Configure persistence
        var persistence = this.UsePersistence<SqlPersistence>();
        persistence.SqlDialect<SqlDialect.MsSqlServer>();
        persistence.ConnectionBuilder(() => new SqlConnection(sqlPersistenceConnectionString));
        
        // Configure transport
        var transport = new SqlServerTransport(sqlTransportConnectionString);
        this.UseTransport(transport);
        
        // Configure routing
        var routing = this.UseTransport(transport);
        foreach (var route in routes)
        {
            routing.RouteToEndpoint(route.Assembly, route.Destination);
        }
    }
}

Characteristics:

  • Database-Based: Uses SQL Server for message transport

  • Transactional: Leverages SQL Server transactions

  • Familiar: Easy to monitor and debug

  • Reliable: ACID compliance for message delivery

Configuration Requirements:

{
  "FlexBase": {
    "SqlPersistenceConnectionString": "Data Source=YourServer;Initial Catalog=YourPersistenceDb;...",
    "SqlTransportConnectionString": "Data Source=YourServer;Initial Catalog=YourTransportDb;..."
  }
}

4. Azure Service Bus Transport

File: AzureServiceNsbConfiguration.cs

public class AzureServiceNsbConfiguration : NsbBaseConfiguration
{
    public AzureServiceNsbConfiguration(string endpointName, IEnumerable<BusRouteConfig> routes, IConfiguration configuration, IHostEnvironment env, string errorQueueName = "error") 
        : base(endPointName, configuration, env, errorQueueName)
    {
        string sqlPersistenceConnectionString = configuration.GetSection("FlexBase")["SqlPersistenceConnectionString"];
        string azureServiceBusConnectionString = configuration.GetSection("FlexBase")["AzureServiceBusConnectionString"];
        
        // Configure persistence
        var persistence = this.UsePersistence<SqlPersistence>();
        persistence.SqlDialect<SqlDialect.MsSqlServer>();
        persistence.ConnectionBuilder(() => new SqlConnection(sqlPersistenceConnectionString));
        
        // Configure transport
        var transport = new AzureServiceBusTransport(azureServiceBusConnectionString);
        this.UseTransport(transport);
        
        // Configure routing
        var routing = this.UseTransport(transport);
        foreach (var route in routes)
        {
            routing.RouteToEndpoint(route.Assembly, route.Destination);
        }
    }
}

Characteristics:

  • Cloud-Native: Fully managed Azure service

  • Scalable: Auto-scaling capabilities

  • Reliable: 99.9% SLA guarantee

  • Integrated: Works seamlessly with other Azure services

Configuration Requirements:

{
  "FlexBase": {
    "SqlPersistenceConnectionString": "Data Source=YourServer;Initial Catalog=YourPersistenceDb;...",
    "AzureServiceBusConnectionString": "Endpoint=sb://YourNamespace.servicebus.windows.net/;SharedAccessKeyName=YourKeyName;SharedAccessKey=YourKey"
  }
}

5. Azure Storage Queue Transport

File: AzureStorageQueueNsbConfiguration.cs

public class AzureStorageQueueNsbConfiguration : NsbBaseConfiguration
{
    public AzureStorageQueueNsbConfiguration(string endpointName, IEnumerable<BusRouteConfig> routes, IConfiguration configuration, IHostEnvironment env, string errorQueueName = "error") 
        : base(endPointName, configuration, env, errorQueueName)
    {
        string azureConnectionString = configuration.GetSection("FlexBase")["AzureStorageConnectionString"];
        
        // Configure persistence
        var persistence = this.UsePersistence<AzureTablePersistence>();
        persistence.ConnectionString(azureConnectionString);
        
        // Configure transport
        var queueServiceClient = new QueueServiceClient(azureConnectionString, new QueueClientOptions());
        var blobServiceClient = new BlobServiceClient(azureConnectionString, new BlobClientOptions());
        var tableServiceClient = new TableServiceClient(azureConnectionString, new TableClientOptions());
        
        var transport = new AzureStorageQueueTransport(queueServiceClient, blobServiceClient, tableServiceClient)
        {
            ReceiverBatchSize = 20,
            MaximumWaitTimeWhenIdle = TimeSpan.FromSeconds(1),
            DegreeOfReceiveParallelism = 16,
            PeekInterval = TimeSpan.FromMilliseconds(100),
            MessageInvisibleTime = TimeSpan.FromSeconds(30)
        };
        
        // Configure routing
        var routing = this.UseTransport(transport);
        foreach (var route in routes)
        {
            routing.RouteToEndpoint(route.Assembly, route.Destination);
            routing.RegisterPublisher(route.Assembly, route.Destination);
        }
    }
}

Characteristics:

  • Cost-Effective: Lower cost than Service Bus

  • Simple: Easy to set up and manage

  • Scalable: Handles high message volumes

  • Azure-Native: Integrated with Azure ecosystem

Configuration Requirements:

{
  "FlexBase": {
    "AzureStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=YourAccount;AccountKey=YourKey;EndpointSuffix=core.windows.net"
  }
}

6. Amazon SQS Transport

File: AmazonSQSNsbConfiguration.cs

public class AmazonSQSNsbConfiguration : NsbBaseConfiguration
{
    public AmazonSQSNsbConfiguration(string endpointName, IEnumerable<BusRouteConfig> routes, IConfiguration configuration, IHostEnvironment env, string errorQueueName = "error") 
        : base(endPointName, configuration, env, errorQueueName)
    {
        string sqlPersistenceConnectionString = configuration.GetSection("FlexBase")["SqlPersistenceConnectionString"];
        string s3BucketName = configuration.GetSection("FlexBase")["AmazonSQSTransportBucketName"];
        string s3KeyPrefix = configuration.GetSection("FlexBase")["AmazonSQSTransportKeyPrefix"];
        
        // Configure persistence
        var persistence = this.UsePersistence<SqlPersistence>();
        persistence.SqlDialect<SqlDialect.MsSqlServer>();
        persistence.ConnectionBuilder(() => new SqlConnection(sqlPersistenceConnectionString));
        
        // Configure transport
        var transport = new SqsTransport
        {
            S3 = new S3Settings(
                bucketForLargeMessages: s3BucketName,
                keyPrefix: s3KeyPrefix,
                s3Client: new AmazonS3Client())
        };
        
        // Configure routing
        var routing = this.UseTransport(transport);
        foreach (var route in routes)
        {
            routing.RouteToEndpoint(route.Assembly, route.Destination);
        }
    }
}

Characteristics:

  • AWS-Native: Fully integrated with AWS services

  • Scalable: Auto-scaling message queues

  • Reliable: High availability and durability

  • Cost-Effective: Pay-per-use pricing model

Configuration Requirements:

{
  "FlexBase": {
    "SqlPersistenceConnectionString": "Data Source=YourServer;Initial Catalog=YourPersistenceDb;...",
    "AmazonSQSTransportBucketName": "YourS3BucketName",
    "AmazonSQSTransportKeyPrefix": "YourKeyPrefix"
  }
}

Service Registration

BusEndPointConfig.cs - Service Registration

The BusEndPointConfig.cs file also handles service registration for dependency injection:

public static void AddFlexBaseBusServices(this IServiceCollection services)
{
    services.AddSingleton<IFlexServiceBusBridge, NsbServiceBusBridge>();
    services.AddTransient<FlexBusSendOptions, NsbSendOptions>();
}

What This Does:

  • Service Bus Bridge: Registers the NServiceBus bridge as a singleton

  • Send Options: Registers send options for message publishing

  • Dependency Injection: Makes bus services available throughout the application

Configuration Best Practices

1. Environment-Specific Configuration

// Development
if (env.IsDevelopment())
{
    endPointConfig = new LearningNsbConfiguration(endPointName, routes, configuration, env);
}

// Staging
else if (env.IsStaging())
{
    endPointConfig = new RabbitMqNsbConfiguration(endPointName, routes, configuration, env);
}

// Production
else if (env.IsProduction())
{
    endPointConfig = new RabbitMqNsbConfiguration(endPointName, routes, configuration, env);
}

2. Connection String Management

{
  "FlexBase": {
    "SqlPersistenceConnectionString": "Data Source=YourServer;Initial Catalog=YourPersistenceDb;...",
    "RabbitMqConnectionString": "amqp://YourUser:YourPassword@YourRabbitMqHost:YourPort",
    "AzureServiceBusConnectionString": "Endpoint=sb://YourNamespace.servicebus.windows.net/;...",
    "AzureStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=YourAccount;...",
    "AmazonSQSTransportBucketName": "YourS3BucketName",
    "AmazonSQSTransportKeyPrefix": "YourKeyPrefix"
  }
}

3. Error Handling

Guard.AgainstNullAndEmpty("SqlPersistenceConnectionString for connection string cannot be empty", 
    configuration.GetSection("FlexBase")["SqlPersistenceConnectionString"]);

4. Routing Configuration

var routing = transport.Routing();
foreach (var route in routes)
{
    routing.RouteToEndpoint(route.Assembly, route.Destination);
}

Custom Configuration Template

MyCustomNsbConfiguration.cs

public class MyCustomNsbConfiguration : EndpointConfiguration
{
    public MyCustomNsbConfiguration(string endpointName, string errorQueueName = "error") : base(endpointName)
    {
        this.SendFailedMessagesTo(errorQueueName);
        
        // Add all other NSB Configuration here
        // - Transport configuration
        // - Persistence configuration
        // - Routing configuration
        // - Serialization settings
        // - Error handling
        // - Performance tuning
    }
}

Use Cases:

  • Custom Requirements: Specific business needs not covered by standard configurations

  • Performance Tuning: Optimized settings for specific scenarios

  • Integration: Custom transport or persistence providers

  • Testing: Specialized configurations for testing scenarios

Performance Considerations

Transport Selection Guidelines

Scenario
Recommended Transport
Reason

Development

Learning Transport

No external dependencies, easy setup

Small Scale

SQL Server Transport

Familiar, easy to monitor

High Throughput

RabbitMQ Transport

Excellent performance, reliable

Cloud-Native

Azure Service Bus

Fully managed, integrated

Cost-Sensitive

Azure Storage Queue

Lower cost, good performance

AWS Environment

Amazon SQS

Native AWS integration

Persistence Selection Guidelines

Scenario
Recommended Persistence
Reason

Development

Learning Persistence

No external dependencies

Production

SQL Server Persistence

Reliable, familiar, ACID compliance

Azure

Azure Table Persistence

Native Azure integration

Troubleshooting

Common Issues

  1. Connection String Errors

    • Verify connection strings in configuration

    • Check network connectivity

    • Validate credentials

  2. Transport Failures

    • Ensure transport service is running

    • Check firewall settings

    • Verify endpoint configuration

  3. Routing Issues

    • Verify route configuration

    • Check assembly references

    • Validate destination endpoints

  4. Performance Problems

    • Monitor message throughput

    • Check resource utilization

    • Consider transport scaling

Debugging Tips

  1. Enable Logging: Use structured logging to track message flow

  2. Monitor Queues: Check queue depths and processing rates

  3. Health Checks: Implement health checks for transport and persistence

  4. Metrics: Use application insights or similar tools for monitoring

Key Benefits

  • Environment Awareness: Automatic configuration based on environment

  • Multiple Transports: Support for various messaging technologies

  • Flexible Persistence: Multiple persistence options

  • Easy Configuration: Simple configuration management

  • Production Ready: Battle-tested configurations

  • Scalable: Supports high-throughput scenarios

  • Reliable: Built-in error handling and retry mechanisms

  • Maintainable: Clear separation of concerns

  • Testable: Easy to test with different configurations

This NServiceBus configuration system provides a robust, scalable, and maintainable messaging infrastructure that adapts to different environments and requirements! 🚀

PreviousCommon ConfigurationsNextEFCore Configuration

Last updated