Controlling What Is Subscribed

Automatic subscriptions

The default mode for managing subscriptions is auto-subscribe. Every time a subscriber endpoint starts, it determines which events it needs to subscribe to and automatically subscribes to them. For more information on how publish and subscribe works, refer to Publish-Subscribe.

Message types matching both of the following criteria will be auto-subscribed at startup:

1. Defined as an event either using IEvent or by the .DefiningEventsAs convention
2. At least one message handler and/or saga exists for the given event

When using a transport that doesn't support publish-subscribe natively, if a message handler is defined for an event but no publisher information can be found, the endpoint will log the following error at startup:

AutoSubscribe was unable to subscribe to event '<event-type-full-name>': No publisher address could be found for message type '<event-type-full-name>'.

Exclude event types from auto-subscribe

In NServiceBus version 7.1 and above, specific event types can be excluded from the auto-subscription mechanism using the following API:

var autoSubscribe = endpointConfiguration.AutoSubscribe();
autoSubscribe.DisableFor<EventType>();

Exclude sagas from auto-subscribe

Sagas are treated the same as handlers and will cause an endpoint to subscribe to a given event. It is possible to opt-in to the old exclude saga event handling behavior using:

var autoSubscribe = endpointConfiguration.AutoSubscribe();
autoSubscribe.DoNotAutoSubscribeSagas();

Auto-subscribe to plain messages

In NServiceBus version 6 and above, it is possible to subscribe to messages not defined as events by manually subscribing to the message type.

When a subscriber stops or uninstalls

A subscriber will not unsubscribe automatically when it stops; it remains registered with the publisher to receive events. The publisher still sends events to the stopped subscriber's input queue. When the subscriber starts, it will consume messages from its queue. The subscriber will never lose an event.

Disabling auto-subscription

Automatic subscriptions by the infrastructure can be disabled using the configuration API:

endpointConfiguration.DisableFeature<AutoSubscribe>();

Manually subscribing to a message

Events can be manually subscribed and unsubscribed to:

await messageSession.Subscribe<MyEvent>();

await messageSession.Unsubscribe<MyEvent>();

Subscribe and Unsubscribe are accessible via the IMessageSession or within a feature startup task.

Decommissioning event handlers

An event is not automatically unsubscribed when a message handler is removed. The subscription remains active until it is unsubscribed.

Unsubscribing can be done at startup via IMessageSession.Unsubscribe. For example, via a background service:

public sealed class UnsubscribeService(IMessageSession messageSession) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await messageSession.Unsubscribe<MyEvent>();
    }
}

The service runs every time the endpoint starts. Unsubscribing from an event the subscriber isn't subscribed to has no effect, so the code is safe to keep. Once the endpoint has started in every environment where the subscription existed, you can remove the code.

Unsubscribing prevents future events from being sent to the subscriber's input queue, but it cannot remove any messages that have already been sent to the input queue. So, before removing the handler, consider what to do with events in the input queue that haven't been processed yet.