Momentum .NET

Appearance

Class ServiceBusOptions ​

Namespace: Momentum.ServiceDefaults.Messaging
Assembly: Momentum.ServiceDefaults.dll

Configuration options for the Wolverine service bus and messaging infrastructure.

csharp
public class ServiceBusOptions

Inheritance ​

object ← ServiceBusOptions

Inherited Members ​

object.GetType(), object.MemberwiseClone(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Examples ​

Basic Configuration in appsettings.json ​

json
{
    "ServiceBus": {
        "Domain": "ECommerce",
        "PublicServiceName": "order-service",
        "CloudEvents": {
            "Source": "https://api.mystore.com/orders",
            "DefaultType": "com.mystore.orders"
        }
    },
    "ConnectionStrings": {
        // Standalone fallback only: used when no application NpgsqlDataSource is
        // registered in DI. A generated service reuses its application data source
        // (e.g. AppDomainDb) automatically and omits this entry.
        "ServiceBus": "Host=postgres;Database=order_messaging;Username=app;Password=secret"
    }
}

Multi-Environment Configuration ​

json
// appsettings.Local.json (excluded from Docker — local overrides)
{
  "ServiceBus": {
    "Domain": "ECommerce",
    "PublicServiceName": "order-service-dev"
  }
}

// appsettings.Production.json
{
  "ServiceBus": {
    "Domain": "ECommerce",
    "PublicServiceName": "order-service",
    "CloudEvents": {
      "Source": "https://api.production.mystore.com/orders",
      "Subject": "orders"
    }
  }
}

Service URN Generation Examples ​

csharp
// Domain: "ECommerce", PublicServiceName: "order-service"
// Generated URN: "/e_commerce/order-service"

// Domain: "CustomerManagement", PublicServiceName: "customer-api"
// Generated URN: "/customer_management/customer-api"

CloudEvents Configuration ​

json
{
    "ServiceBus": {
        "CloudEvents": {
            "Source": "https://api.mystore.com/orders",
            "DefaultType": "com.mystore.orders",
            "Subject": "orders",
            "DataContentType": "application/json"
        }
    }
}

Generated CloudEvent Example ​

json
{
    "specversion": "1.0",
    "type": "com.mystore.orders.order-created",
    "source": "https://api.mystore.com/orders",
    "subject": "orders/12345",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "time": "2024-01-15T10:30:00Z",
    "datacontenttype": "application/json",
    "data": {
        "orderId": "12345",
        "customerId": "67890",
        "totalAmount": 99.99
    }
}

Service Name Conversion Examples ​

csharp
GetServiceName("ECommerce.OrderService") // Returns: "ecommerce-orderservice"
GetServiceName("Customer.API") // Returns: "customer-api"
GetServiceName("payment-processor") // Returns: "payment-processor"

Automatic Configuration Example ​

csharp
// Given application name: "ECommerce.OrderService"
// And configuration:
{
  "ServiceBus": {
    "Domain": "ECommerce"
    // PublicServiceName not specified
  }
}

// After post-configuration:
// PublicServiceName = "ecommerce-orderservice" (derived from app name)
// ServiceUrn = "/e_commerce/ecommerce-orderservice" (generated URN)

Missing Data Source Scenario ​

csharp
// Standalone use with neither an application NpgsqlDataSource registered in DI
// nor a ServiceBus connection string configured throws at startup:
// "No NpgsqlDataSource is registered and the DB string 'ServiceBus' is not set."

// A generated service always registers an application NpgsqlDataSource, so message
// persistence reuses it automatically and this path is never hit. For standalone
// library use, provide ConnectionStrings:ServiceBus as the fallback.

Remarks ​

ServiceBusOptions Detailed Configuration Guide ​

Overview ​

This class configures the core messaging infrastructure used for CQRS patterns, event-driven architecture, and cross-service communication. It integrates with PostgreSQL for message persistence and supports CloudEvents for standardized messaging.

The configuration automatically derives service names and URNs from the application assembly name, following domain-oriented naming patterns where the assembly name reflects the business domain and bounded context.

Domain Property ​

The business domain name. Defaults to the main namespace of the entry assembly. For example, if the assembly is "ECommerce.OrderService", the domain defaults to "ECommerce".

This property is used to group related services and organize message routing. It should represent the business domain rather than technical concerns.

PublicServiceName Property ​

The service name in kebab-case format. If not explicitly set, defaults to the application name converted to lowercase with dots replaced by hyphens.

This name is used for:

  • Message routing and topic naming
  • Service discovery and registration
  • CloudEvents source identification
  • Database schema naming for message persistence

The name should be stable across deployments and follow DNS naming conventions (lowercase, hyphens, no underscores).

Examples of good service names: ​

  • order-service
  • payment-processor
  • inventory-manager
  • customer-portal

ServiceUrn Property ​

A relative URI in the format "/{domain_snake_case}/{service_name}" that uniquely identifies this service within the messaging infrastructure.

This URN is automatically generated during configuration and used for:

  • Message routing and subscription patterns
  • Service identification in distributed tracing
  • Dead letter queue naming
  • Health check endpoint registration

The URN format ensures uniqueness across different domains and services while maintaining readability and following URI conventions.

Example URNs generated from configuration: ​

// Domain: "ECommerce", PublicServiceName: "order-service"
// Generated URN: "/e_commerce/order-service"

// Domain: "CustomerManagement", PublicServiceName: "customer-api"
// Generated URN: "/customer_management/customer-api"

CloudEvents Configuration ​

CloudEvents provides a standardized format for event data, enabling interoperability between different services and platforms. This configuration controls how events are formatted when published to external systems.

Key CloudEvents properties configured: ​

  • Source: URI identifying the event producer
  • Type: Event type for categorization and routing
  • Subject: Subject of the event for filtering
  • DataContentType: Format of the event data

CloudEvents Configuration Example: ​

json
{
    "ServiceBus": {
        "CloudEvents": {
            "Source": "https://api.mystore.com/orders",
            "DefaultType": "com.mystore.orders",
            "Subject": "orders",
            "DataContentType": "application/json"
        }
    }
}

Generated CloudEvent Example: ​

json
{
    "specversion": "1.0",
    "type": "com.mystore.orders.order-created",
    "source": "https://api.mystore.com/orders",
    "subject": "orders/12345",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "time": "2024-01-15T10:30:00Z",
    "datacontenttype": "application/json",
    "data": {
        "orderId": "12345",
        "customerId": "67890",
        "totalAmount": 99.99
    }
}

Post-Configuration Processing ​

The ServiceBusOptions.Configurator runs after the options have been bound from configuration and performs final setup including:

  • Setting default PublicServiceName if not provided
  • Generating the service URN from domain and service name
  • Validating required connection strings
  • Logging configuration warnings for missing dependencies

The configurator follows the .NET options pattern for post-configuration processing, ensuring all derived values are computed correctly even when base configuration is incomplete.

Automatic Configuration Example: ​

// Given application name: "ECommerce.OrderService"
// And configuration:
{
  "ServiceBus": {
    "Domain": "ECommerce"
    // PublicServiceName not specified
  }
}

// After post-configuration:
// PublicServiceName = "ecommerce-orderservice" (derived from app name)
// ServiceUrn = "/e_commerce/ecommerce-orderservice" (generated URN)

Missing Data Source Scenario: ​

// Standalone use with neither an application NpgsqlDataSource registered in DI
// nor a ServiceBus connection string configured throws at startup:
// "No NpgsqlDataSource is registered and the DB string 'ServiceBus' is not set."

// A generated service always registers an application NpgsqlDataSource, so message
// persistence reuses it automatically and this path is never hit. For standalone
// library use, provide ConnectionStrings:ServiceBus as the fallback.

Constructors ​

ServiceBusOptions() ​

csharp
public ServiceBusOptions()

Fields ​

SectionName ​

Gets the configuration section name used to bind these options.

csharp
public const string SectionName = "ServiceBus"

Field Value ​

string

Properties ​

Domain ​

Gets or sets the domain name for the service, used for message routing and URN generation.

csharp
public string Domain { get; set; }

Property Value ​

string

Remarks ​

See for detailed configuration information.

PublicServiceName ​

Gets or sets the public service name used for external identification and message routing.

csharp
public string PublicServiceName { get; set; }

Property Value ​

string

Examples ​

Examples of good service names:

  • order-service
  • payment-processor
  • inventory-manager
  • customer-portal

Remarks ​

See for detailed configuration information.

ReliableMessaging ​

Enables reliable message delivery. (Default: true)

csharp
public bool ReliableMessaging { get; set; }

Property Value ​

bool

Remarks ​

Enables:

  • Automatic transaction middleware
  • Durable local queues for reliable processing
  • Durable outbox pattern on all sending endpoints

These settings ensure message delivery reliability and prevent message loss in case of failures.

ServiceUrn ​

Gets the service URN (Uniform Resource Name) used for message routing and identification.

csharp
public Uri ServiceUrn { get; }

Property Value ​

Uri

Examples ​

See class-level examples in .

Remarks ​

See for detailed configuration information.

Momentum .NET