Configuring for cloud services hosting
Cloud services is a hosting model provided by the Azure cloud, which is specifically designed for hosting large applications. For a detailed description of the cloud service configuration in Azure, see What is the Cloud Service model packaging.
When NServiceBus is hosted in cloud services, it needs to connect to a specific Azure storage account (for Azure Storage Queues) or an Azure Service Bus namespace. For more information on required connection string formats, refer to the Windows Azure connection string formats article.
Configuring an endpoint
When an endpoint is hosted in a cloud service, it should be configured by implementing the IConfigureThisEndpoint interface.
Enabling the transport
To enable a given transport, UseTransport should be called on the endpoint configuration and a connection string must be provided.
For example, using the Azure Service Bus transport:
8.x NServiceBus.Hosting.Azure
public class EndpointConfig :
IConfigureThisEndpoint,
AsA_Worker
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
transport.ConnectionString("Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]");
endpointConfiguration.UsePersistence<AzureStoragePersistence>();
}
}
7.x NServiceBus.Hosting.Azure
public class EndpointConfig :
IConfigureThisEndpoint,
AsA_Worker
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
transport.ConnectionString("Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]");
endpointConfiguration.UsePersistence<AzureStoragePersistence>();
}
}
6.x NServiceBus.Hosting.Azure
public class EndpointConfig :
IConfigureThisEndpoint,
AsA_Worker
{
public void Customize(BusConfiguration busConfiguration)
{
var transport = busConfiguration.UseTransport<AzureServiceBusTransport>();
transport.ConnectionString("Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]");
busConfiguration.UsePersistence<AzureStoragePersistence>();
}
}
or using the Azure Storage Queues transport:
10-pre NServiceBus.Transport.AzureStorageQueues
public class EndpointConfig :
IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var transport = endpointConfiguration.UseTransport<AzureStorageQueueTransport>();
transport.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
9.x NServiceBus.Transport.AzureStorageQueues
public class EndpointConfig :
IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var transport = endpointConfiguration.UseTransport<AzureStorageQueueTransport>();
transport.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
8.x NServiceBus.Azure.Transports.WindowsAzureStorageQueues
public class EndpointConfig :
IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var transport = endpointConfiguration.UseTransport<AzureStorageQueueTransport>();
transport.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
7.x NServiceBus.Azure.Transports.WindowsAzureStorageQueues
public class EndpointConfig :
IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var transport = endpointConfiguration.UseTransport<AzureStorageQueueTransport>();
transport.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
6.x NServiceBus.Azure.Transports.WindowsAzureStorageQueues
public class EndpointConfig :
IConfigureThisEndpoint
{
public void Customize(BusConfiguration busConfiguration)
{
var transport = busConfiguration.UseTransport<AzureStorageQueueTransport>();
transport.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
Enabling the persistence
The Azure Table persistence can be enabled by calling UsePersistence on the endpoint config as well.
4-pre NServiceBus.Persistence.AzureTable
public class EndpointConfig : IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var persistence = endpointConfiguration.UsePersistence<AzureTablePersistence>();
persistence.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
3.x NServiceBus.Persistence.AzureTable
public class EndpointConfig : IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var persistence = endpointConfiguration.UsePersistence<AzureTablePersistence>();
persistence.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
2.x NServiceBus.Persistence.AzureStorage
public class EndpointConfig : IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var persistence = endpointConfiguration.UsePersistence<AzureStoragePersistence>();
persistence.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
1.x NServiceBus.Persistence.AzureStorage
public class EndpointConfig :
IConfigureThisEndpoint
{
public void Customize(EndpointConfiguration endpointConfiguration)
{
var persistence = endpointConfiguration.UsePersistence<AzureStoragePersistence>();
persistence.ConnectionString("DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];");
}
}
NServiceBus.Hosting.Azure, these persistence strategies will be enabled by default.Convention to override configuration
NServiceBus is typically configured using an app. file, however Azure Cloud Services have their own configuration model. That makes settings management between various environments (e.g. local machine and production) complicated. To simplify the process, NServiceBus supports a convention-based configuration which allows for adding any NServiceBus setting to the service configuration file. The value specified in the service configuration file will override the value specified in the app. file.
The configuration source can be turned on like this:
8.x NServiceBus.Hosting.Azure
endpointConfiguration.AzureConfigurationSource();
7.x NServiceBus.Hosting.Azure
endpointConfiguration.AzureConfigurationSource();
6.x NServiceBus.Hosting.Azure
busConfiguration.AzureConfigurationSource();
The convention-based override model works for all configuration sections used by NServiceBus. For example, it's possible to override the AzureServiceBusQueueConfig section which is available in Azure Service Bus Transport version 6 and below:
public class AzureServiceBusQueueConfig :
ConfigurationSection
{
[ConfigurationProperty("ConnectionString", IsRequired = true)]
public string ConnectionString
{
get { return this["ConnectionString"] as string; }
set { this["ConnectionString"] = value; }
}
}
It is configured in the app. file by specifying a dedicated config section:
<configSections>
<section name="AzureServiceBusQueueConfig"
type="NServiceBus.Config.AzureServiceBusQueueConfig, NServiceBus.Azure.Transports.WindowsAzureServiceBus" />
</configSections>
<AzureServiceBusQueueConfig ConnectionString="Endpoint=sb://{namespace}.servicebus.windows.net/;SharedSecretIssuer=owner;SharedSecretValue={key}" />
That setting can then be overridden in the service configuration file (.) when hosting in a Azure cloud service.
First, define the setting in the service definition file (.).
<WorkerRole name="WorkerRole">
<ConfigurationSettings>
<Setting name="AzureServiceBusQueueConfig.ConnectionString"/>
</ConfigurationSettings>
</WorkerRole>
Then, specify the value for every cloud service deployment in the cloud service project.
<Role name="WorkerRole">
<Instances count="2" />
<ConfigurationSettings>
<Setting name="AzureServiceBusQueueConfig.ConnectionString"
value="YourConnectionString"/>
</ConfigurationSettings>
</Role>
Names used for property overrides always have the following structure: TagName.. Tags can be nested: ParentTagName.. It's currently not possible to override parent tags that contain multiple child tags with the same name, therefore MessageEndpointMappings can't be overridden using this approach.
The default value set in the config section has the lowest priority. It can be overridden by the value specified in the app. file. The value provided in the service configuration file takes precedence over the value specified in the app. file.
Applying configuration changes
Azure cloud services allow changing the configuration settings from within the Azure portal. However, the changes made in the Azure portal are not automatically applied to the all NServiceBus components.
If configuration changes should result in a reconfiguration of the endpoint, consider instructing the RoleEnvironment to restart the role instances by subscribing to the RoleEnvironment.Changing event and setting e.
If at least two role instances are running, this will result in a configuration change without inflicting downtime on the overall system. Each instance may reboot individually in the process, but this is orchestrated across update and fault domains so that at any point in time an instance is operational.
