Intent.Eventing.NServiceBus

This module integrates NServiceBus as a message broker for publishing and subscribing to integration events and commands in .NET applications.

What is NServiceBus?

NServiceBus is a battle-tested service bus for .NET that provides reliable messaging, automatic retries, error queues, and durable outbox support. It is built around the concept of a single named endpoint per application, with support for multiple transport technologies.

For more information, see the NServiceBus documentation.

What's in this module?

Modeling Integration Events and Integration Commands in the Services designer.
NServiceBus endpoint configuration generation (transport, serialization, recoverability, installers).
Open generic handler wiring (NServiceBusMessageHandler<TMessage>) with explicit registry registration — no assembly scanning required.
Command routing (RouteToEndpoint) for commands sent to other endpoints.
SQL Persistence transactional outbox (with EF Core shared connection).
appsettings.json configuration entries.
Dependency Injection wiring.
Multi-broker coexistence support via the NServiceBus stereotype.
.NET 8/9 (UseNServiceBusHost) and .NET 10+ (AddNServiceBusEndpoint) host registration.

Module Settings

Transport

Selects the underlying message transport. Options:

Setting	Transport	NuGet
`Learning Transport`	File-based, local only — ideal for development	Included in `NServiceBus`
`RabbitMQ`	RabbitMQ (Quorum queues, Conventional routing)	`NServiceBus.RabbitMQ`
`Azure Service Bus`	Azure Service Bus Topics	`NServiceBus.Transport.AzureServiceBus`
`Amazon SQS`	AWS SQS + SNS	`NServiceBus.AmazonSQS`

The default is Learning Transport. Change the setting in Intent Architect's application settings and rerun the Software Factory to switch transports.

Outbox Pattern

Enables the NServiceBus transactional outbox, which ensures messages are only dispatched after the database transaction commits.

Setting	Behaviour
`None`	No outbox. Messages are dispatched inline.
`Sql Persistence`	Uses `NServiceBus.Persistence.Sql` with a shared EF Core `DbConnection`/`DbTransaction`. Requires `Intent.EntityFrameworkCore`.

Important

Setting OutboxPattern to Sql Persistence without the Intent.EntityFrameworkCore module installed will cause the Software Factory to fail with a descriptive error.

Recoverability Policy

Configures automatic retry behaviour when message processing fails.

Setting	Behaviour
`None`	No retries. Failed messages are immediately sent to the error queue.
`Immediate Only`	Immediate consecutive retries before moving to the error queue.
`Delayed Only`	Delayed retries with configurable back-off before moving to the error queue.
`Immediate and Delayed`	Immediate retries followed by delayed retries.

Retry counts and delay values are driven by appsettings.json and can be overridden per environment.

Modeling Integration Events and Commands

Integration Events and Integration Commands are modeled in the Services designer. This module installs the Intent.Modelers.Eventing module which provides the designer elements.

Integration Events

Events represent something that happened. Any application can publish an event; any application can subscribe to it. Events do not require an endpoint name — they are broadcast via the transport's pub/sub mechanism (SNS for SQS, Topics for Azure Service Bus, Exchanges for RabbitMQ).

Integration Commands

Commands target a specific endpoint. The NServiceBus stereotype is mandatory on every Integration Command:

Open the Integration Command in the Services designer.
Right-click → Add Stereotype → NServiceBus.
Set Endpoint Name to the NServiceBus:EndpointName config value of the application that handles this command.

Important

EndpointName must be set on every NServiceBus Integration Command — both in the application that sends it and in the application that subscribes to it. The value identifies which endpoint owns the command. Omitting it causes the Software Factory to fail with a descriptive error pointing to the offending command.

Generated Code

NServiceBusConfiguration

The primary generated file. Contains:

AddNServiceBusConfiguration(IServiceCollection, IConfiguration) — registers the message bus in DI and (on .NET 10+) starts the NServiceBus endpoint.
UseNServiceBusHost(IHostBuilder) — (.NET 8/9 only) extension method called from Program.cs to start the endpoint on the host builder.
ConfigureMainEndpoint(IConfiguration) — private method that builds the full EndpointConfiguration: transport, persistence, installers, serialization, recoverability, message conventions, handler registration, and command routing.

Handler Pattern

NServiceBus handler discovery via assembly scanning does not work for open generic types. This module uses explicit registry registration instead:

RegisterHandler<NServiceBusMessageHandler<TMessage>, TMessage>(endpointConfiguration);

NServiceBusMessageHandler<TMessage> implements IHandleMessages<TMessage> and delegates to the application-layer IIntegrationEventHandler<TMessage>, keeping infrastructure concerns out of the application layer.

Command Routing

Commands sent to other endpoints get a RouteToEndpoint entry using the endpoint name from the NServiceBus stereotype:

routing.RouteToEndpoint(typeof(OrderAnimal), configuration["NServiceBus:Routing:Commands:OrderAnimal"] ?? "TargetApp");

The configuration key allows per-environment overrides without regenerating.

Commands handled by the same endpoint are self-routed (routed to endpointName).

Working with Multiple Message Bus Providers

This module can coexist with other message bus providers (e.g. MassTransit) in the same application. When multiple providers are installed, Intent Architect generates a Composite Message Bus that routes messages to the correct broker.

Designating Messages for NServiceBus

When only this module is installed, all messages automatically use NServiceBus — no additional configuration is needed.

When multiple providers are installed, mark messages for NServiceBus using the NServiceBus stereotype:

Right-click on a Package or Folder in the Services designer.
Select Add Stereotype → NServiceBus.

The stereotype can be applied at package or folder level. Child elements inherit the designation automatically.

`appsettings.json` Configuration

The module generates default entries. Key sections:

{
  "NServiceBus": {
    "EndpointName": "MyApplication",
    "ErrorQueue": "error",
    "Recoverability": {
      "ImmediateRetries": 5,
      "DelayedRetries": 3,
      "DelayIncreaseSeconds": 10
    },
    "LearningTransport": {
      "StorageDirectory": "%TEMP%\\nservicebus-learning"
    },
    "Routing": {
      "Commands": {
        "OrderAnimal": "TargetApp"
      }
    }
  },
  "ConnectionStrings": {
    "RabbitMQ": "amqp://guest:guest@localhost:5672",
    "AzureServiceBus": "Endpoint=sb://<namespace>.servicebus.windows.net/;..."
  }
}

Amazon SQS uses the AWS credential chain — no connection string is needed.

Dependency Injection Wiring

The module registers AddNServiceBusConfiguration into the Infrastructure DI extension:

public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
{
    // ...
    services.AddNServiceBusConfiguration(configuration);
    // ...
}

On .NET 8/9, the host builder call is also injected into Program.cs:

builder.Host.UseNServiceBusHost();

Local Development

Learning Transport (no infrastructure required)

The Learning Transport stores messages as files on disk. It requires no external service and is the fastest way to verify handler wiring locally. Set Transport to Learning Transport in module settings.

RabbitMQ (Docker)

docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.11-management

Admin console: http://localhost:15672/ (guest/guest).

Azure Service Bus

Use a real Azure namespace with a connection string, or use the Azure Service Bus emulator for local development.

Store connection strings in user secrets:

dotnet user-secrets set "ConnectionStrings:AzureServiceBus" "<your-connection-string>"

Amazon SQS

SQS uses the AWS credential chain. Set up credentials via IAM access keys or AWS SSO:

# IAM access keys
aws configure

# Or set environment variables
$env:AWS_ACCESS_KEY_ID = "..."
$env:AWS_SECRET_ACCESS_KEY = "..."
$env:AWS_REGION = "eu-west-1"

EnableInstallers() automatically creates SQS queues and SNS topics on first run.

Intent.Eventing.NServiceBus

What is NServiceBus?

What's in this module?

Module Settings

Transport

Outbox Pattern

Important

Recoverability Policy

Modeling Integration Events and Commands

Integration Events

Integration Commands

Important

Generated Code

NServiceBusConfiguration

Handler Pattern

Command Routing

Working with Multiple Message Bus Providers

Designating Messages for NServiceBus

appsettings.json Configuration

Dependency Injection Wiring

Local Development

Learning Transport (no infrastructure required)

RabbitMQ (Docker)

Azure Service Bus

Amazon SQS

`appsettings.json` Configuration