Azure Service Bus Transport Upgrade Version 6 to 7

Topology is mandatory

In Versions 7 and above the topology selection is mandatory:

9.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();

transport.UseForwardingTopology();
// OR
transport.UseEndpointOrientedTopology();
8.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();

transport.UseForwardingTopology();
// OR
transport.UseEndpointOrientedTopology();
7.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();

transport.UseForwardingTopology();
// OR
transport.UseEndpointOrientedTopology();

The EndpointOrientedTopology is backward compatible with versions 6 and below of the transport. The ForwardingTopology is the recommended option for new projects.

When selecting EndpointOrientedTopology, it is also necessary to configure publisher names, in order to ensure that subscribers are subscribed to the correct publisher:

9.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var topology = transport.UseEndpointOrientedTopology();

topology.RegisterPublisher(typeof(MyMessage), "publisherName");
// OR
var messagesAssembly = Assembly.LoadFrom("path/to/assembly/containing/messages");
topology.RegisterPublisher(messagesAssembly, "publisherName");
8.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var topology = transport.UseEndpointOrientedTopology();

topology.RegisterPublisher(typeof(MyMessage), "publisherName");
// OR
var messagesAssembly = Assembly.LoadFrom("path/to/assembly/containing/messages");
topology.RegisterPublisher(messagesAssembly, "publisherName");
7.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var topology = transport.UseEndpointOrientedTopology();

topology.RegisterPublisher(typeof(MyMessage), "publisherName");
// OR
var messagesAssembly = Assembly.LoadFrom("path/to/assembly/containing/messages");
topology.RegisterPublisher(messagesAssembly, "publisherName");

For more details on topologies refer to the Azure Service Bus Transport Topologies article.

Sanitization

Azure Service Bus entities have path and naming rules that limit the allowed characters and maximum length. NServiceBus derives entity names from endpoint and event names; these derived names may fail Azure Service Bus validation. Sanitization allows to modify entity names to meet the namning rules of the broker.

In Versions 6 and below sanitization was performed by default and the MD5 algorithm was used to truncate entity names. In Versions 7 and above, the sanitization has to configured explicitly.

In order to maintain backward compatibility, register a custom sanitization strategy.

In version 6.4.0 NamingConventions class was introduced to customize sanitization. The class is obsoleted. Instead, implement a custom sanitization strategy.

New Configuration API

In Versions 6 and below the transport was configured using the AzureServiceBusQueueConfigconfiguration section. This section has been removed in favor of a more granular code based configuration API.

The new API is accessible through the .UseTransport<AzureServiceBusTransport>() extension point. Refer to the Full Configuration Page for more details.

Configuring a connection string

Setting a connection string is still supported using the ConnectionString extension method:

7.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
transport.ConnectionString("Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]");

Default value changes

The default values for the following settings have changed:

  • BatchSize, which had a default value of 1000, is replaced by PrefetchCount with a default value of 200.
  • MaxDeliveryCount is set to number of immediate retries + 1. For system queues the value has changed from 6 to 10.

For more details refer to the ASB Batching and ASB Retry behavior articles.

Setting Entity Property Values

The other configuration properties found on AzureServiceBusQueueConfig were related to the configuration of Azure Service Bus entities. Even though the name implied differently, these settings were not only applied to queues, but also to topics and subscriptions.

In the new configuration API the settings for queues, topics and subscriptions can be configured individually using the Queues(), Topics() and Subscriptions() extension points.

For example the lock duration on a queue can be configured using the LockDuration setting:

9.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var queues = transport.Queues();
queues.LockDuration(TimeSpan.FromMinutes(1));
8.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var queues = transport.Queues();
queues.LockDuration(TimeSpan.FromMinutes(1));
7.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var queues = transport.Queues();
queues.LockDuration(TimeSpan.FromMinutes(1));

and the size of the topics can be configured using the MaxSizeInMegabytes setting:

9.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var topics = transport.Topics();
topics.MaxSizeInMegabytes(SizeInMegabytes.Size5120);
8.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var topics = transport.Topics();
topics.MaxSizeInMegabytes(SizeInMegabytes.Size5120);
7.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var topics = transport.Topics();
topics.MaxSizeInMegabytes(SizeInMegabytes.Size5120);

Securing Credentials

All endpoints need to be upgraded to Version 7 prior to enabling this feature. Older versions of the transport cannot use namespace names.

In order to enhance security and to avoid sharing sensitive information enable the UseNamespaceNameInsteadOfConnectionString feature using the following steps:

  • Upgrade all endpoints to Version 7 or above. Previous versions of the transport aren't able to understand namespace names instead of connection strings.
  • After the above has been done and all endpoints have been deployed switch on the UseNamespaceNameInsteadOfConnectionString feature and re-deploy.

BrokeredMessage conventions

In versions 6 and below, BrokeredMessage conventions were specified using BrokeredMessageBodyConversion class. In versions 7 and above, it has been replaced by configuration API.

Related Articles


Last modified