The service model for a Cloud Service in Microsoft Azure is specified in two XML files: the service definition file, ServiceDefinition.csdef, and the service configuration file, ServiceConfiguration.cscfg. These files are part of the Microsoft Azure project.

The service definition file specifies the roles used in the Cloud Service, up to 25 in a single definition. For each role, the service definition file specifies the following:

The following code snippet is an example of the skeleton of the service definition document:

<ServiceDefinition name="<service-name>" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition" upgradeDomainCount="<number-of-upgrade-domains>" schemaVersion="<version>">
  <LoadBalancerProbes>  </LoadBalancerProbes>
  <WebRole …>  </WebRole>
  <WorkerRole …>  </WorkerRole>
  <NetworkTrafficRules>  </NetworkTrafficRules>
</ServiceDefinition>

We can mix up to 25 roles from both the web role and worker role types. In the past, there was also a third kind of supported role, the VM Role, which is now deprecated.

All instances of a role have the same size, chosen from standard sizes (A0-A04), memory intensive sizes (A5-A7), and compute intensive sizes (A8-A9). Each role may specify a number of input endpoints, internal endpoints, and instance-input endpoints. Input endpoints are accessible over the Internet and are load balanced, using a round-robin algorithm, across all instances of the role:

<InputEndpoint name="PublicWWW" protocol="http" port="80" />

Internal endpoints are accessible only by instances of any role in the Cloud Service. They are not load balanced:

<InternalEndpoint name="InternalService" protocol="tcp" />

Instance-input endpoints define a mapping between a public port and a single instance under the load balancer. An instance-input endpoint is linked to a specific role instance, using a port-forwarding technique on the load balancer. Onto it, we must open a range of ports through the AllocatePublicPortFrom section:

<InstanceInputEndpoint name="InstanceLevelService" protocol="tcp" localPort="10100">
  <AllocatePublicPortFrom>
    <FixedPortRange max="10105" min="10101" />
  </AllocatePublicPortFrom>
</InstanceInputEndpoint>

An X.509 public key certificate can be uploaded to a Cloud Service either directly on the Microsoft Azure Portal or using the Microsoft Azure Service Management REST API. The service definition file specifies which public key certificates, if any, are to be deployed with the role as well as the certificate store they are put in. A public key certificate can be used to configure an HTTPS endpoint but can also be accessed from code:

<Certificate name="CertificateForSSL" storeLocation="LocalMachine" storeName="My" />

Pluggable modules instruct Azure on how to set up the role. Microsoft Azure tooling for Visual Studio can automatically add/remove modules in order to enable/disable services as follows:

The following configuration XML code enables the additional modules:

<Imports>
  <Import moduleName="Diagnostics" />
  <Import moduleName="RemoteAccess" />
  <Import moduleName="RemoteForwarder" />
  <Import moduleName="Caching" />
</Imports>

Startup tasks are scripts or executables that run each time an instance starts, and they modify the runtime environment of the instance, up to and including the installation of the required software:

<Startup>
  <Task commandLine="run.cmd" taskType="foreground" executionContext="elevated">
    <Environment>
      <Variable name="A" value="B" />
    </Environment>
  </Task>
</Startup>

The local resources section specifies how to reserve an isolated storage in the instance, for temporary data, accessible through an API instead of direct access to the filesystem:

<LocalResources>
  <LocalStorage name="DiagnosticStore" sizeInMB="20000" cleanOnRoleRecycle="false" />
  <LocalStorage name="TempStorage" sizeInMB="10000" />
</LocalResources>

The runtime execution context specifies whether the role runs with limited privileges (default) or with elevated privileges that provide full administrative capabilities. Note that in a web role that is running full IIS, the runtime execution context applies only to the web role and does not affect IIS. This runs in a separate process with restricted privileges:

<Runtime executionContext="elevated" />

In a web role that is running full IIS, the site's element in the service definition file contains the IIS configuration for the role. It specifies the endpoint bindings, virtual applications, virtual directories, and host headers for the various websites hosted by the web role. The Hosting multiple websites in a web role recipe contains more information about this configuration. Refer to the following code:

<Sites>
  <Site name="Web">
    <Bindings>
      <Binding name="Endpoint1" endpointName="Endpoint1" />
    </Bindings>
  </Site>
</Sites>

The contents section specifies whether static contents are copied from an application folder to a destination folder on the Azure virtual machine, relative to the %ROLEROOT%\Approot folder:

<Contents>
  <Content destination="MyFolder">
    <SourceDirectory path="FolderA"/>        
  </Content>
</Contents>

The service definition file is uploaded to Microsoft Azure as part of the Microsoft Azure package.

The service configuration file specifies the number of instances of each role. It also specifies the values of any custom configuration settings as well as those for any pluggable modules imported in the service definition file.

Applications developed using the .NET framework typically store application configuration settings in an app.config or web.config file. However, in Cloud Services, we can mix several applications (roles), so a uniform and central point of configuration is needed. Runtime code can still use these files; however, changes to these files require the redeployment of the entire service package. Microsoft Azure allows custom configuration settings to be specified in the service configuration file where they can be modified without redeploying the application. Any service configuration setting that could be changed while the Cloud Service is running should be stored in the service configuration file. These custom configuration settings must be declared in the service definition file:

<ConfigurationSettings>
  <Setting name="MySetting" />
</ConfigurationSettings>

The Microsoft Azure SDK provides a RoleEnvironment.GetConfigurationSetting() method that can be used to access the values of custom configuration settings. There is also CloudConfigurationManager.GetSetting() of the Microsoft.WindowsAzure.Configuration assembly that checks in-service configuration first, and if no Azure environment is found, it goes to the local configuration file.

The service configuration file is uploaded separately from the Microsoft Azure package and can be modified independently of it. Changes to the service configuration file can be implemented either directly on the Microsoft Azure Portal or by upgrading the Cloud Service. The service configuration can also be upgraded using the Microsoft Azure Service Management REST API.

The customization of the service configuration file is limited almost to the role instance count, the actual values of the settings, and the certificate thumbprints:

<Role name="WorkerHelloWorld">
  <Instances count="2" />
  <ConfigurationSettings>
    <Setting name="MySetting" value="Value" />
  </ConfigurationSettings>
  <Certificates>      
    <Certificate name="CertificateForSSL" thumbprint="D3E008E45ADCC328CE6BE2AB9AACE2D13F294838" thumbprintAlgorithm="sha1" />
  </Certificates>
</Role>

The handling of service upgrades is described in the Managing upgrades and changes to a Cloud Service and Handling changes to the configuration and topology of a Cloud Service recipes.

In this recipe, we'll learn how to configure the service model for a sample application.

<ServiceDefinition name="WAHelloWorld" upgradeDomainCount="20"…