Home Library Learn Downloads Support Community
Sign in | United States - English | |
This topic has not yet been rated Rate this topic

WebRole Schema

Updated: November 10, 2011

[This topic contains preliminary content for the current release of Windows Azure.]

The Windows Azure web role is a role that is customized for web application programming as supported by IIS 7, such as ASP.NET, PHP, Windows Communication Foundation, and FastCGI.

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

The basic format of a service definition file containing a web role is as follows.

XML
Copy 

<ServiceDefinition name="<service-name>" xmlns=”http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition” upgradeDomainCount="<number-of-upgrade-domains>">
  <WebRole name="<web-role-name>" vmsize="[ExtraSmall|Small|Medium|Large|ExtraLarge]" enableNativeCodeExecution="[true|false]">
    <Certificates>
      <Certificate name="<certificate-name>" storeLocation="<certificate-store>" storeName="<store-name>" />
    </Certificates>    
    <ConfigurationSettings>
      <Setting name="<setting-name>" />
    </ConfigurationSettings>
    <Imports>
      <Import moduleName="<import-module>"/>
    </Imports>
    <InputEndpoints >
        <InputEndpoint certificate="<certificate-name>" ignoreRoleInstanceStatus="[true|false]" name="<input-endpoint-name>" protocol="[http|https]" localPort="<port-number>" port="<port-number>" />
    </InputEndpoints>
    <Endpoints>
      <InputEndpoint certificate="<certificate-name>" ignoreRoleInstanceStatus="[true|false]" name="<input-endpoint-name>" protocol="[http|https|tcp]" localPort="<port-number>" port="<port-number>" />
      <InternalEndpoint name="<internal-endpoint-name>" protocol="[http|tcp]" port="<port-number>">
         <FixedPort port="<port-number>"/>
         <FixedPortRange min="<minium-port-number>" max="<maximum-port-number>"/>
      </InternalEndpoint>
    </Endpoints>
    <LocalResources>
      <LocalStorage name="<local-store-name>" cleanOnRoleRecycle="[true|false]" sizeInMB="<size-in-megabytes>" />
    </LocalResources>
    <LocalStorage name="<local-store-name>" cleanOnRoleRecycle="[true|false]" sizeInMB="<size-in-megabytes>" />
    <Runtime executionContext="[limited|elevated]">
      <Environment>
         <Variable name="<variable-name>" value="<variable-value>">
            <RoleInstanceValue xpath="<xpath-to-role-environment-settings>"/>
          </Variable>          
      </Environment>
      <EntryPoint>
         <NetFxEntryPoint assemblyName="<name-of-assembly-containing-entrypoint>" targetFrameworkVersion="<.net-framework-version>"/>
      </EntryPoint>
    </Runtime>
    <Sites>
      <Site name="<web-site-name>">
        <VirtualApplication name="<application-name>" physicalDirectory="<directory-path>"/>
        <VirtualDirectory name="<directory-path>" physicalDirectory="<directory-path>"/>
        <Bindings>
          <Binding name="<binding-name>" endpointName="<endpoint-name-bound-to>" hostHeader="<url-of-the-site>"/>
        </Bindings>
      </Site>
    </Sites>
    <Startup priority="<for-internal-use-only>”>
      <Task commandLine="<command-to=execute>" executionContext="[limited|elevated]" taskType="[simple|foreground|background]">
        <Environment>
         <Variable name="<variable-name>" value="<variable-value>">
            <RoleInstanceValue xpath="<xpath-to-role-environment-settings>"/>
          </Variable>          
        </Environment>
      </Task>
    </Startup>
    <Contents>
      <Content destination="<destination-folder-name>" >
        <SourceDirectory path="<local-source-directory>" />
      </Content>
    </Contents>
  </WebRole>
</ServiceDefinition>

The XML namespace for the service definition file is:

Copy 
http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition

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

The following table describes the attributes of the ServiceDefinition element:

 

Attribute Type Description

name

string

Required. The name of the service. The name must be unique within the service account.

upgradeDomainCount

integer

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 How to Perform In-Place Upgrades on a Hosted Service in Windows Azure.

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

The service definition file must contain one ServiceDefinition element.

The ServiceDefinition element may include any number of WebRole.

The WebRole element describes a role that is customized for web application programming, as supported by IIS 7 and ASP.NET. A service may contain zero or more web roles.

The following table describes the attributes of the WebRole element:

 

Attribute Type Description

name

string

Required. The name for the web role. The role's name must be unique.

enableNativeCodeExecution

boolean

Optional. The default value is true; native code execution and full trust are enabled by default. Set this attribute to false to disable native code execution for the web role, and use Windows Azure partial trust instead.

For more information on trust policies, see FastCGI and Full Trust Support in Windows Azure and Windows Azure Partial Trust Policy Reference.

vmsize

string

Optional. Set this value to change the size of the VM allotted to this role. The default value is Small. Other possible values are ExtraSmall, Medium, Large, and ExtraLarge.

For more information on configuring the virtual machine size, see How to Configure Virtual Machine Sizes.

The ConfigurationSettings element describes the collection of configuration settings for a web. This element is the parent element of the Setting Element.

The Setting element describes a name/value pair that specifies a configuration setting for an instance of a role.

The following table describes the attributes of the Setting element:

 

Attribute Type Description

name

string

Required. A unique name for the configuration setting.

The configuration settings for a role are name/value pairs that are declared in the service definition file and set in the service configuration file.

The LocalResources element describes the collection of local storage resources for a web role. This element is the parent element of the LocalStorage Element.

The LocalStorage element identifies a local storage resource that provides file system space for the service at runtime. A role may define zero or more local storage resources.

noteNote
The LocalStorage element can appear as a child of the WebRole element to support compatibility with earlier versions of the Windows Azure SDK.

The following table describes the attributes of the LocalStorage element:

 

Attribute Type Description

name

string

Required. A unique name for the local store.

cleanOnRoleRecycle

boolean

Optional. Indicates whether the local store should be cleaned when the role is restarted. Default value is true.

sizeInMb

int

Optional. The desired amount of storage space to allocate for the local store, in MB. If not specified, the default storage space allocated is 100 MB. The minimum amount of storage space that may be allocated is 1 MB.

The maximum size of the local resources is dependent on the virtual machine size. For more information, see How to Configure Virtual Machine Sizes.

The name of the directory allocated to the local storage resource corresponds to the value provided for the name attribute. For more information on accessing a local storage resource from code running within a role instance, see How to Configure Local Storage Resources.

The Endpoints element describes the collection of input (external) and internal endpoints for a role. This element is the parent element of the InputEndpoint and InternalEndpoint elements.

Input and Internal endpoints are allocated separately. A service can have a total of 25 input endpoints and 25 internal endpoints which can be allocated across the 25 roles allowed in a service. For example, if have 5 roles you can allocate 5 input endpoints per role or you can allocate 25 input endpoints to a single role or you can allocate 1 input endpoint each to 25 roles.

noteNote
Each role deployed requires one instance per role. The default provisioning for a subscription is limited to 20 cores and thus is limited to 20 instances of a role. If your application requires more instances than is provided by the default provisioning see Billing, Subscription Management and Quota Support for more information on increasing your quota.

The InputEndpoints element describes the collection of external input endpoints for a role. This element is the parent element of the InputEndpoint element in the service definition for a role. The InputEndpoints element is deprecated use the Endpoints element instead.

The InputEndpoint element describes an external endpoint to a web role.

You can define multiple endpoints that are a combination of HTTP, HTTPS, and TCP endpoints.

You can specify any port number you choose for an input endpoint, but the port numbers specified for each role in the service must be unique. For example, if you specify that a web role uses port 80 for HTTP and port 443 for HTTPS, you might then specify that a second web role uses port 8080 for HTTP and port 8043 for HTTPS. For more information on using endpoints, see Overview of Enabling Communication for Role Instances.

The parent element of the InputEndpoint element is either the Endpoints Element element or the InputEndpoints element.

The following table describes the attributes of the InputEndpoint element:

 

Attribute Type Description

name

string

Required. A unique name for the external endpoint.

protocol

string

Required. The transport protocol for the external endpoint. For a web role, possible values are HTTP, HTTPS, or TCP.

noteNote
TCP is only supported when the input endpoint is defined as a child of the Endpoints element.

port

int

Required. The port for the external endpoint. You can specify any port number you choose, but the port numbers specified for each role in the service must be unique.

certificate

string

Required for an HTTPS endpoint. The name of a certificate defined by a Certificate Element.

localPort

int

Optional. Specifies a port used for internal connections on the endpoint. The localPort attribute maps the external port on the endpoint to an internal port on a role. This is useful in scenarios where a role must communicate to an internal component on a port that different from the one that is exposed externally.

If not specified, the value of Set localPort is the same as the one set in the port attribute. Set localPort to “*” to allow the Windows Azure fabric is assigns an unallocated port that is discoverable using the runtime API.

noteNote
The localPort attribute is only available using the Windows Azure SDK version 1.3 or higher.

ignoreRoleInstanceStatus

boolean

Optional. When the value of this attribute is set to true, the status of a service is ignored and the endpoint will not be removed by the load balancer. The default value is false.

Setting this value to true useful for debugging busy instances of a service.

noteNote
An endpoint can still receive traffic even when the role is not in a Ready state.

The InternalEndpoint element describes an internal endpoint to a web role. An internal endpoint is available only to other role instances running within the service; it is not available to clients outside the service. For more information on using endpoints, see Overview of Enabling Communication for Role Instances.

noteNote
Web roles that do not include the Sites element can only have a single HTTP or TCP internal endpoint.

The following table describes the attributes of the InternalEndpoint element:

 

Attribute Type Description

name

string

Required. A unique name for the internal endpoint.

protocol

string

Required. The transport protocol for the internal endpoint. Possible values are HTTP or tcp.

port

int

Optional. The port used for internal load balanced connections on the endpoint. A Load balanced endpoint uses two ports. The port used for the public IP address, and the port used on the private IP address. Typically these are these are set to the same, but you can choose to use different ports.

noteNote
The Port attribute is only available using the Windows Azure SDK version 1.3 or higher.

The FixedPort element specifies the port for the internal endpoint. The FixedPort element sets the port used for load balanced connections on the endpoint.

noteNote
The FixedPort element is only available using the Windows Azure SDK version 1.3 or higher.

 

Attribute Type Description

port

int

Required. The port for the internal endpoint. This has the same effect as setting the FixedPortRange min and max to the same port.

The FixedPortRange element specifies the range of ports for the Windows Azure fabric to use to assign the internal endpoint. The FixedPortRange element sets the port used for load balanced connections on the endpoint.

noteNote
The FixedPortRange element is only available using the Windows Azure SDK version 1.3 or higher.

 

Attribute Type Description

min

int

Required. The minimum port in the range.

max

string

Required. The maximum port in the range.

The Certificates element describes the collection of certificates for a web role. It is the parent element of the Certificate element. A role may have any number of associated certificates. For more information on using the certificates element, see How to Associate a Certificate with a Service.

The Certificate element describes a certificate that is associated with a web role.

The following table describes the attributes of the Certificate element:

 

Attribute Type Description

name

string

Required. A name for this certificate, which is used to refer to it when it is associated with an HTTPS InputEndpoint element.

storeLocation

string

Required. The location of the certificate store where this certificate may be found on the local machine. Possible values are CurrentUser and LocalMachine.

storeName

string

Required. The name of the certificate store where this certificate resides on the local machine. Possible values include the built-in store names My, Root, CA, Trust, Disallowed, TrustedPeople, TrustedPublisher, AuthRoot, AddressBook, or any custom store name. If a custom store name is specified, the store is automatically created.

permissionLevel

string

Optional. Specifies the access permissions given to the role processes. If you want only elevated processes to be able to access the private key, then specify elevated permission. limitedOrElevated permission allows all role processes to access the private key. Possible values are limitedOrElevated or elevated. The default value is limitedOrElevated.

The Imports element describes a collection of import modules for a web role that add components to the guest operating system. It is the parent element of the import element. This element is optional and a role can have only one runtime block.

noteNote
The Imports element is only available using the Windows Azure SDK version 1.3 or higher.

The Import element specifies a module to add to the guest operating system.

noteNote
The Import element is only available using the Windows Azure SDK version 1.3 or higher.

The following table describes the attributes of the Import element:

 

Attribute Type Description

moduleName

string

Required. The name of the module to import. Valid import modules are:

  • RemoteAccess

  • RemoteForwarder

  • Diagnostics

  • Connect

The RemoteAccess and RemoteForwarder modules allow you to configure your role instance for remote desktop connections. For more information see Overview of Setting Up a Remote Desktop Connection for a Role.

The Diagnostics module allows you to collect diagnostic data for a role instance. For more information see How to Initialize the Windows Azure Diagnostic Monitor.

The Connect module allows you to configure IPsec protected connections between computers or virtual machines (VMs) in your organization’s network, and roles running in Windows Azure. For more information see How to: Configure Windows Azure Connect.

The Runtime element describes a collection of environment variable settings for a web role that control the runtime environment of the Windows Azure host process. It is the parent element of the Environment element. This element is optional and a role can have only one runtime block.

The following table describes the attributes of the Runtime element:

 

Attribute Type Description

executionContext

string

Optional. Specifies the context in which the Role Process is launched. The default context is limited.

  • limited – The process is launched without Administrator privileges.

  • elevated – The process is launched with Administrator privileges.

noteNote
The Runtime element is only available using the Windows Azure SDK version 1.3 or higher.

The Environment element describes a collection of environment variable settings for a web role. It is the parent element of the Variable element. A role may have any number of environment variables set. Environment variables follow the rules set for Windows Server 2008.

The Variable element specifies an environment variable to set in the guest operating.

noteNote
The Variable element is only available using the Windows Azure SDK version 1.3 or higher.

The following table describes the attributes of the Variable element:

 

Attribute Type Description

name

string

Required. The name of the environment variable to set.

value

string

Optional. The value to set for the environment variable. You must include either a value attribute or a RoleInstanceValue element.

The RoleInstanceValue element specifies the xPath from which to retrieve the value of the variable.

 

Attribute Type Description

xpath

string

Optional. Location path of deployment settings for the instance. For more information, see xPath Values in Windows Azure.

You must include either a value attribute or a RoleInstanceValue element.

The EntryPoint element specifies the entry point for a role. This element is the parent element of the NetFxEntryPoint elements. These elements allow you to specify an application other than the default WaWorkerHost.exe to act as the role entry point.

noteNote
The EntryPoint element is only available using the Windows Azure SDK version 1.5 or higher.

The NetFxEntryPoint element specifies the program to run for a role.

noteNote
The NetFxEntryPoint element is only available using the Windows Azure SDK version 1.5 or higher.

The following table describes the attributes of the NetFxEntryPoint element:

 

Attribute Type Description

assemblyName

string

Required. The path and file name of the assembly containing the entry point. The path is relative to the folder \%ROLEROOT%\Approot (do not specify \%ROLEROOT%\Approot in commandLine, it is assumed). %ROLEROOT% is an environment variable maintained by Windows Azure and it represents the root folder location for your role. The \%ROLEROOT%\Approot folder represents the application folder for your role.

For HWC roles the path is always relative to the \%ROLEROOT%\Approot\bin folder.

For full IIS web roles, if the assembly cannot be found relative to \%ROLEROOT%\Approot folder, the \%ROLEROOT%\Approot\bin is searched.

This fall back behavior for full IIS is not a recommend best practice and maybe removed in future versions.

targetFrameworkVersion

string

Required. The version of the .NET framework on which the assembly was built. For example, targetFrameworkVersion="v4.0".

The Sites element describes a collection of web sites and web applications that are hosted in a web role. It is the parent element of the Site element. If you do not specify a Sites element, your web role is hosted as legacy web role and you can only have one web site hosted in your web role. For more information on configuring the Sites element, see How to Configure a Web Role for Multiple Web Sites. This element is optional and a role can have only one sites block.

noteNote
The Sites element is only available using the Windows Azure SDK version 1.3 or higher.

The following table describes the attributes of the Site element:

The Site element specifies a web site or web application that is part of the web role

noteNote
The Site element is only available using the Windows Azure SDK version 1.3 or higher.

The following table describes the attributes of the Site element:

 

Attribute Type Description

name

string

Required. Name of the web site or application.

physicalDirectory

string

The location of the content directory for the site root. The location can be specified as an absolute path or relative to the .csdef location.

The VirtualApplication element defines an application in Internet Information Services (IIS) 7 is a grouping of files that delivers content or provides services over protocols, such as HTTP. When you create an application in IIS 7, the application's path becomes part of the site's URL.

noteNote
The VirtualApplication element is only available using the Windows Azure SDK version 1.3 or higher.

The following table describes the attributes of the VirtualApplication element:

 

Attribute Type Description

name

string

Required. Specifies a name to identify the virtual application.

physicalDirectory

string

Required. Specifies the path on the development machine that contains the virtual application. In the compute emulator, IIS is configured to retrieve content from this location. When deploying to the Windows Azure, the contents of the physical directory are packaged along with the rest of the service. When the service package is deployed to Windows Azure, IIS is configured with the location of the unpacked contents.

The VirtualApplication element specifies a directory name (also referred to as path) that you specify in IIS and map to a physical directory on a local or remote server.

noteNote
The VirtualDirectory element is only available using the Windows Azure SDK version 1.3 or higher.

The following table describes the attributes of the VirtualDirectory element:

 

Attribute Type Description

name

string

Required. Specifies a name to identify the virtual directory.

value

physicalDirectory

Required. Specifies the path on the development machine that contains the web Site or Virtual directory contents. In the compute emulator, IIS is configured to retrieve content from this location. When deploying to the Windows Azure, the contents of the physical directory are packaged along with the rest of the service. When the service package is deployed to Windows Azure, IIS is configured with the location of the unpacked contents.

The Bindings element describes a collection of bindings for a web site. It is the parent element of the Binding element. The element is required for every Site element. For more information on configuring endpoints, see How to Define Input Endpoints for a Role.

noteNote
The Bindings element is only available using the Windows Azure SDK version 1.3 or higher.

The Binding element specifies configuration information required for requests to communicate with a web site or web application.

noteNote
The Binding element is only available using the Windows Azure SDK version 1.3 or higher.

 

Attribute Type Description

name

string

Required. Specifies a name to identify the binding.

endpointName

string

Required. Specifies the endpoint name to bind to.

hostHeader

string

Optional. Specifies a host name that allows you to host multiple sites, with different host names, on a single IP Address/Port number combination.

The Startup element describes a collection of tasks that run when the role is started. The Startup element can be the parent element of the Variable element. For more information on using the role startup tasks, see How to Configure IIS Components in Windows Azure. This element is optional and a role can have only one startup block.

The following table describes the attribute of the Startup element:

 

Attribute Type Description

priority

int

For internal use only.

The Task element specifies startup task that takes place when the role starts. Startup tasks can be used to perform tasks that prepare the role to run such install software components or run other applications. Tasks execute in the order in which they appear within the Startup element block.

noteNote
The Task element is only available using the Windows Azure SDK version 1.3 or higher.

The following table describes the attributes of the Task element:

 

Attribute Type Description

commandLine

string

Required. A script, such as a CMD file, containing the commands to run.

ImportantImportant
Startup command and batch files must be saved in ANSI format. File formats that set a byte-order marker at the start of the file will not process properly.

executionContext

string

Specifies the context in which the script is run.

  • limited [Default] – Run with the same privileges as the role hosting the process.

  • elevated – Run with administrator privileges.

taskType

string

Specifies the execution behavior of the command.

  • simple [Default] – System waits for the task to exit before any other tasks are launched.

  • background – System does not wait for the task to exit.

  • foreground – Similar to background, except role is not restarted until all foreground tasks exit.

The Contents element describes the collection of content for a web role. This element is the parent element of the Content element.

noteNote
The Contents element is only available using the Windows Azure SDK version 1.5 or higher.

The Content element defines the source location of content to be copied to the Windows Azure virtual machine and the destination path to which it is copied.

noteNote
The Content element is only available using the Windows Azure SDK version 1.5 or higher.

The following table describes the attributes of the Content element:

 

Attribute Type Description

destination

string

Required. Location on the Windows Azure virtual machine to which the content is placed. This location is relative to the folder %ROLEROOT%\Approot.

This element is the parent element of the SourceDirectory element.

The SourceDirectory element defines the local directory from which content is copied. Use this element to specify the local contents to copy to the Windows Azure virtual machine.

noteNote
The SourceDirectory element is only available using the Windows Azure SDK version 1.5 or higher.

The following table describes the attributes of the SourceDirectory element:

 

Attribute Type Description

path

string

Required. Relative or absolute path of a local directory whose contents will be copied to the Windows Azure virtual machine. Expansion of environment variables in the directory path is supported.

See Also

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
port attribute for the InternalEndpoint element
The port attribute of the InternalEndpoint element is documented:

-- Optional. The port used for internal load balanced connections on the endpoint. A Load balanced endpoint uses two ports. The port used for the public IP address, and the port used on the private IP address. Typically these are these are set to the same, but you can choose to use different ports.

This documentation is confusing. The use of the phrase "load balanced" is wrong since internal endpoints are not load balanced. Historically, the IP & port used for internal endpoints was allocated by Windows Azure. This parameter now provides for the port to be specified in configuration. The distinction between internal and input endpoints would be clarified by clarifying the documentation.
History