Azure Cloud Services (classic) Definition Schema (.csdef File)

Important

Cloud Services (classic) is now deprecated for new customers and will be retired on August 31st, 2024 for all customers. New deployments should use the new Azure Resource Manager based deployment model Azure Cloud Services (extended support).

The service definition file defines the service model for an application. The file contains the definitions for the roles that are available to a cloud service, specifies the service endpoints, and establishes configuration settings for the service. Configuration setting values are set in the service configuration file, as described by the Cloud Service (classic) Configuration Schema.

By default, the Azure Diagnostics configuration schema file is installed to the C:\Program Files\Microsoft SDKs\Windows Azure\.NET SDK\<version>\schemas directory. Replace <version> with the installed version of the Azure SDK.

The default extension for the service definition file is .csdef.

Basic service definition schema

The service definition file must contain one ServiceDefinition element. The service definition must contain at least one role (WebRole or WorkerRole) element. It can contain up to 25 roles defined in a single definition and you can mix role types. The service definition also contains the optional NetworkTrafficRules element which restricts which roles can communicate to specified internal endpoints. The service definition also contains the optional LoadBalancerProbes element which contains customer defined health probes of endpoints.

The basic format of the service definition file is as follows.

<ServiceDefinition name="<service-name>" topologyChangeDiscovery="<change-type>" 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>

Schema definitions

The following topics describe the schema:

ServiceDefinition Element

The ServiceDefinition element is the top-level element of the service definition file.

The following table describes the attributes of the ServiceDefinition element.

Attribute Description
name Required. The name of the service. The name must be unique within the service account.
topologyChangeDiscovery Optional. Specifies the type of topology change notification. Possible values are:

- Blast - Sends the update as soon as possible to all role instances. If you choose option, the role should be able to handle the topology update without being restarted.
- UpgradeDomainWalk – Sends the update to each role instance in a sequential manner after the previous instance has successfully accepted the update.
schemaVersion Optional. Specifies the version of the service definition schema. The schema version allows Visual Studio to select the correct SDK tools to use for schema validation if more than one version of the SDK is installed side-by-side.
upgradeDomainCount Optional. Specifies the number of upgrade domains across which roles in this service are allocated. Role instances are allocated to an upgrade domain when the service is deployed. For more information, see Update a cloud service role or deployment, Manage the availability of virtual machines and What is a Cloud Service Model.

You can specify up to 20 upgrade domains. If not specified, the default number of upgrade domains is 5.