« February 2011 | Main | May 2011 »

March 2011

March 28, 2011

What Environment Variables Can You Use in Windows Azure?

Yesterday I found the following forum post on Windows Azure Forums: How to get environment variable and information in startup task. At the same time I was prototyping some of our new features, and needed to achieve almost the same goal as in the forum post, hence I decided that it will be useful to publish some more details about what environment variables are available by default in Windows Azure, and how can you use them.

Environment Variables in Windows Azure

You may already know that you can define environment variables per role in Windows Azure Service Definition (CSDEF) file using the Environment tag:



     <Variable name="[my_name]" value="[my_value]" />



CSDEF schema allows you to put the Environment tag it either the Startup task tag or in the Runtime tag. It is important to know that environment variables that are defined for startup tasks are not available in the runtime and the reverse. Hence if you want to have environment variable that can be used in both the startup task and the runtime you need to define it twice.

Here an example for defining environment variables for startup tasks and for your role’s runtime:


<WorkerRole name="MyWorker">
          <Task taskType="background" commandLine="my.cmd"

                    <Variable name="MY_ENV" value="my_value" />
               <Variable name="MY_SECOND_ENV" value="my_value2" />



Pre-Defined Environment Variables in Windows Azure

Of course the more interesting question is what are the pre-defined environment variables in Windows Azure, and whether you can leverage those. I wrote a simple Web Role that uses System.Environment.GetEnvironmentVariables(), iterates through all of them and prints them in a web page. Majority of the variables are standard Windows environment variables but here are some Windows Azure specific ones (Note: Those variables are specific to the process in which your role runs):

  • @AccountUsername ** – this is the username you can use for Remote Desktop connection to the role instance
  • @AccountEncryptedPassword ** – this is the encrypted password that you can use for Remote Desktop connection to the role instance. The password is encrypted using the SSL certificate for your Hosted Service
  • @AccountExpiration ** – this is the timestamp when the Remote Desktop account expires
  • @ConnectionString – is the diagnostics connection string for access to Windows Azure Storage. This is the configuration that you defined in the Service Configuration (CSCFG) file for your deployment. You can change this by modifying your CSCFG file.
  • DiagnosticStore – this is the location where diagnostics information is stored locally before transferred to the Windows Azure storage account
  • RdRoleId – this is the really unique identifier of the role instance. This information is not available in the Management Portal and it is build by concatenating the RoleDeploymentID and the RoleInstanceID.
    Example: eaaa6a386255466dada9dd158c5d4008.WebTest_IN_0
  • RdRoleRoot – is is the same as the RoleRoot above
  • RoleDeploymentID * – is the deployment identifier for your deployment and it is the same one you see in the Windows Azure Management Portal. This is the same for each role and role instance.
    Example: eaaa6a386255466dada9dd158c5d4008
  • RoleInstanceID * – is the unique identifier of the role instance. The instance ID uses the RoleName as a prefix. 
    Example: WebTest_IN_0
  • RoleName * – this is the role name.
    Example: WebTest
  • RoleRoot – this is maybe the most important environment variable in Windows Azure, or at least the one that you need the most. It points to the root where your Windows Azure role code is placed. Very often you will want to access some resource files for your role using %RoleRoot%\AppRoot.
  • __WaRuntimeAgent__ – this is the identifier for the runtime agent that is used by the Fabric controller to monitor your role. Again, it is very unlikely that you will need this one
  • WA_CONTAINER_SID – this is the system identifier of the Windows Azure container. It is very unlikely you will need this one


All environment variables marked with asterisk (*) above are available as properties in Windows Azure Management Portal.

You can change the environment variables marked with double asterisks (**) above by clicking on the role in Windows Azure Management Portal and then on Configure Remote Access.

Also, most of the information stored in the environment variables is available through the Windows Azure Runtime APIs. However those environment variables are accessible from both your role’s startup tasks as well as from the runtime.


Windows Azure Full IIS Mode and Environment Variables

One thing to remember is that if you use Full IIS Mode in Windows Azure you will NOT be able to access the environment variables mentioned above. The reason for that is that you should use the standard IIS programing techniques to access your environment. You will know that you are running in Full IIS Mode if you have the Site element in your Service Definition file.