You can update your service's configuration while the service is running without taking the service offline. The service configuration (.cscfg) file contains the service's configuration.

To change configuration information, you can either upload a new configuration file, or edit the configuration file in place and apply it to your running service. This does not apply to certificate changes that are always done off-line.

For more information about the service configuration files, see Service Configuration Schema.

For practical information on service configuration, see also Using Windows Azure Development Environment Essentials.

Handling Configuration Changes with Service Runtime Events

The Windows Azure Managed Library includes the Microsoft.WindowsAzure.ServiceRuntime namespace, which provides classes for interacting with the Windows Azure environment from code running in a role instance. The RoleEnvironment class defines events raised before and after a configuration change:

  • The RoleEnvironment.Changing event occurs before the configuration change is applied to a given instance of a role. This event may be cancelled, in which case Windows Azure recycles the role. When the role is recycled, the configuration change is applied before the role is brought back online again.
  • The RoleEnvironment.Changed event occurs after the configuration change has been applied to a given instance of a role.

The Changing and Changed events are raised regardless of the health of any particular role instance. The Windows Azure Managed Library does not provide a means of determining the health of other role instances, but you can implement such health assessments yourself if your service needs this functionality.

Changing Event

The Changing event allows you to manage how a role instance responds to a configuration change. Via the Changing event, an instance can respond to a configuration change in one of two ways:

  • The instance can accept the configuration change on the fly, without going offline.
  • The instance can cancel the Changing event, in which case Windows Azure takes the instance offline, applies the configuration change, and then brings the instance back online.

By cancelling the Changing event, you can ensure that the instance proceeds through an orderly shutdown sequence and is taken offline before the configuration change is applied. During the shutdown process, Windows Azure raises the Stopping event, then runs any code in the OnStop method.

The total interval allowed for an instance's shutdown sequence is 30 seconds; if your code has not finished running within this interval, the process will automatically be terminated.

You may wish to cancel the Changing event if:

  • Your role does not support on-the-fly configuration changes, and requires recycling in order to apply the change.
  • Your role is in the midst of performing work that should not be disrupted by a configuration change, and needs to proceed through the shutdown sequence before applying the change.
Configuration Related Exception

When running the application, the system can raise the following exception:

SetConfigurationSettingPublisher needs to be called before FromConfigurationSetting can be used

Usually this happens when a web role is migrated from an older Windows Azure SDK version and is caused by changes associated with the full IIS model introduced in newer SDK versions. In the newer version the SetConfigurationSettingPublisher and FromConfigurationSetting belong to different “app domains”. For more information, see How to Resolve….

To avoid the exception you must assure that the following code is executed in the OnStart method of the web and worker roles before calling FromConfigurationSetting . In the case of the web role you can execute the code in the Application_Start method in the Global.ascx.cs file.

CloudStorageAccount.SetConfigurationSettingPublisher((configName, configSetter) =>
    {
        try
        {   // Retrieves the value of a setting in the service configuration file. 
            configSetter(RoleEnvironment.GetConfigurationSettingValue(configName));
        }
        catch (RoleEnvironmentException e)
        {

            System.Diagnostics.Trace.TraceError(e.Message);
            System.Threading.Thread.Sleep(5000);
        }
    });

For related topics, see the following posts.