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 Azure Cloud Services, then it should be configured by implementing the IConfigureThisEndpoint interface.
Enabling the Transport
To enable a given transport, the UseTransport<T> should be called on the endpoint configuration and a connection string must be provided.
For example using Azure Service Bus Transport
8-pre 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:
8-pre 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];");
}
}
5.x NServiceBus.Azure.Transports.WindowsAzureStorageQueues
public class EndpointConfig :
IConfigureThisEndpoint,
UsingTransport<AzureStorageQueue>
{
}
Enabling the Persistence
The Azure Storage Persistence can be enabled by specifying the UsePersistence<AzureStoragePersistence> on the endpoint config as well.
2-pre 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];");
}
}
6.x NServiceBus.Azure
public class EndpointConfig :
IConfigureThisEndpoint
{
public void Customize(BusConfiguration busConfiguration)
{
busConfiguration.UsePersistence<AzureStoragePersistence>();
}
}
NServiceBus.Hosting.Azure, these persistence strategies will be enabled by default.Convention to override configuration
NServiceBus is typically configured using an app.config file, however Azure Cloud Services have their own configuration model. That makes settings management between various environments (e.g. local machine and production) complicated. In order to simplify the process, NServiceBus also supports a convention-based configuration. It 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.config file.
The configuration source can be turned on like this:
8-pre 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:
6.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
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.config file by specifying a dedicated config section:
6.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
<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}" />
5.x NServiceBus.Azure.Transports.WindowsAzureServiceBus
<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 (.cscfg), when hosting in the Azure Cloud Service.
First define the setting in the service definition file (.csdef).
6.x NServiceBus.Hosting.Azure
<WorkerRole name="WorkerRole">
<ConfigurationSettings>
<Setting name="AzureServiceBusQueueConfig.ConnectionString"/>
</ConfigurationSettings>
</WorkerRole>
Then specify the value for every cloud service deployment in the Cloud Services project.
6.x NServiceBus.Hosting.Azure
<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.PropertyName. Tags can be nested: ParentTagName.ChildTagName.PropertyName. 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.config file. The value provided in the service configuration file takes precedence over the value specified in the app.config file.
Applying configuration changes
Azure Cloud Services allows to change 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.Cancel = true;
If at least 2 role instances are running, then 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.
