5 out of 16 rated this helpful - Rate this topic

Windows Azure Service Configuration Schema (.cscfg File)

Updated: June 7, 2012

The service configuration file specifies the number of role instances to deploy for each role in the service, the values of any configuration settings, and the thumbprints for any certificates associated with a role. If the service includes a Windows Azure virtual machine, the service configuration file specifies the VHD from which the virtual machine is created. If the service is part of a virtual network, configuration information for the virtual network must be provided in the service configuration file, as well as in the virtual networking configuration file.

The service model itself is described by the Windows Azure Service Definition Schema (.csdef File).

By default, the Windows 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 Windows Azure SDK.

The default extension for the service configuration file is .cscfg.

For more information about how to configuring roles in a service, see How To: Configure the Roles for a Windows Azure Application with Visual Studio

Basic Service Configuration Schema

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


<ServiceConfiguration serviceName="<service-name>" osFamily="[1|2]" osVersion="<os-version>" schemaVersion="<schema-version>">
  <Role …>
         …
  </Role>
  <NetworkConfiguration>  
         …
  </NetworkConfiguration>
</ServiceConfiguration>

Schema definitions

The following topics describe the schema for the ServiceConfiguration node.

Role Schema

NetworkConfiguration Schema

Service Configuration Namespace

The XML namespace for the service configuration file is:

http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration

ServiceConfiguration Element

The ServiceConfiguration element is the top-level element of the service configuration file.

The following table describes the attributes of the ServiceConfiguration element:

Attribute Type Description

serviceName

string

Required. The name of the service. The name given here must match the name specified in the service definition file.

osFamily

string

Optional. The OS family that the service will run under. Valid values are as follows.

1 – Specifies the OS family that is substantially compatible with Windows Server 2008 SP2.
2 – Specifies the OS family that is substantially compatible with Windows Server 2008 R2.
3 – Specifies the OS family that is substantially compatible with Windows Server 2012.

If you do not include a osFamily value and you have not set the osVersion attribute to a specific Windows Azure Guest OS version, a default value of 1 is used. This attribute is ignored by VM roles.

osVersion

string

Optional. The version of the Windows Azure Guest OS on which this service should run. The Windows Azure Guest OS that you specify must be compatible with the version of the Windows Azure SDK with which you developed it; see the Windows Azure Guest OS Versions and SDK Compatibility Matrix for a matrix of compatible versions.

You have two options for handling upgrades to the Windows Azure Guest OS:

You can specify that Windows Azure should automatically upgrade the guest OS when a new version becomes available. Automatically upgrading the guest OS is a recommended best practice. This is the default behavior for handling OS upgrades.
You can opt to manually upgrade the guest OS to your desired version at a time of your choosing.

To specify that the guest OS should be automatically upgraded, set the value of the osVersion attribute to *. When set to *, the hosted service is deployed using the latest version of the guest OS for the specified OS family and will be automatically upgraded when new versions of the guest OS are released.

Note
Automatic upgrading from one OS family to another is not supported. Automatic upgrading of the Guest OS only applies to worker and web roles.

To specify a specific version manually, specify the value of the osVersion attribute in the following format:

WA-GUEST-OS-M.m_YYYYMM-nn

Where:

WA-GUEST-OS is a fixed string
M.m refers to the major and minor versions
YYYY refers to the year
MM refers to the month
nn serves as a sequence number to differentiate between releases which typically supercede previous releases. For more information on superceded releases see Windows Azure Guest OS Versions and SDK Compatibility Matrix

The default value for the osVersion attribute is *.

For details on determining the version on which your service is currently running, see Configure Operating System Versions. To review available versions and determine their compatibility with the Windows Azure SDK, see Windows Azure Guest OS Versions and SDK Compatibility Matrix.

schemaVersion

string

Optional. Specifies the version of the Service Configuration schema used. 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.

The schema version of Windows Azure SDK 1.7 is "2012-05.1.7".

The schemaVersion attribute is only available using the Windows Azure SDK version 1.7 or higher.

The service configuration file must contain one ServiceConfiguration element.

The ServiceConfiguration element may include any number of Role elements and zero or 1 NetworkConfiguration elements.

Windows Azure Service Configuration Schema (.cscfg File)

Basic Service Configuration Schema

Schema definitions

Service Configuration Namespace

ServiceConfiguration Element

See Also

Concepts