Target Version: NServiceBus 5.x
Standard support for version 5.x of NServiceBus has expired. For more information see our Support Policy.
This page refers to the legacy Azure Service Bus transport that uses the WindowsAzure.ServiceBus NuGet package. This package is currently on extended support until May 2022, after which it will be out of support according to the support policy. All users should migrate to the Azure Service Bus transport transport.

Azure Service Bus entity naming rules

Azure Service Bus transport works with the Messaging namespaces and operates on four types of entities: queues, topics, subscriptions, and rules. Entities have their paths and names derived from NServiceBus endpoint and event names. Entities have path and name rules applied to:

  1. Allowed characters
  2. Maximum length
Only queues and topics can have a path.

When entity name does not follow the rules, an exception is raised by the broker and transport fails to start. Paths and names need to be validated and adhere to the Azure Service Bus service rules.

Entity TypeValid CharactersPath / Name Maximum Length
QueueLetters, numbers, periods (.), hyphens (-), underscores (_), and forward slashes (/).260
TopicLetters, numbers, periods (.), hyphens (-), underscores (_), and forward slashes (/).260
SubscriptionLetters, numbers, periods (.), hyphens (-), and underscores (_).50
RuleLetters, numbers, periods (.), hyphens (-), and underscores (_).50

When sanitization strategy is specified, the validation settings can be overridden. The validation settings determine how entity names are validated. They should correspond to the validation rules in the configured Azure Service Bus namespace. The rules implementations vary depending on the namespace type, and are changing over time (in some cases without notice and update of the relevant MSDN documentation). The default settings align with the recently created Standard namespaces.


Sanitization is an operation that is performed on an entity path or name to ensure the broker can operate on the entity, and no exception is thrown. Sanitization can be performed manually or by the Azure Service Bus transport.

To perform manual sanitization, inspect entity name for invalid characters and number of characters. For automated sanitization, the transport allows configuration outlined below.

Automated sanitization

All entities treated the same for allowed characters. Only letters, numbers, periods (.), hyphens (-), and underscores (_) were allowed. Maximum length was predefined by the transport.

In Version 6.4.x Naming Conventions were added to allow custom sanitization of queues, topics, and subscriptions.

Future consideration prior to using sanitization

When implementing custom sanitization, consider factors such as readability and discover-ability. Things to consider:

  • Truncated long entity names could conflict.
  • Hashed entity names could lead to difficult names to use during production troubleshooting or debugging.
  • Sanitized entity names stay in the system and cannot be replaced until no longer used.
  • Composition strategy needs to work in conjunction with custom sanitization.
    • If HierarchyComposition is used, the generated path must be shared with the custom sanitization strategy and be exempted from sanitization.

Possible ways to avoid sanitization

  • Define endpoint name as short and meaningful.
  • Avoid message definitions in deep-nested namespaces.
  • Keep event names descriptive and short.

Last modified