Expose role configuration settings as an environment variable with XPath

Article
08/02/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.

Share via