Configuring an endpoint
To use Azure Service Bus as the underlying transport:
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
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.TimeToWaitBeforeTriggeringCircuitBreaker(TimeSpan): The time to wait before triggering the circuit breaker after a critical error occurred. Defaults to 2 minutes.
Retry-policy
CustomRetryPolicy(RetryPolicy): Allows replacement of the default retry policy.
Token-credentials
CustomTokenCredential(TokenCredential): Enables using Microsoft Entra ID authentication such as managed identities for Azure resources instead of the shared secret in the connection string.
Microsoft Entra ID authentication requires a fully-qualified namespace usage (e.g. Endpoint=sb:/).
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.
Access rights
By default the transport requires elevated privileges to manage subscriptions at runtime. If using a shared access policy make sure to include Manage rights or the Azure Service Bus Data Owner role if authenticating using Managed Identities.
To avoid running with elevated privileges:
- Make sure that installers are not configured to run
- Turn off automatic subscriptions
- Use operational scripting to provision entities(queues, topics and subscriptions)
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 tobundle-1. Topic names must adhere to the limits outlined in the Microsoft documentation on topic creation.
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 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.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.<string, string>) SubscriptionNameShortener(Func: Shortens subscription names that exceed the maximum length. The shortener is invoked only when a subscription name exceeds the maximum length.<string, string>) 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.<Type, string>) RuleNameShortener(Func: Shortens rule names that exceed the maximum length. The shortener is invoked only when a rule name exceeds the maximum length.<string, string>)
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 by the prefetch multiplier. The default value of the multiplier is 10, but it can be changed by using the following:
transport.PrefetchMultiplier(3);
Alternatively, the whole calculation can be overridden by setting the prefetch count directly using the following:
transport.PrefetchCount(100);
To disable prefetching, prefetch count should be set to zero.
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 the endpoint's scaling. If the prefetch count is high, the lock may deprive other endpoint instances of messages, rendering additional endpoint instances unnecessary.
Lock-renewal
For all supported transport transaction modes (except TransportTransactionMode.), 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.
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 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.
If message lock renewal is required, it may be worth checking the duration of the handlers, and see whether these can be optimised. In addition, it may be worth checking whether the prefetch count is too high, considering all messages are locked on peek. This may indicate that too many messages are locked for which the processing exceeds the lock duration.