How to Configure the Guest OS in Windows Azure

It’s an exciting time with the release of Visual Studio 2010, .NET 4 and ASP.NET MVC 2. I made the move to rewriting my Azure Email Queuer Application to ASP.NET MVC and leveraging some Telerik ASP.NET MVC Extension Controls to kick up the project a little bit.

twitterProfilePhoto_bigger In making this move it made it necessary to upgrade from the default Guest OS for my Windows Azure Hosted Service. Luckily I was pointed to the “Windows Azure Guest OS Versions and SDK Compatibility Matrix” by Brent Stineman [@BrentCodeMonkey] which gave me the low down on how to configure Azure for the Guest OS I needed to target.

Here is the how to get the “osVersion” attribute in your Cloud Service Configuration (.cscfg) File.

Generating a Windows Azure Configuration File

Obviously, the easiest way to create a Cloud Service Configuration file for Windows Azure is to use the Visual Studio templates for a Cloud Service.  This is all fine and dandy for those of us that are using the .NET Framework on Azure, but Azure is a Robust Cloud Service Model that allows Open Source Languages like PHP, Python, Ruby and even Java. How do those folks Generate Cloud Service Configuration file?

This task is made simple with the Windows Azure Command-line Tool which is part of the Windows Azure SDK.

In the Azure Command-Line tool, you should start by adding the following to the %PATH%:

C:\Program Files\Windows Azure SDK\v1.1\bin

Here’s where things get fun, using the CSPack.exe file you can use a flag to Generate a Skeleton Windows Azure Configuration File. You’ll have to first save the following Service Definition File (I’m not sure why they don’t have a tool to generate this):

<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="[Service Name]" xmlns="">
  <WebRole name="[Must be a valid folder path]">
      <InputEndpoint name="HttpIn" protocol="http" port="80" />
      <Setting name="DiagnosticsConnectionString" />
  <WorkerRole name="[Must be a valid folder path]">
      <Setting name="DiagnosticsConnectionString" />

Once you’ve replaced the Square Bracketed names with valid data, save the above XML to a file called “ServiceDefinition.csdef”, run the following command in your command-line tool:

c:\samples\HelloWorld>cspack HelloWorld\ServiceDefinition.csdef /generateConfigurationFile:ServiceConfiguration.cscfg

This will probably cause an error as there is a good chance there isn’t an endpoint defined for the Roles. However, It does generate the necessary Cloud Service Configuration File. In order to do the next step you’ll need to deploy a project, this will require that you use cspack to package your configuration to a cspkg file. This can be done using the following:

c:\samples\HelloWorld>cspack HelloWorld\ServiceDefinition.csdef

Got my Configuration File and Package, Now What?

Now We’ll Login to the Windows Azure Development Portal, which currently needs a Windows Live ID to login [The Windows Azure team is looking for feedback on other login methods that would be handy for Cloud login, if you’d like to share your Great Windows Azure Idea].

After you’re created a new Hosted Service to host your application, you’ll have to deploy your project, seen below:


Once the Deployment finishes uploading you will need to hit the configure button.


After deployment, Windows Azure adds some additional configuration settings to the Configuration file. Opening the Configuration file in the Deployment Portal will allow you to modify your deployments configuration, note that this is also the way that you scale up/down the number of running instances of your application.


For this exercise to make sense you will have to Understand Which Windows Azure Guest OS is Required for your application. On the Details page for the Guest OS that you have selected you will see the Configuration Value for the Guest OS which will start with WA-GUEST-OS. Copy the entire value, as  you will be pasting it into the osVersion attribute for your Cloud Service Configuration.

If you specify an osVersion this will keep your deployment targeted to the Guest OS you chose. Note that future service updates may contain patches to the deployment which may fix security vulnerabilities, it is not guaranteed that these patches won’t affect your deployment so each set of security deployments may be hosted under a different Guest OS. You will be able to test out the newest Guest OS in your Staging environment before upgrading your Production deployment.

Happy Coding!