Share via

Expose role configuration settings as an environment variable with XPath

  • Article
  • 07/23/2024

Important

Cloud Services (classic) is now deprecated for all customers as of September 1st, 2024. Any existing running deployments will be stopped and shut down by Microsoft and the data will be permanently lost starting October 2024. New deployments should use the new Azure Resource Manager based deployment model Azure Cloud Services (extended support).

In the cloud service worker or web role service definition file, you can expose runtime configuration values as environment variables. The following XPath values are supported (which correspond to API values).

These XPath values are also available through the Microsoft.WindowsAzure.ServiceRuntime library.

App running in emulator

Indicates that the app is running in the emulator.

Type Example
XPath xpath="/RoleEnvironment/Deployment/@emulated"
Code var x = RoleEnvironment.IsEmulated;

Deployment ID

Retrieves the deployment ID for the instance.

Type Example
XPath xpath="/RoleEnvironment/Deployment/@id"
Code var deploymentId = RoleEnvironment.DeploymentId;

Role ID

Retrieves the current role ID for the instance.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/@id"
Code var id = RoleEnvironment.CurrentRoleInstance.Id;

Update domain

Retrieves the update domain of the instance.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/@updateDomain"
Code var ud = RoleEnvironment.CurrentRoleInstance.UpdateDomain;

Fault domain

Retrieves the fault domain of the instance.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/@faultDomain"
Code var fd = RoleEnvironment.CurrentRoleInstance.FaultDomain;

Role name

Retrieves the role name of the instances.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/@roleName"
Code var rname = RoleEnvironment.CurrentRoleInstance.Role.Name;

Config setting

Retrieves the value of the specified configuration setting.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/ConfigurationSettings/ConfigurationSetting[@name='Setting1']/@value"
Code var setting = RoleEnvironment.GetConfigurationSettingValue("Setting1");

Local storage path

Retrieves the local storage path for the instance.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/LocalResources/LocalResource[@name='LocalStore1']/@path"
Code var localResourcePath = RoleEnvironment.GetLocalResource("LocalStore1").RootPath;

Local storage size

Retrieves the size of the local storage for the instance.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/LocalResources/LocalResource[@name='LocalStore1']/@sizeInMB"
Code var localResourceSizeInMB = RoleEnvironment.GetLocalResource("LocalStore1").MaximumSizeInMegabytes;

Endpoint protocol

Retrieves the endpoint protocol for the instance.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/Endpoints/Endpoint[@name='Endpoint1']/@protocol"
Code var prot = RoleEnvironment.CurrentRoleInstance.InstanceEndpoints["Endpoint1"].Protocol;

Endpoint IP

Gets the specified endpoint's IP address.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/Endpoints/Endpoint[@name='Endpoint1']/@address"
Code var address = RoleEnvironment.CurrentRoleInstance.InstanceEndpoints["Endpoint1"].IPEndpoint.Address

Endpoint port

Retrieves the endpoint port for the instance.

Type Example
XPath xpath="/RoleEnvironment/CurrentInstance/Endpoints/Endpoint[@name='Endpoint1']/@port"
Code var port = RoleEnvironment.CurrentRoleInstance.InstanceEndpoints["Endpoint1"].IPEndpoint.Port;

Example

Here's an example of a worker role that creates a startup task with an environment variable named TestIsEmulated set to the @emulated xpath value.

<WorkerRole name="Role1">
    <ConfigurationSettings>
      <Setting name="Setting1" />
    </ConfigurationSettings>
    <LocalResources>
      <LocalStorage name="LocalStore1" sizeInMB="1024"/>
    </LocalResources>
    <Endpoints>
      <InternalEndpoint name="Endpoint1" protocol="tcp" />
    </Endpoints>
    <Startup>
      <Task commandLine="example.cmd inputParm">
        <Environment>
          <Variable name="TestConstant" value="Constant"/>
          <Variable name="TestEmptyValue" value=""/>
          <Variable name="TestIsEmulated">
            <RoleInstanceValue xpath="/RoleEnvironment/Deployment/@emulated"/>
          </Variable>
          ...
        </Environment>
      </Task>
    </Startup>
    <Runtime>
      <Environment>
        <Variable name="TestConstant" value="Constant"/>
        <Variable name="TestEmptyValue" value=""/>
        <Variable name="TestIsEmulated">
          <RoleInstanceValue xpath="/RoleEnvironment/Deployment/@emulated"/>
        </Variable>
        ...
      </Environment>
    </Runtime>
    ...
</WorkerRole>

Next steps

Learn more about the ServiceConfiguration.cscfg file.

Create a ServicePackage.cspkg package.

Enable remote desktop for a role.