Help
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 D:\htmlwebsite>
Note
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.)
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" xmlns= "http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition"> <span class="strong"><strong><WebRole name="WebRole1" enableNativeCodeExecution="false"></strong></span> <InputEndpoints> <InputEndpoint name="HttpIn" protocol="http" port="80" /> </InputEndpoints> <ConfigurationSettings /> </WebRole> </ServiceDefinition>
Example 3.3. Sample ServiceConfiguration.cscfg
<?xml version="1.0"?> <ServiceConfiguration serviceName="CloudService1" xmlns= "http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration"> <span class="strong"><strong><Role name="WebRole1"></strong></span> <Instances count="1" /> <ConfigurationSettings /> </Role> </ServiceConfiguration>
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
WebRole] should have one (1) instance, meaning that the code will run on one virtual machine in the cloud.
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.
Note
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:\><strong class="userinput"><code>cspack htmlwebsite\ServiceDefinition.csdef[/inlinecode]</strong> <span class="strong"><strong>/role:WebRole1;htmlwebsite /out:output /copyonly</strong></span> Windows(R) Azure(TM) Packaging Tool version 1.0.0.0 for Microsoft(R) .NET Framework 3.5 Copyright (c) Microsoft Corporation. All rights reserved. D:\>
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.
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:\>dir /s output Volume in drive D has no label. Volume Serial Number is 34DA-B4F3 Directory of D:\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:\output\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:\output\roles\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:\output\roles\WebRole1\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
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:\>csrun /run:output;htmlwebsite/ServiceConfiguration.cscfg Windows(R) Azure(TM) Desktop Execution Tool version 1.0.0.0 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 http://127.0.0.1:81/
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 http://127.0.0.1:81. Since your web page was
called index.html, navigate to
http://127.0.0.1:81/index.html in any web browser.
You should see something similar to Figure 3.5.
Note
The Dev Fabric’s web server isn’t configured to redirect requests from http://127.0.0.1:81 to http://127.0.0.1:81/index.html. 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.
Note
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!
Now that you have your code up and running in the Dev Fabric, let’s get it running in the actual Windows Azure 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:\>cspack htmlwebsite\ServiceDefinition.csdef /role:WebRole1;htmlwebsite /out:package.cspkg Windows(R) Azure(TM) Desktop Execution Tool version 1.0.0.0 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.
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).
Note
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.
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.
Note
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.
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.
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.
Note
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.
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
Figure 3.10 shows the two slots represented as two molded cubes on the portal.
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.
Note
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.
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.
Congratulations! You’ve successfully launched code in Windows Azure.
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 File→New→Project. Select the Cloud Service template on the list, as shown in Figure 3.14.
Note
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.
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.
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
Note that Publish happens to be a widely used term inside Visual Studio. Also note that selecting Build→Publish 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.
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.
