Getting Started


Target Version: NServiceBus 7.x

Configuring an endpoint

To use Azure Service Bus as the underlying transport:

var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();


These settings control how the transport connects to the broker.


  • UseWebSockets(): Configures the transport to use AMQP over websockets.
  • TimeToWaitBeforeTriggeringCircuitBreaker(TimeSpan): The time to wait before triggering the circuit breaker after a critical error occurred. Defaults to 2 minutes.


  • CustomRetryPolicy(RetryPolicy): Allows replacement of the default retry policy.


Entity creation

These settings control how the transport creates entities in the Azure Service Bus namespace.

Entity creation settings are applied only at creation time of the corresponding entities; they are not updated on subsequent startups.


  • TopicName(string): The topic's name used to publish events between endpoints. All endpoints share this topic, so ensure all endpoints specify the same topic name. Defaults to bundle-1. Topic names must adhere to the limits outlined in the Microsoft documentation on topic creation.


  • EntityMaximumSize(int): The maximum entity size in GB. The value must correspond to a valid value for the namespace type. Defaults to 5. See the Microsoft documentation on quotas and limits for valid values.

  • EnablePartitioning(): Partitioned entities offer higher availability, reliability, and throughput over conventional non-partitioned queues and topics. For more information about partitioned entities see the Microsoft documentation on partitioned messaging entities.

  • SubscriptionNameShortener(Func<string, string>): By default subscription names are derived from the endpoint name, which may exceed the maximum length of subscription names. This callback allows for a replacement name for the subscription. Subscription names must adhere to the limits outlined in the Microsoft documentation on subscription creation.

  • RuleNameShortener(Func<string, string>): By default rule names are derived from the message type's full name, which may exceed the maximum length of rule names. This callback allows for a replacement name for the rule. Rule names must adhere to the limits outlined in Service Bus quotas.

The shorteners are invoked only when the entity name exceeds the maximum length.

Controlling the prefetch count

When consuming messages from the broker, throughput can be improved by having the consumer prefetch additional messages. The prefetch count is calculated by multiplying maximum concurrency by the prefetch multiplier. The default value of the multiplier is 10, but it can be changed by using the following:


Alternatively, the whole calculation can be overridden by setting the prefetch count directly using the following:


To disable prefetching, prefetch count should be set to zero.


For all supported transport transaction modes (expect TransportTransactionMode.None), the transport uses a peek-lock mechanism to ensure a single instance of an endpoint can process a message. The default lock duration is specified during the entity creation. By default, the transport uses the SDK's default maximum auto lock renewal duration of 5 minutes.

Message lock renewal is initiated by client code, not the broker. If the request to renew the lock fails after all the SDK built-in retries (.e.g due to a connection-loss), the lock won't be renewed, and the message will become unlocked and available for processing by competing consumers. Lock renewal should be treated as best-effort and not as a guaranteed operation.

Last modified