Chapter 4. It’s time to run with the service

In the last chapter we got into the guts of the infrastructure and architecture of Windows Azure. During that chapter we introduced the concept of the service model and how it’s used by the FC to manage your role.

In this chapter we’ll take some time out to look at the parts of the service model that we didn’t get to mess around with much (specifically the service definition and service configuration files). But first, let’s spend a little time with the Service Management API.

4.1. Using the Windows Azure Service Management API

In both chapter 1 and chapter 2, you created a brand new Windows Azure web role from scratch. As we pointed out then, a web role hosted by Windows Azure is a regular old ASP.NET web application with a little bit of extra magic that allows you to interact with Windows Azure. That extra magic is three new assemblies that are automatically added to your new web application when you create a new Windows Azure Cloud Service project in Visual Studio. Figure 4.1 shows these assemblies listed in the Visual Studio 2010 Solution Explorer.

In this chapter we’ll focus only on the Microsoft.WindowsAzure.ServiceRuntime assembly. We’ll look at Diagnostics in chapter 18, and the StorageClient in chapters 9 through 12 and 16.

The ServiceRuntime assembly acts as a bridge between the Windows Azure runtime and your application. Although you don’t need to include the ServiceRuntime assembly in your web role, you should. Without this assembly, your applications have no way to interact with Windows Azure and make use of the APIs that it exposes to you. This assembly provides the following helper routines that we’ll explore throughout this chapter:

This assembly provides some valuable methods that you’ll need to fully use the power of Windows Azure. We’ll take a look at how you can include this assembly in your projects.

4.1.1. Adding the ServiceRuntime assembly to your application

As you saw earlier, when you create a new ASP.NET web role in Visual Studio, the new assemblies from the SDK are automatically referenced within your project. That’s great if you’re creating a new role, but what if you’re migrating an existing ASP.NET application to the cloud, or if you want to access the API from another assembly?

The ASP.NET web role project created in Visual Studio is a normal ASP.NET web application with three extra assembly references. If you need to migrate your existing application (or use it in another project), you can always add those extra assemblies via the Add Reference dialog box. You can find these assemblies in the c:\Program Files\Windows Azure SDK\v1.1\ref\ directory.

Now that you know how to reference the ServiceRuntime assembly, let’s take a look at some of the API calls and how you can use them.

4.1.2. Is your application running in Windows Azure?

One of the static properties that the ServiceRuntime exposes via the RoleEnvironment static class is the ability to check whether your application is running in Windows Azure. You can perform this check using the RoleEnvironment.IsAvailable property.

To see this check in action, you’re going to quickly create a web page that displays a label that states whether your application is running in Windows Azure. Figure 4.2 shows that web page running in the development fabric.

To create the web page shown in figure 4.2, create a new cloud service solution called ServiceRuntimeWeb with a new ASP.NET web role called ServiceRuntimeWebsite. In the web project, modify the Default.aspx page to include the following label:

After you’ve added this label to your web page and a using statement for the ServiceRuntime namespace, you can then display the result of the RoleEnvironment.IsAvailable call in the contents of the label by adding the following code to the Page_Load event:

As you know, web roles are standard ASP.NET web applications; they can still be run on a standard IIS web server (if you like retro computing). If you launched this page in IIS (or the ASP.NET Web Development Server by selecting the ASP.NET project and pressing F5), then it would display the message Not in the fabric. If you were to now fire up your web page in the Windows Azure development fabric, it would display I am running in the fabric (as shown in figure 4.2).

The RoleEnvironment.IsAvailable call is not only useful for announcing to the world that your web application is in heaven (I mean in the cloud), but it’s also useful for building applications (or libraries) that will be hosted both inside and outside Windows Azure. Because most of Windows Azure’s APIs aren’t available outside Windows Azure, you might want to check that you’re running inside Windows Azure before using one of these APIs. Later in this section we’ll look at some of these situations and possible solutions that you can use when working with shared code.

We’ve introduced you to the ServiceRuntime assembly. Now let’s take a look at some of the other differences between a standard ASP.NET web application and a Windows Azure ASP.NET web role.

4.2. Defining your service

In chapter 3, we spent quite a bit of time discussing the infrastructure and architecture of Windows Azure. In that chapter, we introduced the concept of the service model and how it comprises three elements: the service definition, the service configuration, and the operating model.

In this section, we’ll look at the first piece of the service model puzzle, which is the service definition file (we’ll look at some of the other stuff later on). In chapter 3, we described how the FC uses the service definition file (ServiceDefinition.csdef) to manage your service; in this chapter we’ll show you how you can effectively define your service.

The following information is held in the service definition file:

In the following subsections, we’ll take a look at how you can define some of that information. Before we do that, let’s return to the service definition file itself.

4.2.1. The format of the service definition file

When you created your Cloud Service project in chapter 1, the service definition file was automatically added to your project. The following listing shows the service definition file for the ServiceRuntimeWeb project that you created in chapter 1.

As shown in listing 4.1, the service definition file adheres to the following format:

Throughout the course of the next few sections we’ll explore the items that define your role in more detail.

Because your Cloud Service project contains only a single web role, you’ll see only a single role definition in your service definition file. If your project contained multiple roles, these roles would also be included in the file. The XML in the following listing shows how this would be structured in the service definition file.

In this example, there are two roles in the project: a web role called ServiceRuntimeWebsite and a worker role called WorkerRole1 (note that the definition of a worker role is exactly the same as the configuration of a web role, except that the definition element is called WorkerRole instead of WebRole).

You have an idea of the structure of the service definition file, but what sort of information describing your service would you put in that file?

4.2.2. Configuring the endpoint of your web role

If you look at the service definition file for your web role in listing 4.1, you’ll see that the HTTP port and protocol that your application runs on is defined at .

Windows Azure allows web roles to receive incoming HTTP or HTTPS messages (usually via port 80 and port 443 respectively) via your virtual IP address only (see chapter 3). Any other traffic that’s sent to your virtual IP address is either filtered out by the firewalls or is not forwarded to your web role from the load balancer. Figure 4.3 shows the interaction between a client browser, the load balancer, and your web role. Worker roles are not held to this protocol restriction. (We’ll cover worker roles in chapter 15.)

By locking down the available protocols, Windows Azure reduces the surface area of attack for your web role. Any incoming requests to your web role (outside of the port and protocol combinations defined in the service definition) are filtered out by the firewalls and load balancers; the request never reaches the servers that your web role is hosted on. This level of protection protects your web role from port attacks, as well as from distributed denial-of-service (DDoS) attacks.

By default, Visual Studio correctly configures your web role to use HTTP and port 80 in your service definition file. (This configuration is shown at in listing 4.1.)

If you wanted to expose your service via HTTPS, you would change the InputEndpoint in the service definition file to the following:

If you need to run your application in both HTTP and HTTPS, define two InputEndpoint tags:

You can configure other ports for the protocols as well (for example, you can define an endpoint with the port 8080). You would usually configure other ports when there are multiple web roles in the same solution. Such a configuration would allow each web role to be accessed on a different port.

Where’s the GUI?

If you’re currently thinking to yourself “I’ll never remember all that XML syntax,” then good news: the service definition file has an XSD (XML Schema Definition language) associated with it. You get full IntelliSense support when you edit this file in Visual Studio. If you edit in Notepad, you don’t get the benefit of this support.

Alternatively, if you feel that we’ve moved beyond text files and are in a Windows Presentation Foundation (WPF) Minority Report-style GUI interface era, then you’ll be pleased to hear that you can edit the service definition file by using a dialog box in Visual Studio 2010. To open the dialog box, double-click the name of your web role in the Roles folder of your Cloud Service project (for example, double-click ServiceRuntimeWebsite in the Roles folder in the ServiceRuntimeWeb cloud project, as shown in figure 4.1).

To modify the endpoints in the editor, select the Endpoints tab, shown in figure 4.4.

There are several reasons why you might want to use a port other than port 80 or 443, but for the most part, these are the traditional ports used with HTTP and HTTPS and are considered best practices.

Ignoring Best Practices When Developing

Although security best practices are great for production servers, they can be a real pain to follow during development. We can all thank Ray Ozzie at Microsoft for making this a little easier in the development fabric by allowing us to run our web roles on any port.

Figure 4.4 shows how you can easily set this value via the editor. Because we have an XML fetish, let’s look at how it’s done in the service definition file. The following bit of configuration shows how you can run your web role on port 87 over HTTP in the development fabric:

The development fabric is pretty lenient when it comes to configuring available ports. If a port is already taken (if IIS is hogging port 80), it gives you the next available port. For example, if you asked for port 80, it would fire up your application on port 81 instead.

Intrarole Communication

You might have noticed in figure 4.4 that there’s a little section called Internal Endpoint (go on, look, if you didn’t see it already). If you need to host a web role internally (you don’t want that web role to be available outside the Windows Azure fabric) but you want to make that web role available to another role, this check box is for you. A typical reason for wanting this functionality is that a web role or worker role is reliant on an internal web service (as is the case with service-oriented-architecture-type applications).

You can configure the internal endpoint of this role by setting the name, port, and protocol of the internal endpoint in this way:

Alternatively, you can use the editor, as shown in figure 4.4.

It’s worth pointing out that web roles support only HTTP internal endpoints and can’t be secured with certificates. You should use the HTTP protocol only for internal endpoints that are legacy web services (old ASP.NET Web Services [ASMX] and the like). If you’re considering using this approach for WCF services, you should host your service with a worker role and expose it via TCP instead. TCP generally provides better performance for internal services than does HTTP.

Worker Role Endpoints

Although the service definition file is a common file that’s used by both web roles and worker roles, we’re going to look at only web roles in this chapter. We’ll leave the examples on how to host worker roles that accept incoming requests across various protocols and ports to later in the book.

The configuration of a worker role uses the same InputEndpoint tag as the web role. The following XML shows the endpoint for a worker role hosted on TCP port 10000:

Figure 4.5 shows the GUI for configuring a worker role endpoint.

You can use the editor shown in figure 4.5 to set internal endpoints. Remember, internal endpoints are dynamically assigned ports and you can’t manually set the port number. The following XML defines an internal endpoint called MyEndpoint that uses TCP (rather than HTTP or HTTPS) as a protocol:

As we said earlier, we intended to give only a brief description about how this configuration applies to worker roles. We’ll return to this later on, but now we’re going to take a little detour and examine other things you can do in the editor.

4.2.3. Configuring trust level, instances, and startup action

When you click the Configuration tab, you see the options shown in figure 4.6.

There are three sections on this page: .NET Trust Level, Instances, and Startup Action. We’ll be looking at these sections in more detail later in the book, but for the moment let’s have a quick introduction to them.

.NET Trust Level

Windows Azure supports two levels of trust: full trust and partial trust. Partial trust is similar to ASP.NET’s medium trust level. It restricts the operations that your application can perform to only those that it trusts. Whenever possible, you should run your application in partial-trust mode because it provides a greater level of security (I sleep like a baby at night whenever my application is running under partial trust). If, however, you need to perform big scary actions that would make a security freak’s skin crawl (such as C++, Reflection, or P/Invoke) then you’ll need to set your application to full trust.

Using the dialog box shown in figure 4.6 is probably the easiest way to set your trust level, but because we all love messing with configuration files, let’s modify the service definition file directly.

To configure partial trust, set the enableNativeExecution attribute on your role to false. For full trust, you can either set the attribute to true or not configure it at all (full trust is the default level). The following XML shows how to set your earlier web role to partial trust:

In chapter 6, we’ll look in more detail at the supported trust levels. Now let’s move on to the Instances section.

Instances

The Instances section allows you to set the number of instances of your role and the size of your VM (small, medium, large, or extra large). The number of instances is an important setting, but because this setting is held in the service configuration file, we’re going to save our discussion of it for chapter 6. Now it’s on to the Startup Action section.

Startup Action

The final section on the Configuration page is Startup Action. This section isn’t really part of the service definition, but is instead a wee bit of Visual Studio configuration. The following two check boxes are in this section:

These check boxes tell Visual Studio which endpoints you want to launch in the development environment when you press F5.

That’s about it for what you can do on the Configuration page in the Visual Studio editor. Let’s take a look now at the Local Storage page and find out how to configure your local storage.

4.2.4. Configuring local storage

Local storage is a temporary filesystem storage area that’s made available to a role instance to store and retrieve data locally. The local storage area is available only to a single role instance and can’t be shared across multiple role instances.

If the VM for your role instance dies and never recovers, you’ll lose the data stored in this area forever. Only volatile data should be stored in this storage area; never store any data that you might need to rely on later in a court of law. Any data that you store in local storage should also be stored in a nonvolatile storage area such as a BLOB, Table storage, or SQL Azure.

If It’s So Volatile, Why Do I Need It?

Although BLOBs, Table storage, and SQL Azure can be accessed by all instances of a role, the convenience of centralized storage mechanisms comes at a cost: latency. Those other, nonvolatile storage areas are all hosted on separate servers in another part of the data center, whereas local storage is part of your VM. Because the disks are hosted on the same server as your VM, local storage is much faster than the other storage mechanisms.

BLOBs, Table storage, and SQL Azure are suitable for most scenarios, but if you’re processing high volumes of data, you might want to use local storage to temporarily cache that data. Let’s look at how to set that up.

Setting Up Local Storage

As always, there are two ways to configure local storage. You can either do it manually via the service definition file, or you can use the role editor in Visual Studio 2010 and let it modify the service definition file for you. Figure 4.7 shows the GUI for configuring local storage in Visual Studio.

When you define a local storage resource, you can define the following three items:

The maximum amount of local storage that you can use for a single role instance is 20 GB. If you need more than 20 GB of temporary storage space, you might want to rethink the architecture of your application.

The information that you supply in the editor is reflected in the service definition file, as shown in the following listing.

In the current version of Windows Azure, you can’t dynamically change this setting at runtime, which is why this code lives in the service definition file and not in the service configuration file. If you incorrectly size your temporary storage area and need to request a larger size, you have to redeploy your application. Why is that?

The FC uses the requested size of local storage as part of its algorithm to decide which physical servers will host your VM. If the FC allowed you to modify the local storage dynamically without a redeployment, it might not be able to satisfy your request with the servers that are currently hosting your role instances (there might be too many other roles hosted on that server that have high local storage requirements). By forcing a redeployment of the application, the FC can safely redeploy your role instances to the servers that most appropriately satisfy your request.

Now that you know how to set up local storage, let’s take a quick look at how to use it in your application.

Using Local Storage

If you need to be able to use local storage in your role (web or worker), then you can make a request to retrieve information about your role using the RoleEnvironment class in the ServiceRuntime. Use the following call to request information about your local storage resource.

You need to call RoleEnvironment.GetLocalResource, passing in the name of the local storage resource that you defined earlier (myStorage). The object returned by GetLocalResource exposes three properties (Name, MaximumSizeInMegabytes, and RootPath). The Name and MaximumSizeInMegabytes properties return the information that you set in the service definition file:

The RootPath property returns the physical path of the folder where your temporary storage area has been assigned. Using the RootPath property, you can use standard .NET methods to store and retrieve data in this folder. The following code creates a text file called HelloWorld.txt that contains the text “Goodbye World”.

It’s pretty simple to use local storage. It’s built on all the existing system.I/O classes that we all know and love.

Before we leave the subject of local storage, we want to cover one final thing: the Clean on Role Recycle setting.

Recycling a Role

Use the Clean on Role Recycle setting to indicate whether you want to lose or keep your local storage data if one of the following things occurs:

It’s pretty hard to test how your application responds to losing your temporary data as part of an upgrade or a fault, but you can manually request that your roles be recycled. All you need to do is call the RequestRecycle method in the RoleEnvironment class:

This call not only allows you to test that your application handles local storage correctly when your role instance is recycled; it also allows you to test whether the rest of your application behaves gracefully.

If your application needs to know when a role instance is stopping (because it’s cleaning up resources, notifying a monitor, or performing some other such task), you can always use the RoleEnvironment.Stopping event:

You can easily stick any cleanup code that you need in the event handler for this event. When this handler is called, your code has only 30 seconds to respond. This time limit protects Windows Azure from sloppy tear-down code or freezes in the cleanup process. This limit is similar to the limit local Windows services face when they’re told to stop by the user or the OS.

You now know almost everything you need to know about local storage. We’ll revisit this topic in part 4, when we show how you can use this in combination with BLOBs and how local storage can help you when you’re building massively scalable worker processes built on MapReduce.

Now let’s turn our attention to the tabs in the role editor that we haven’t covered yet. So far we’ve looked at the Configuration, Endpoints, and Local Storage tabs. That leaves the Certificates and Settings tabs. When we looked at configuring endpoints, we discussed HTTPS but we didn’t mention how to configure the SSL certificate for your site. Let’s return to that subject and look at certificate management in Windows Azure.

4.3. Setting up certificates in Windows Azure

We want to look at how to generate, add, and configure certificates in Azure. Let’s look at how to generate one first; then we’ll cover how to add and configure them. Certificates are widely used to encrypt, and thereby protect, data as it travels over the network. In this section, when we refer to certificates, we mean the type you’ll use for HTTPS/SSL or for your own encryption needs. We’re not referring to the management certificates we’ll cover in chapter 18.

4.3.1. Generating a certificate

For live production applications you should use a purchased certificate from a trusted authority. If you’re just experimenting or testing an application, you can use a test certificate. Because you’ve already bought this lovely book, we’ll save your wallet from more troubles and show you how to generate a test certificate that you can use on the production or development fabric.

To generate a test X.509 certificate, you can use a tool called makecert, which is included with both Visual Studio and the .NET Framework. To start using the tool, fire up an instance of the Visual Studio command prompt as an administrator. Using the command prompt, you can generate a test certificate with the following command:

This command generates a test X.509 certificate called MyCertficate.cer, and stores it in the CurrentUser/Personal store. You’ll need to use the certificate management tool in Windows to export it as a PFX-formatted certificate, which is suitable for use in Windows Azure. For more details about the makecert tool, you can always visit the following URL: http://msdn.microsoft.com/en-us/library/bfsktky3(VS.80).aspx.

With your brand new certificate in hand, you can install the certificate in both the production fabric and the development fabric.

4.3.2. Adding certificates

The production fabric and the development fabric both have different methods of managing certificates. Let’s look at how to add certificates on the live system first.

Adding Certificates to the Production Fabric

As you might expect, you manage certificates via the Azure portal. Select your hosted service in the portal, and then click Manage in the Certificates section. You’ll see the window shown in figure 4.8.

If you need to install your certificate using your own code, you can use the management APIs. We won’t cover how to do this in this book because it’s not a typical scenario for most folks. If you’re automatically installing lots of websites, then using your own code could be useful; the rest of you should use the portal.

Adding Certificates to the Development Fabric

If you need to test HTTPS in your development fabric, you’ll need the appropriate certificate on your development machine. To upload your certificate into the development fabric, click the Certificates tab in the role editor, as shown in figure 4.9.

You can set the name, location (LocalMachine, CurrentUser), store name (My, Root, CA, Trust), and the certificate.

To set the certificate, you can either enter the thumbprint manually or select a certificate from your personal store. If you click the button in the Thumbprint cell, the Select a Certificate dialog box opens (already armed with the test certificate that you generated earlier), as shown in figure 4.10.

Now that you’ve selected your certificate, you might be wondering how this is reflected in the service definition file. Don’t worry. Your XML-obsessed authors are here to help you out. The following listing shows how the certificate is represented.

Everything that you set in figure 4.9 is present in the service definition file, except for the thumbprint, which is stored in the service configuration file. The thumbprint is a configurable setting, not a definable attribute of the service; that’s why it’s in the configuration file. We’re going to talk more about the thumbprint in chapter 5; now let’s use that new certificate.

4.3.3. Configuring your HTTPS endpoint to use the certificate

The last thing you need to do is to configure your endpoint to use the new certificate. With your certificate installed, you can either use the SSL Certificate drop-down menu shown in figure 4.4 (which is now populated with your test certificate) to configure the endpoint, or you can manually configure it in the service definition file. To configure the endpoint manually, set the certificate attribute of the InputEndpoint element to the name of your certificate:

If you expose a worker role externally using an InputEndpoint element, you can also secure that service with a certificate. You manage and configure certificates for a worker role in the same way as you do a web role.

4.4. Summary

It’s probably a good time to stop and review where we’ve been. In this chapter, you’ve taken everything that you’ve learned about how Windows Azure works (from chapter 3) and started to define how you want your application to run in the environment.

We talked about the ServiceRuntime assembly and how you can use that to interact with Windows Azure. This assembly provides several APIs that can help you to get the most out of Windows Azure. You can use the ServiceRuntime assembly to determine whether your application is up and running in Azure.

Next, we examined the service definition file, which defines your service. The information in this file instructs the FC about how to manage your application. In this file, you configure the endpoint of your web role, the trust level you want to use, your instances, your local storage, and the certificates you’ll use. We showed how you can do all this using either the Visual Studio editor or by putting the information directly into the file in XML.

In the next chapter you’ll take what you’ve learned about defining your service and configure it to work in Windows Azure.