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": {
    "ServiceBus": "Host=postgres;Database=order_messaging;Username=app;Password=secret"
  }
}

Multi-Environment Configuration ​

json
// appsettings.Development.json
{
  "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)

Warning Scenarios ​

csharp
// Missing connection string warning:
// "ConnectionStrings:ServiceBus is not set. Transactional Inbox/Outbox 
//  and Message Persistence features disabled"

// This allows the application to start without messaging persistence
// but logs a clear warning about reduced functionality

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-driven design patterns where the assembly name reflects the business domain.

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)

Warning Scenarios: ​

// Missing connection string warning:
// "ConnectionStrings:ServiceBus is not set. Transactional Inbox/Outbox 
//  and Message Persistence features disabled"

// This allows the application to start without messaging persistence
// but logs a clear warning about reduced functionality

Constructors ​

ServiceBusOptions() ​

csharp
public ServiceBusOptions()

Properties ​

CloudEvents ​

Gets or sets the CloudEvents configuration for standardized cross-service messaging.

csharp
public CloudEventsSettings CloudEvents { get; set; }

Property Value ​

CloudEventsSettings

Examples ​

See class-level examples in .

Remarks ​

See for detailed configuration information.

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.

SectionName ​

Gets the configuration section name used to bind these options.

csharp
public static string SectionName { get; }

Property Value ​

string

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.

Methods ​

GetServiceName(string) ​

Converts an application name to a service name following DNS naming conventions.

csharp
public static string GetServiceName(string appName)

Parameters ​

appName string

The application name to convert.

Returns ​

string

A service name in lowercase with dots replaced by hyphens, suitable for DNS naming, Kubernetes services, and message routing.

Examples ​

See class-level examples in .

Remarks ​

See for detailed configuration information.

Momentum .NET