Windows Azure Start-up Tasks Part 1

 

I find myself several times a week having conversations with people around the ability to install and configure additional software on Windows Azure™ Web and Worker roles.  This key piece of functionality provides a mechanism for you to setup the environment the way you require and still gain the benefits of Platform as a Service. 

I am writing this as a series of posts starting with the basics eventually leading to samples of how to deal with specific scenarios.

The Basics
Installation of software and features can be done through start-up tasks which run before the OnStart() method is called.  You create a list of tasks that will be executed in the order provided.  The role will not become available until all of the tasks in the list have been launched.   There are several types of start-up tasks that you have to choose from depending on the behavior you desire such as blocking or non-blocking.

1. Simple tasks are the most commonly used.  This task type will execute the specified command and wait for it to return before launching the next task in the list.  This is great when you have an ordered set of installs etc. that must occur before the instance becomes available.
2. Background tasks are used to start processes that are not required to be complete before the instance becomes available.  When the command is launched it will execute in the background and the next task in the list will be processed.
3. Foreground tasks are the same as background tasks with the one caveat, the instance cannot be stopped while the foreground task is running.  The interesting behavior with this is that although you cannot stop the instance that has a running foreground task you can remove it.  So if you had 3 instances running and decided to drop the instance count to 2 the instance with the running foreground task could be shutdown.

The OnStart() method will be executed once all of the tasks in the list have been launched and all simple tasks have completed.

In order to configure these tasks you need to open your ServiceDefinition.csdef file and find the element representing the role you want to add them to.

  
Based on the XML definition above we will be working with the Worker Role named StDemo.  Add a child element named Start-up that will contain the task list.  Create a child element named task for each start-up tasks you wish to launch.

 

 

In the image above you can see that we have created 2 start-up tasks, the first one defining the following elements:

1. commandLine: is the command to be executed, format this as you would when executing it from the command line.  In this case it will execute the file in the current directory named startup.cmd.
2. executionContext: indicates whether to run the code as the standard or elevated user in the event it requires  administrative permissions.  In this case we are running it as an administrator (elevated).
3. taskType: indicates the type of start-task it is.  In this case it is a simple task meaning it will block until it returns only running the second task when and if it completes.

Including the Files
Looking at the first task you will notice it is running a file named Startup.cmd but we have not added it to the deployment package yet.  I have run into encoding issues with cmd files created in Visual Studio so rather that playing with encoding I simply create the file in notepad first.  To add the file to Visual Studio 2010 perform the following steps:

1. In Solution Explorer open the project that represents the worker role.  In the case of this demo it is StDemo.
2. Right click on the project and select add -> Existing Item
3. Browse to the file you want to add remembering that you may want to change the file filter to show in our case files with a “cmd” file extension.
4. Select the file you just added in the solution explorer and navigate to the properties window.
5. Change the “Build Action” to “Content”
6. Change the “Copy to Output Directory” to “Copy always”

The changes performed will make Visual Studio add it to the package when it is created.  Remember that when using the Worker Role or Web Role in Hosted Core mode these files will be put into the %RoleRoot%\approot folder on the instance.  If this is a Web Role in full IIS mode (sites are defined) it will be added to the %RoleRoot%\Sitex where x is replaced by the site number (0 based).  This can be important to understand when building your script files.

 

When using start-up tasks knowing the Operating System family can be important (ex. Windows 2008 or Windows 2008 R2).  If you want to change the family you can do it in the configuration file.  Remember if you are changing it to do it in both the local and cloud or may have some frustrations determining why your script runs in the development environment but not in the cloud.  The following image shows where to change the Operating System family in your configuration file.

 

An osFamily of 1 is Windows Server 2008 while 2 is Windows Server 2008 R2.  If you choose Windows Server 2008 R2 you can leverage PowerShell 2 by default which is very nice to build start-up tasks in.

As you can see by leveraging start-up tasks some of the scenarios where PaaS does not seem to fit become attainable.  This is a great yet often overlooked feature that every Windows Azure™ Developer should become familiar with.

I hope you found this post helpful and read more on this in my next post “Windows Azure Start-up Tasks Part 2”.