A Microsoft Azure Cloud Service has to detect and respond to changes to its service configuration. Two types of changes are exposed to the service: changes to the ConfigurationSettings element of the ServiceConfiguration.cscfg service configuration file and changes to the service topology. The latter refers to changes in the number of instances of the various roles that comprise the service.

The RoleEnvironment class exposes six events to which a role can register a callback method to be notified about these changes:

The Changing event is raised before the change is applied to the role. For configuration setting changes, the RoleEnvironmentChangingEventArgs parameter to the callback method identifies the existing value of any configuration setting being changed. For a service topology change, the argument specifies the names of any roles whose instance count is changing. The RoleEnvironmentChangingEventArgs parameter has a Cancel property that can be set to true to recycle an instance in response to specific configuration setting or topology changes.

The Changed event is raised after the change is applied to the role. As for the previous event, for configuration setting changes, the RoleEnvironmentChangedEventArgs parameter to the callback method identifies the new value of any changed configuration setting. For a service topology change, the argument specifies the names of any roles whose instance count has changed. Note that the Changed event is not raised on any instance recycled in the Changing event.

The SimulteneousChanging and SimultaneousChanged events behave exactly like the normal events, but they are called only during a simultaneous update.

We will talk about this kind of update in the Publishing a Cloud Service with options from Visual Studio recipe.

The Stopping event is raised on an instance being stopped. The OnStop() method is also invoked. Either of them can be used to implement an orderly shutdown of the instance. However, this must completed within 5 minutes. In a web role, the Application_End() method is invoked before the Stopping event is raised and the OnStop() method is invoked. It can also be used for shutdown code.

The StatusCheck event is raised every 15 seconds. The RoleInstanceStatusCheckEventArgs parameter to the callback method for this event specifies the status of the instance as either Ready or Busy. The callback method can respond to the StatusCheck event by invoking the SetBusy() method on the parameter to indicate that the instance should be taken out of the load-balancer rotation temporarily. This is useful if the instance is so busy that it is unable to process additional inbound requests.

In this recipe, we'll learn how to manage service configuration and topology changes to a Cloud Service.

private static void RoleEnvironmentChanging(object sender, 
    RoleEnvironmentChangingEventArgs e)
{            
    var oldInstances =
        e.Changes.OfType<RoleEnvironmentTopologyChange>()
        .SelectMany(p => RoleEnvironment.Roles[p.RoleName].Instances);
    var oldValues =        e.Changes.OfType<RoleEnvironmentConfigurationSettingChange>()
        .ToDictionary(p => p.ConfigurationSettingName,p=>RoleEnvironment            .GetConfigurationSettingValue(p.ConfigurationSettingName));
    e.Cancel =oldValues.Any(p=>p.Key=="SettingRequiringRecycle");
}