# Configuration ## Configuring an endpoint To use Azure Service Bus as the underlying transport: ```cs var transport = endpointConfiguration.UseTransport(); transport.ConnectionString("Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]"); ``` ## Connectivity These settings control how the transport connects to the broker. ### Transport * `UseWebSockets()`: Configures the transport to use AMQP over websockets. ```cs transport.UseWebSockets(); ``` * `TimeToWaitBeforeTriggeringCircuitBreaker(TimeSpan)`: The time to wait before triggering the circuit breaker after a critical error occurred. Defaults to 2 minutes. ```cs transport.TimeToWaitBeforeTriggeringCircuitBreaker(TimeSpan.FromMinutes(2)); ``` ### Retry-policy * `CustomRetryPolicy(ServiceBusRetryOptions)`: Allows replacement of the default [retry options](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusretryoptions?view=azure-dotnet). ```cs var azureAsbRetryOptions = new Azure.Messaging.ServiceBus.ServiceBusRetryOptions { Mode = Azure.Messaging.ServiceBus.ServiceBusRetryMode.Exponential, MaxRetries = 5, Delay = TimeSpan.FromSeconds(0.8), MaxDelay = TimeSpan.FromSeconds(15) }; transport.CustomRetryPolicy(azureAsbRetryOptions); ``` ### Token-credentials * `CustomTokenCredential(TokenCredential)`: Enables using Microsoft Entra ID authentication such as [managed identities for Azure resources](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-managed-service-identity) instead of the shared secret in the connection string. > [!NOTE] > **Microsoft Entra ID** authentication requires a fully-qualified namespace usage (e.g. `.servicebus.windows.net`) instead of a connection string (e.g. `Endpoint=sb://.servicebus.windows.net>;[...]`). ## Entity creation These settings control how the transport creates entities in the Azure Service Bus namespace. > [!WARNING] > Entity creation settings are applied only at the time the corresponding entities are created; they are not updated on subsequent startups. ### Access rights By default, the transport requires elevated privileges to manage namespace entities at runtime. If using a [shared access policy](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-sas), make sure to include `Manage` rights or the [Azure Service Bus Data Owner](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#azure-service-bus-data-owner) role if authenticating using [Managed Identities](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-managed-service-identity). To avoid running with elevated privileges: - Make sure that [installers are not configured to run](/nservicebus/operations/installers.md) - Use [operational scripting](/transports/azure-service-bus/operational-scripting.md) to provision entities(queues, topics and subscriptions) - [Turn off automatic subscriptions](/nservicebus/messaging/publish-subscribe/controlling-what-is-subscribed.md#disabling-auto-subscription) ### Topology * `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](https://learn.microsoft.com/en-us/rest/api/servicebus/create-topic). ### Settings * `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](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quotas) 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](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-partitioning). * `SubscriptionNamingConvention(Func)`: By default subscription names are derived from the endpoint name. 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](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quotas). * `SubscriptionNameShortener(Func)`: Shortens subscription names that exceed the maximum length. The shortener is invoked only when a subscription name exceeds the maximum length. * `SubscriptionRuleNamingConvention(Func)`: By default rule names are derived from the message type's full name. This callback allows for a replacement name for the rule. Rule names must adhere to the limits outlined in [Service Bus quotas](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quotas). * `RuleNameShortener(Func)`: Shortens rule names that exceed the maximum length. The shortener is invoked only when a rule name exceeds the maximum length. #### Combining shorteners and naming conventions When both a shortener and a naming convention are provided for a subscription or subscription rule, the naming convention is applied first, and the result is then passed into the shortener. ## 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](/nservicebus/operations/tuning.md) by the prefetch multiplier. The default value of the multiplier is 10, but it can be changed by using the following: ```cs transport.PrefetchMultiplier(3); ``` Alternatively, the whole calculation can be overridden by setting the prefetch count directly using the following: ```cs transport.PrefetchCount(100); ``` To disable prefetching, prefetch count should be set to zero. > [!NOTE] > The lock duration for all prefetched messages starts as soon as they are fetched. To avoid `LockLostException`, ensure the lock-renewal duration is longer than the total time it takes to process all prefetched messages (i.e., message handler execution time multiplied by the prefetch count). > In addition, it's important to consider how endpoints are scaled. If the prefetch count is high, the lock may deprive other endpoint instances of messages, making those instances redundant. ## Lock-renewal For all supported transport transaction modes (except `TransportTransactionMode.None`), the transport utilizes a peek-lock mechanism to ensure that only one instance of an endpoint can process a message. The default lock duration is set during entity creation. By default, the transport uses the SDK's default maximum auto lock renewal duration of 5 minutes. To ensure smooth processing, it is recommended to configuring the `MaxAutoLockRenewalDuration` property to be greater than the longest running handler for the endpoint. This helps avoid `LockLostException` and ensures the message is properly handled by [the recoverability process](/nservicebus/recoverability/index.md). > [!NOTE] > Message lock renewal is initiated by client code, not the broker. If a request to renew a lock fails after all the SDK built-in retries (e.g., due to 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 a best effort, not as a guaranteed operation. > [!NOTE] > The following approaches may be considered to minimize or avoid the occurrence of message lock renewals: > > - Optimise the message handlers to reduce their execution time. > - Reduce the prefetch count. All messages are locked on peek, so when they are prefetched, they remain locked until they are all processed.