Jump to content

Getting Started with Windows Azure

  adfm's Photo
Posted May 24 2010 08:52 AM

If you're a Windows developer curious about Windows Azure, you'll want to check out this excerpt from Sriram Krishnan's Programming Windows Azure. It gets you up to speed with what it takes to set up your first Windows Azure cloud application.

For this example you will create a simple website that contains a solitary HTML page that displays only the text “Hello World!” Since this is just pure HTML, no server-side code is being executed. However, Windows Azure will be doing the heavy lifting in terms of hosting the site, and it is a short step from doing plain HTML to running ASP.NET code (which you’ll see in the next sample).

Let’s start by creating a directory to hold your code. In this example, let’s call it htmlwebsite, as shown here:

D:\>mkdir htmlwebsite

D:\>cd htmlwebsite



Although you can certainly replace htmlwebsite with whatever you feel like, remember to replace all references to the directory name in the commands you’ll be running later on.

This directory will be the root of your website—the equivalent to inetpub/wwwroot in IIS, or the root of your ASP.NET application. Any content you put in here will “hang” off the root URL of your website.

Let’s now create the contents of the website. Create a new file called index.html in the htmlwebsite directory with the contents shown in Example 3.1. (Since this is just a normal HTML page, you can put any valid HTML content you want in here.)

Example 3.1. Über-complex web page



Hello World!



To get Windows Azure to run this trivial site, you must provide two pieces of metadata: the service definition and the service configuration. These are stored in two XML files called ServiceDefinition.csdef and ServiceConfiguration.cscfg, respectively.

Remember that Windows Azure can host any type of code, and provides a ton of configurable knobs/settings for you to tweak. The service definition defines what kind of code your website/service is made of. This is specified when building your service, and can’t be changed dynamically when your application is running. The service configuration contains tweakable settings (the most important one being the number of virtual machines your code will use). These settings can be changed on-the-fly without having to rebuild and redeploy your application.

So, let’s create two files called ServiceDefinition.csdef and ServiceConfiguration.cscfg with the contents of Examples 3.2 and 3.3, respectively.

Example 3.2. Sample ServiceDefinition.csdef

<?xml version="1.0" encoding="utf-8"?>

<ServiceDefinition name="CloudService1"



<span class="strong"><strong><WebRole name="WebRole1" enableNativeCodeExecution="false"></strong></span>


	<InputEndpoint name="HttpIn" protocol="http" port="80" />


	<ConfigurationSettings />



Example 3.3. Sample ServiceConfiguration.cscfg

<?xml version="1.0"?>

<ServiceConfiguration serviceName="CloudService1"



<span class="strong"><strong><Role name="WebRole1"></strong></span>

	<Instances count="1" />

	<ConfigurationSettings />



Chapter 4, Service Model provides more information on these, so it’s not important here to delve into the details of what each element does. In short, the service definition defines a new “web role” called WebRole1. Chapter 4, Service Model provides more on what “roles” are and the different types of roles. For now, simply be aware that a web role is how web applications/sites are packaged and run on Windows Azure. The service configuration file specifies that

] should have one (1) instance, meaning that the code will run on one virtual machine in the cloud.

Packing the Code for the Dev Fabric

You now have all the code you need to run the service on Windows Azure. However, to run applications on Windows Azure (either the production fabric or in the Dev Fabric), you must package the applications in a special format. This lays out your application binaries in a specific folder structure, and generates some files used internally by Windows Azure. Once deployed to the cloud, the Windows Azure fabric opens up this package and runs your code by copying it to the right number of virtual machines, and makes the necessary configuration changes.

You use the cspack.exe tool (or CSPack) that ships with the SDK to perform the packaging. (You can find it in the SDK’s bin directory.) In this case, you first pack the code to run in the Dev Fabric. The command you use to package the application for the cloud is slightly different.


For the cloud, CSPack performs an additional step of zipping all the files and folders into one single file that the Windows Azure fabric extracts. Without this, you would have to upload each file individually to Windows Azure. On the local machine, this step is skipped because the Dev Fabric can just be pointed to the files and folders.

Run the command shown in Example 3.4 from the directory above htmlwebsite (which contains the index.html web page). This will “package” your application code and service definition file into a Windows Azure-understandable format in a directory named output.

Example 3.4. Packing the sample application for the Dev Fabric

D:&#092;><strong class="userinput"><code>cspack htmlwebsite&#092;ServiceDefinition.csdef[/inlinecode]</strong>

	<span class="strong"><strong>/role:WebRole1;htmlwebsite /out:output /copyonly</strong></span>

Windows(R) Azure(TM) Packaging Tool version

for Microsoft(R) .NET Framework 3.5

Copyright (c) Microsoft Corporation. All rights reserved.


This command takes a service definition file, a /role parameter (specifying the role’s name), and its directory, as well as an output location. The /copyonly parameter is specific to the Dev Fabric—it specifies that it should copy the files over, instead of zipping them together. You leave out this parameter when packing for the cloud. If the command executed successfully, you should have an output folder with the structure shown in Figure 3.4.

Figure 3.4. CSPack’s output

Attached Image

Looking at all the files and folders (shown in Example 3.5), you see that this folder essentially contains the files you typed up, as well as some auto-generated files (ServiceDefinition.rd, ServiceDefinition.rdsc, ucruntime.dll) that the Windows Azure fabric uses to run your code.

Example 3.5. Listing of output directory’s contents

D:&#092;>dir /s output

Volume in drive D has no label.

Volume Serial Number is 34DA-B4F3

Directory of D:&#092;output

10/08/2009 04:02 AM	<DIR> 	.

10/08/2009 04:02 AM	<DIR> 	..

10/08/2009 04:02 AM	<DIR> 	roles

10/08/2009 03:57 AM 	489 ServiceDefinition.csdef

10/08/2009 04:02 AM 	3,866 ServiceDefinition.rd

10/08/2009 04:02 AM 	374 ServiceDefinition.rdsc

	3 File(s) 	4,729 bytes

Directory of D:&#092;output&#092;roles

10/08/2009 04:02 AM	<DIR> 	.

10/08/2009 04:02 AM	<DIR> 	..

10/08/2009 04:02 AM	<DIR> 	WebRole1

	0 File(s) 	0 bytes

Directory of D:&#092;output&#092;roles&#092;WebRole1

10/08/2009 04:02 AM	<DIR> 	.

10/08/2009 04:02 AM	<DIR> 	..

10/08/2009 04:02 AM	<DIR> 	bin

10/08/2009 03:54 AM 	109 index.html

10/08/2009 03:57 AM 	276 ServiceConfiguration.cscfg

10/08/2009 03:57 AM 	489 ServiceDefinition.csdef

	3 File(s) 	874 bytes

Directory of D:&#092;output&#092;roles&#092;WebRole1&#092;bin

10/08/2009 04:02 AM	<DIR> 	.

10/08/2009 04:02 AM	<DIR> 	..

07/07/2009 09:11 PM 	18,288 ucruntime.dll

	1 File(s) 	18,288 bytes

	Total Files Listed:

	7 File(s) 	23,891 bytes

	11 Dir(s) 19,353,911,296 bytes free

Running the Code in the Dev Fabric

The final step in creating your first application is to run the packaged application in the Dev Fabric. To do that, run the command shown in Example 3.6. This uses another utility that ships with the SDK, CSRun, to point to the output files and to launch the Dev Fabric with your specified configuration.

Example 3.6. Launching the Dev Fabric

D:&#092;>csrun /run:output;htmlwebsite/ServiceConfiguration.cscfg

Windows(R) Azure(TM) Desktop Execution Tool version

for Microsoft(R) .NET Framework 3.5

Copyright (c) Microsoft Corporation. All rights reserved.

Created deployment(21)

Started deployment(21)

Deployment input endpoint HttpIn of role WebRole1 at

The Dev Fabric acts not only as a simulation of the Windows Azure fabric, but also as a local web server. In this case, as the last line of the command output indicates, it has launched your site at the local URL Since your web page was called index.html, navigate to in any web browser. You should see something similar to Figure 3.5.

Figure 3.5. The sample web page running in a browser

Attached Image


The Dev Fabric’s web server isn’t configured to redirect requests from to However, when you are writing ASP.NET code, redirecting to the default page is done automatically for you.

You now have your first web page running in the Windows Azure Dev Fabric. Since this is essentially a simulation of the cloud, it is a short step from running on the Dev Fabric to running on the actual Windows Azure fabric.

You can click on the Dev Fabric icon in the system tray/notification area to launch the Dev Fabric UI. This shows you what services you have running, as well as health data from each of your roles and instances. For example, in Figure 3.6, you can see that one WebRole is running and that the Dev Fabric’s health checks on it are returning a healthy response.

Figure 3.6. Running the Dev Fabric with our “Hello World” website

Attached Image


Note the little green icon on the left of the screen in Figure 3.6 with the number “0” after it. This denotes the number of running role instances. In the actual cloud, this will correspond to running virtual machines. You can change the number of role instances in the ServiceConfiguration.cscfg file. It is much faster to launch a few dozen role instances in the Dev Fabric (since they are just instances of the RdRoleHost.exe process) than it is to spin them up in the actual Windows Azure fabric. It’s also cheaper!

Running the Code in the Cloud

Now that you have your code up and running in the Dev Fabric, let’s get it running in the actual Windows Azure cloud.

Packaging code for the cloud

You have seen how to use CSPack to package code to run in the Dev Fabric. Packaging for the cloud is the same process, except that the output files and folders are zipped together, and then optionally encrypted. This encryption ensures that only the Windows Azure fabric can crack open the package.

To create a package for upload, you call CSPack again, but without the /copyonly argument. You can call the output package anything you want, but the Windows Azure convention is to tag a .cspkg extension to it. Example 3.7 shows the command you need to run.

Example 3.7. Packaging for the cloud

D:&#092;>cspack htmlwebsite&#092;ServiceDefinition.csdef

	/role:WebRole1;htmlwebsite /out:package.cspkg

Windows(R) Azure(TM) Desktop Execution Tool version

for Microsoft(R) .NET Framework 3.5

Copyright (c) Microsoft Corporation. All rights reserved.

You should now have a file called package.cspkg in your current directory. This is the package you must upload to the cloud to run your service.

Creating a new hosted service project

The Developer Portal is also where you create projects, which are either hosted services (that let you run code) or storage accounts (that let you store data in Windows Azure storage).


Be careful not to confuse Windows Azure “projects” with Visual Studio “projects,” which are two different things.

Log in to the Developer Portal. Click the New Service link appearing in the top right. The portal displays the different kinds of projects available to you, as shown in Figure 3.7. Click Hosted Services.

Figure 3.7. Choice of projects

Attached Image

A hosted service project is essentially a container for running your package in the cloud. Apart from just running your package, it also provides a public URL from which to access your web roles, and provides the ability to upload two packages—one as a staging version that is used for testing, and one as a production version that your users will see. It also provides the ability to deploy upgrades and manage your code. You’ll learn how to manage your service in Chapter 5, Managing Your Service.


In the world of Windows Azure, anything that runs on the Windows Azure fabric is generally called a “service.” This is different from the definition of a “service” used by other parts of the Microsoft ecosystem, where the only “services” are “web services.”

After you click Hosted Services, a new project wizard kicks in. The first step is to enter a label and description for your new hosted service. This is for your use only, so you can go crazy and enter anything you want here. Figure 3.8 shows this screen with some conservative choices for Service Label and Service Description. Once you have entered the information, click Next.

Figure 3.8. Entering service properties

Attached Image

The next step is arguably the most important when creating a new hosted service project. On the next screen shown in Figure 3.9, you pick the service name/URL for your website. This service name must be globally unique across Windows Azure. It is used all across Windows Azure, so pick carefully.

Figure 3.9. Picking a service name/URL

Attached Image

Most important of all, the service name determines at which URL the website will run. The service name is prepended to the domain cloudapp.net, and this URL is used for accessing your service. Note in Figure 3.9 that booksample appears as the service name, which in turn means the service’s final URL will be http://booksample.cloudapp.net.


Since service names are unique, you must use some other service name for this step in creating a new hosted services project.

The screen shown in Figure 3.9 also enables you to pick where your code will be hosted. Windows Azure is present in a few geographic locations at launch, and this list is constantly being expanded as Microsoft builds out infrastructure. You typically want to host your services as close to your end users as possible for the best network performance.

You can also choose to host your services as part of an affinity group, which will place your hosted services close to the Windows Azure storage data that it uses. Let’s ignore this option for now. You’ll learn more about affinity groups when we examine the Windows Azure storage services in Chapter 7.

Once you’ve picked a service name and location, click Create. This will allocate a new hosted service project for you with which you can upload your packages and run them.

Uploading packages

Consider how new builds of a website are deployed in your current environment, or, for that matter, anywhere in the noncloud world. Typically, the build goes first to a staging/testing/preproduction environment where the build is tested. When everything looks good, the build is deployed to the final production environment and goes live.

Windows Azure offers you the same two environments. They’re called deployment slots, and there are two of them: staging (where you deploy your build if you want to test it before it goes live) and production (where the build goes live). Each slot can contain its own package, and each runs separately on its own URL. The production slot runs at the servicename.cloudapp.net URL you picked out, while the staging slot runs at a randomly picked URL of the form .cloudapp.net.

Figure 3.10 shows the two slots represented as two molded cubes on the portal.

Figure 3.10. Production and staging slots

Attached Image

You’ll learn more about how these slots work and how you can switch between the two in Chapter 5, Managing Your Service. For the rest of this example, let’s ignore the staging slot and upload the build directly to production. This is acceptable for a “Hello World” example and trivial applications, but it is almost always a good practice to test your code on staging first.

To upload a package to the production deployment slot, click the Deploy button underneath the production cube to bring up the screen shown in Figure 3.11. This is where you upload the package.cspkg file you created earlier. Click the Browse button to locate and select the package you created earlier.

Figure 3.11. Upload package

Attached Image


The screen shown in Figure 3.11 also supports uploading packages from Windows Azure blob storage. When using the Windows Azure Service Management API (discussed in Chapter 5, Managing Your Service), uploading packages from blob storage is the only mechanism supported. Uploading packages manually through the Developer Portal is great for test applications, but real production applications typically have a build process that publishes their packages to Windows Azure storage, and then uses the management API to deploy them. You can think of the Developer Portal as a wrapper to the functionality provided by the management API.

Every package upload also must have an associated configuration file. This is the ServiceConfiguration.cscfg file you created earlier. This specifies application settings for your service, and, as mentioned earlier, can be changed on-the-fly without having to go through the deployment rigmarole all over again. Most importantly, it controls the number of virtual machines (or role instances, in Windows Azure terminology) your service will use. Under the Configuration Settings portion of this page, browse to the ServiceConfiguration.cscfg file you created earlier and select it.

The final step is to pick a deployment label to uniquely identify the deployment. This can be any text you like (testdeployment has been used in Figure 3.11), but it typically contains a build number or some versioning information.

Click Deploy to kick off the process. You should see a wait cursor and a progress bar as your package gets deployed to the Windows Azure fabric.

You learned about how Windows Azure works under the hood in Chapter 2, Under the Hood. Essentially, when you click Deploy, the Windows Azure fabric kicks in and starts deploying the package. The fabric controller finds unused virtual machines on which to place the website, copies a new operating system image over onto the virtual machines, and copies the package files over. It modifies network settings to make requests to your cloudapp.net URL resolve to the IP address of the virtual machine on which your code has been placed.

The final step to run your code is to click the Run button, as shown in Figure 3.12. This causes the fabric controller to go to the virtual machine(s) on which your code has been placed, and launch the application. Depending on the complexity of your application and the number of virtual machines you use, this can take anywhere from a few seconds to a few minutes.

Figure 3.12. Deployment allocated and ready to run

Attached Image

At this point, your code is up and running. Head on over to your cloudapp.net URL (which is booksample.cloudapp.net in the example shown here) in a web browser. You should see the text “Hello World!” as shown in Figure 3.13.

Figure 3.13. Website running in the cloud

Attached Image

Congratulations! You’ve successfully launched code in Windows Azure.

Using the Visual Studio Tools

Just as Visual Studio wraps around the C# or Visual Basic compilers to provide an integrated experience with the IDE, the Visual Studio extensions wrap around CSPack and the Dev Fabric to provide an integrated experience with Windows Azure. This also provides an additional important feature that is difficult to reach with just the command-line tools alone: debugging support.

The following discussion assumes that you’ve finished installing the SDK and the Visual Studio tools. If you haven’t, follow the instructions presented earlier in this chapter on where to get the right bits and how to install them.

Let’s start by opening Visual Studio and selecting FileNewProject. Select the Cloud Service template on the list, as shown in Figure 3.14.

Figure 3.14. Visual Studio New Project dialog

Attached Image


You can also use the Cloud Service template as a good way to check whether the SDK and tools installed cleanly. If you don’t see the Cloud Service template, it means something failed in the installation process.

A cloud service solution contains only the service definition and service configuration files for your service. It doesn’t contain (by default) the actual roles that make up your service. As mentioned earlier, Chapter 4, Service Model provides more information on roles. For now, you simply should be aware that you can add roles to your cloud service project in two ways:

  • Using the New Cloud Service Project dialog, which pops up when you create a new cloud service solution, as shown in Figure 3.15. This dialog shows you a list of role types available for adding to your project. This list is frequently expanded, so you may see more items on this list with newer builds of the SDK.

  • Using the Visual Studio Solution Explorer later in the development cycle to add them to your solution.

Figure 3.15. Adding roles to your Visual Studio solution

Attached Image

Since you are creating a simple website, let’s add an ASP.NET Web Role to your project by clicking that option, as shown on the right side of the dialog shown in Figure 3.15.

At this time, Visual Studio generates a cloud service solution, a web role project, and some default files for you. Your Solution Explorer should look similar to Figure 3.16. The Cloud Service project is a container for your service definition and service configuration files. You should have default ServiceDefinition.csdef and ServiceConfiguration.cscfg files generated for you. These files automatically reference the WebRole1 project and are set to use one virtual machine.

Figure 3.16. Default web role project created by Visual Studio

Attached Image

The WebRole1 project itself is just an ASP.NET web application project under the covers. It is identical to a typical ASP.NET project in almost all ways. However, instead of hooking up with the ASP.NET development server, Cloud Service projects are automatically run in the Dev Fabric.

At this point, you can press F5 to build and launch your empty website. Visual Studio will build your website, call CSPack to package it for the Dev Fabric, and then launch the Dev Fabric. Most importantly, it will attach a debugger to the Dev Fabric so that normal Visual Studio debugging functions “just work.” You can set a breakpoint, step through code, inspect local variables, and do everything that you would normally do while debugging an ASP.NET website.

Finally, you can package your service for Windows Azure by right-clicking on the Cloud Service node in the Solution Explorer and selecting Publish, as shown in Figure 3.17.


Note that Publish happens to be a widely used term inside Visual Studio. Also note that selecting BuildPublish invokes a completely different and unrelated menu.

Clicking Publish will call CSPack and create a .cspkg file and a .cscfg file for uploading to Windows Azure. You can then upload this to the cloud using the Developer Portal, or through the Windows Azure Service Management API.

Figure 3.17. Packaging our project using CSPack

Attached Image

Programming Windows Azure

Learn more about this topic from Programming Windows Azure.

Learn the nuts and bolts of cloud computing with Windows Azure, Microsoft's new Internet services platform. Written by a key member of the product development team, Programming Windows Azure shows you how to build, deploy, host, and manage applications using Windows Azure's programming model and essential storage services.

See what you'll learn

0 Replies