> For the complete documentation index, see [llms.txt](https://docs.flexbase.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flexbase.in/solution-structure/getting-started/application/default-bus-configuration.md). # 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: ```xml ``` ## 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: ```csharp public static EndpointConfiguration GetEndpoint(IConfiguration configuration, IHostEnvironment env, List 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` ```csharp public class LearningNsbConfiguration : NsbBaseConfiguration { public LearningNsbConfiguration(string endpointName, IEnumerable routes, IConfiguration configuration, IHostEnvironment env, string errorQueueName = "error") : base(endpointName, configuration, env, errorQueueName) { // Configure persistence var persistence = this.UsePersistence(); // Configure transport var transport = this.UseTransport(); // 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` ```csharp public class RabbitMqNsbConfiguration : NsbBaseConfiguration { public RabbitMqNsbConfiguration(string endpointName, IEnumerable 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(); persistence.SqlDialect(); persistence.ConnectionBuilder(() => new SqlConnection(sqlPersistenceConnectionString)); // Configure transport var transport = this.UseTransport(); 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:** ```json { "FlexBase": { "SqlPersistenceConnectionString": "Data Source=YourServer;Initial Catalog=YourPersistenceDb;...", "RabbitMqConnectionString": "amqp://YourUser:YourPassword@YourRabbitMqHost:YourPort" } } ``` ### **3. SQL Server Transport** **File**: `SqlNsbConfiguration.cs` ```csharp public class SqlNsbConfiguration : NsbBaseConfiguration { public SqlNsbConfiguration(string endpointName, IEnumerable 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(); persistence.SqlDialect(); 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:** ```json { "FlexBase": { "SqlPersistenceConnectionString": "Data Source=YourServer;Initial Catalog=YourPersistenceDb;...", "SqlTransportConnectionString": "Data Source=YourServer;Initial Catalog=YourTransportDb;..." } } ``` ### **4. Azure Service Bus Transport** **File**: `AzureServiceNsbConfiguration.cs` ```csharp public class AzureServiceNsbConfiguration : NsbBaseConfiguration { public AzureServiceNsbConfiguration(string endpointName, IEnumerable 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(); persistence.SqlDialect(); 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:** ```json { "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` ```csharp public class AzureStorageQueueNsbConfiguration : NsbBaseConfiguration { public AzureStorageQueueNsbConfiguration(string endpointName, IEnumerable 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(); 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:** ```json { "FlexBase": { "AzureStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=YourAccount;AccountKey=YourKey;EndpointSuffix=core.windows.net" } } ``` ### **6. Amazon SQS Transport** **File**: `AmazonSQSNsbConfiguration.cs` ```csharp public class AmazonSQSNsbConfiguration : NsbBaseConfiguration { public AmazonSQSNsbConfiguration(string endpointName, IEnumerable 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(); persistence.SqlDialect(); 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:** ```json { "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: ```csharp public static void AddFlexBaseBusServices(this IServiceCollection services) { services.AddSingleton(); services.AddTransient(); } ``` **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** ```csharp // 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** ```json { "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** ```csharp Guard.AgainstNullAndEmpty("SqlPersistenceConnectionString for connection string cannot be empty", configuration.GetSection("FlexBase")["SqlPersistenceConnectionString"]); ``` ### **4. Routing Configuration** ```csharp var routing = transport.Routing(); foreach (var route in routes) { routing.RouteToEndpoint(route.Assembly, route.Destination); } ``` ## Custom Configuration Template ### **MyCustomNsbConfiguration.cs** ```csharp 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!** 🚀