Run Startup Tasks in Windows Azure
Updated: November 13, 2013
You can use startup tasks to perform operations before a role starts. Operations that you might want to perform include installing a component, registering COM components, setting registry keys, or starting a long running process.
|Startup tasks are not applicable to VM roles.|
How startup tasks work
Startup tasks are actions that are taken before your roles begin. Startup tasks are defined in the ServiceDefinition.csdef file by using the Task element within the Startup element. Frequently startup tasks are batch files, but they can also be console applications, or batch files that start PowerShell scripts.
Environment variables pass information into a startup task, and local storage can be used to pass information out of a startup task. For example, an environment variable can specify the path to a program you want to install, and files can be written to local storage that can then be read later by your roles.
Your startup task can log information and errors to the directory specified by the TEMP environment variable. During the startup task, the TEMP environment variable resolves to the C:\Resources\temp\<guid>.<rolename>\RoleTemp directory when running on the cloud.
|After the startup task completes, the TEMP environment variable will change to point to a different directory. Therefore, the TEMP directory is not suitable for storing data at startup that will be accessed later by the role. Use local storage to store data that will be accessed later by the role.|
Startup tasks can also be executed several times between reboots. For example, the startup task will be run each time the role recycles, and role recycles may not always include a reboot. Startup tasks should be written in a way that allows them to run several times without problems.
Startup tasks must end with an errorlevel (or exit code) of zero for the startup process to complete. If a startup task ends with a non-zero errorlevel, the role will not start.
Role startup order in Windows Azure
The following lists the role startup procedure in Windows Azure:
The instance is marked as Starting and does not receive traffic.
All startup tasks are executed according to their taskType attribute.
The simple tasks are executed synchronously, one at a time.
The background and foreground tasks are started asynchronously, parallel to the startup task.
Warning IIS may not be fully configured during the startup task stage in the startup process, so role-specific data may not be available. Startup tasks that require role-specific data should use Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart.
- The simple tasks are executed synchronously, one at a time.
The role host process is started and the site is created in IIS.
The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.OnStart method is called.
The instance is marked as Ready and traffic is routed to the instance.
The Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint.Run method is called.
Example of a startup task
Startup tasks are defined in the ServiceDefinition.csdef file, in the Task element. The commandLine attribute specifies the name and parameters of the startup batch file or console command, the executionContext attribute specifies the privilege level of the startup task, and the taskType attribute specifies how the task will be executed.
In this example, an environment variable, MyVersionNumber, is created for the startup task and set to the value "22.214.171.124".
<Startup> <Task commandLine="Startup.cmd" executionContext="limited" taskType="simple" > <Environment> <Variable name="MyVersionNumber" value="126.96.36.199" /> </Environment> </Task> </Startup>
In the following example, the Startup.cmd batch file writes the line "The current version is 188.8.131.52" to the StartupLog.txt file in the directory specified by the TEMP environment variable. The
EXIT /B 0 line ensures that the startup task ends with an errorlevel of zero.
|In Visual Studio, the Copy to Output Directory property for your startup batch file should be set to Copy Always to be sure that your startup batch file is properly deployed to your project on Windows Azure (approot\bin for Web roles, and approot for worker roles).|
Description of Task attributes
The following describes the attributes of the Task element in the ServiceDefinition.csdef file:
commandLine - Specifies the command line for the startup task:
The command, with optional command line parameters, which begins the startup task.
Frequently this is the filename of a .cmd or .bat batch file.
Can be a console application or a batch file that starts a PowerShell script. For specific information on using a PowerShell script as a startup task, see Use a PowerShell Script as a Startup Task.
executionContext - Specifies the privilege level for the startup task. The privilege level can be limited or elevated:
limited - The startup task runs with the same privileges as the role. When the executionContext attribute for the Runtime element is also limited, then user privileges are used.
elevated - The startup task runs with administrator privileges. This allows startup tasks to install programs, make IIS configuration changes, perform registry changes, and other administrator level tasks, without increasing the privilege level of the role.
|The privilege level of a startup task can be greater than the privilege level of a role. A startup task may use elevated privileges to install programs or make changes to IIS settings, while a role may use limited privileges for security reasons.|
taskType - Specifies the way a startup task is executed.
simple tasks are executed synchronously, one at a time, in the order specified in the ServiceDefinition.csdef file. When one simple startup task ends with an errorlevel of zero, the next simple startup task is executed. If there are no more simple startup tasks to execute, then the role itself will be started.To ensure that your batch file ends with an errorlevel of zero, execute the command
Note If the simple task ends with a non-zero errorlevel, the instance will be blocked. Subsequent simple startup tasks, and the role itself, will not start.
EXIT /B 0at the end of your batch file process.
background tasks are executed asynchronously, in parallel with the startup of the role.
foreground tasks are executed asynchronously, in parallel with the startup of the role. The key difference between a foreground and a background task is that a foreground task keeps the role running while the foreground task runs. This also means that if the foreground task does not end, then the role will not shut down or recycle. The background tasks do not have this restriction, so roles can be recycled even though the background tasks have not completed.
Environment variables are a way to pass information to a startup task. For example, you can put the path to a blob that contains a program to install, or port numbers that your role will use, or settings to control features of your startup task.
There are two kinds of environment variables for startup tasks; static environment variables and environment variables based on members of the RoleEnvironment class. Both are in the Environment section of the ServiceDefinition.csdef file, and both use the Variable element and name attribute.
Static environment variables uses the value attribute of the Variable element. The example above creates the environment variable MyVersionNumber which has a static value of "184.108.40.206". Another example would be to create a StagingOrProduction environment variable which you can manually set to values of "staging" or "production" to perform different startup actions based on the value of the StagingOrProduction environment variable.
Environment variables based on members of the RoleEnvironment class do not use the value attribute of the Variable element. Instead, the RoleInstanceValue child element, with the appropriate xPath attribute value, are used to create an environment variable based on a specific member of the RoleEnvironment class. Values for the xPath attribute to access various RoleEnvironment values can be found in xPath Values in Windows Azure.
For example, to create an environment variable that is "true" when the instance is running in the compute emulator, and "false" when running in the cloud, use the following Variable and RoleInstanceValue elements:
<Startup> <Task commandLine="Startup.cmd" executionContext="limited" taskType="simple"> <Environment> <!-- Create the environment variable that informs the startup task whether it is running in the Compute Emulator or in the cloud. "%ComputeEmulatorRunning%"=="true" when running in the Compute Emulator, "%ComputeEmulatorRunning%"=="false" when running in the cloud. --> <Variable name="ComputeEmulatorRunning"> <RoleInstanceValue xpath="/RoleEnvironment/Deployment/@emulated" /> </Variable> </Environment> </Task> </Startup>
ConceptsStrategies for Writing Startup Tasks that can run Multiple Times
Best Practices for Startup Tasks
Define Startup Tasks for a Role
Define Environment Variables Before a Role Starts
Use Local Storage to Store Files During Startup
Make a Startup Task Perform Different Actions on the Compute Emulator and the Cloud
Use AppCmd.exe to Configure IIS at Startup
Add Firewall Rules By Using a Startup Task