The first thing I had the opportunity to work on when I joined the Windows Azure team was something that I’m excited to show off today. I demonstrated the early bits of the Windows Azure Management Libraries at the TechEd Australia Developer kick-off session, and now that they’re out I’m really excited to walk you through getting started with their use. This post will sum up what the Windows Azure Management Libraries are and why you should care to take a peek at them, and then I’ll dive into some code to show you how to get started.

What are these libraries you speak of?

With this release, a broad surface area of the Windows Azure cloud infrastructure can be accessed and automated using the same technology that was previously available only from the Windows Azure PowerShell Cmdlets or directly from the REST API. Today’s initial preview includes support for hosted Cloud Services, Virtual Machines, Virtual Networks, Web Sites, Storage Accounts, as well as infrastructure components such as affinity groups.

We’ve spent a lot of time designing natural .NET Framework APIs that map cleanly to their underlying REST endpoints. It was very important to expose these services using a modern .NET approach that developers will find familiar and easy to use:

  • Supports Portable Class Library (PCL), which targets apps that are built for .NET Framework 4.5, Windows Phone 8, Windows Store, and Silverlight
  • Ships as a set of focused NuGet packages with minimal dependencies to simplify versioning
  • Supports async/await-based task asynchrony (with easy synchronous overloads)
  • Has a shared infrastructure for common error handling, tracing, configuration, and HTTP pipeline manipulation
  • Is factored for easy testability and mocking
  • Is built on top of popular libraries such as HttpClient and Json.NET

These packages open up a rich surface area of Windows Azure services, giving you the power to automate, deploy, and test cloud infrastructure with ease. These services support Windows Azure Virtual Machines, Hosted Services, Storage, Virtual Networks, Web Sites and core data center infrastructure management.

Getting Started

As with any good SDK, it helps to know how you could get started using it by taking a look at some code. No code should ever be written to solve a problem that doesn’t exist, so let’s start with a decent, but simple, problem statement:

I have this process I run as in Windows Azure as a Worker Role. It runs great, but the process it deals with really only needs to be run a few times a week. It’d be great if I could set up a new service, deploy my code to it, then have it run. Once the process finishes it’d be even better if the service could “phone home” so it could be deleted automatically. I sometimes forget to turn it off when I’m not using it, and that can be expensive. It’d be great if I could automate the creation of what I need, then let it run, then have it self-destruct.

Until this preview release of the Windows Azure Management Libraries (WAML for short hereafter, though this is not an official acronym, I’m just being lazy), this wasn’t very easy. There’ve been some great open-source contributions to answering the .NET layer in managing Windows Azure services and their automation, but nothing comprehensive that delivers C# wrappers for nearly all of the Windows Azure Management REST APIs. If you needed to use these API to generate your own “stuff” in Windows Azure, you pretty much had to write your own HTTP/XML code to communicate with the REST API. Not fun. Repetitive. Boring, maybe, after you do a few dozen out of hundreds of API methods.

Getting the Management Libraries

I decided to do this work in a simple WPF application I’ll run on my desktop for the time being. I’ll want to run it as long-running app or service later, but for now this will work just fine. Since I’ve got a Windows Azure Cloud Service with a Worker Role I’ll want to run in the cloud, I’ve just added all three projects to a single solution, which you’ll see below.

You probably noticed that I’m preparing to add some NuGet packages to the WPF application. That’s because all of the Windows Azure Management Libraries are available as individual NuGet packages. I’m going to select the Microsoft.WindowsAzure.Management.Libraries package, as that one will pull everything in the Management Libraries into my project. If I wanted to manage one aspect of Windows Azure rather than all of it, I’d reference one of the more specific packages, like Microsoft.WindowsAzure.Management.WebSites, which provides management functionality specific only to the Windows Azure Web Sites component.

Once I’ve referenced the NuGet packages, I’m ready to set up client authentication between my WPF application and the Windows Azure REST APIs.


The first implementation we’ve built out for authenticating users who are using WAML and Windows Azure is a familiar one – using X509 Certificates. Integrated sign-in was added recently in SDK 2.2 to Visual Studio and to PowerShell, and we’re working on a solution for this in WAML, too. With this first preview release we’re shipping certificate authentication, but stay tuned, we’re doing our best to add in additional functionality.

Don’t panic. We’ve made this so easy even I can do it.

I’m not going to go deep into a discussion of using certificate-based authentication in this post. In fact, I’m going to be as brute-force as possible just to move into the functional areas of this tutorial. I’ll need two pieces of information to be able to log into the Windows Azure API:

  • A subscription ID
  • A management certificate

I obtained these values from one of my publish settings files. The XML for this file is below.

With the key and the subscription ID in my code later on, I can call the GetCredentials method below that returns an instance of the abstract class, SubscriptionCloudCredentials, we’re using to represent a credential instance in the Management Library code. That way, if I add single-sign on later it’ll be easy for me to replace the certificate authentication with something else. The code the the CertificateAuthenticationHelper class from my sample code is below:

Now I’ll write a controller class that’ll do the work between my WPF application and the Management Libraries – a convenience layer, in a sense.

Management Convenience Layer

To map out all the various parameters I’ll have in my workflow I’ve created the ManagementControllerParameters class shown below. This class will summarize all of the pieces of data I’ll need to create my services and deploy my code.

Then, I’ll create a class that will provide convenience functionality between the UX code and the Management Library layer. This code will make for cleaner code in the UX layer later on. Note the constructor of the code below. In it, two clients are being created. One, the StorageManagementClient, will provide the ability for me to manage storage accounts. The other, the ComputeManagementClient, provides the ability for me to work with most of the Windows Azure compute landscape – hosted services, locations, virtual machines, and so on.

For the purposes of explaining these steps individually, I've created a partial class named ManagementController that's spread across multiple files. This just breaks up the code into functional units to make it easier to explain in this post, and to provide for you as a public Gist so that you can clone all the files and use them in your own code.

Now, let’s wire up some management clients and do some work.

Create a New Storage Account using the Storage Management Client

The first thing I’ll need in my deployment strategy is a storage account. I’ll be uploading the .cspkg file I packaged up from a Cloud project in Visual Studio into a Windows Azure blob. Before I can do that, I’ll need to create an account into which that package file can be uploaded. The code below will create a new storage account in a specified region.

Once the storage account has finished creating, I'm ready to use it. Given that I'll need a connection string to connect my application (and my soon-to-be-created cloud service) to the storage account, I'll create a method that will reach out to the Windows Azure REST APIs to get the storage account's connection keys. Then, I'll build the connection string and hand it back to the calling code.

Now that the storage account has been created I'll create my cloud service and publish my package up to Windows Azure.

Create and Deploy a new Cloud Service using the Compute Management Client

The call to create a cloud service is surprisingly simple. All I need to do is to provide the name of the cloud service I intend on creating and the region in which I'd like it to be created.

Finally, all I need to do to deploy the cloud service is to upload the cloud service package file I created in Visual Studio to a blob, then call the REST API. That call will consist of the blob URI of the package I uploaded to my storage account, and the XML data from the cloud project's configuration file. This code will make use of the Windows Azure Storage SDK, which is also available as a NuGet package.

Now that all the code's written to create my Windows Azure application, I'll write some code to destroy it once it wraps up all of the work it was designed to do.

Deleting Assets from Windows Azure

Deleting assets using the Windows Azure Management Libraries is as easy as creating the assets. The code below cleans up the storage account I created. Then, it deletes the cloud service deployment and the cloud service altogether.

With all the convenience code written at this point, the user experience code should be relatively painless to write next.

The User Experience

The UX for this application is relatively simplistic. I'm just providing a pair of buttons on a WPF form. One will create the assets I need in Windows Azure and perform the deployment. The other will delete the assets from Windows Azure. XAML code for this UX is below. It isn't much to look at but the idea here is to keep this simple.

The codebehind for the UX is also just as easy. In the Create button-click event, I create a new ManagementController instance, providing it all of the parameters I'll need to create the application's components in the Windows Azure fabric. Then I call all of the methods to created everything.

I also handle the Delete button-click by cleaning up everything I just created.

I could modify this code to use the Windows Storage SDK to watch a storage queue on the client side. When the cloud service is finished doing its job, it could send a message into that queue in the cloud. The message would then be caught by the client, which would in turn call the Cleanup method and delete the entire application.

Endless Automation Possibilities

The Windows Azure Management Libraries provide a great automation layer between your code and Windows Azure. You can use these libraries, which are in their preview release as of this week, to automate your entire Windows Azure creation and destruction processes. In this first preview release, we're providing these management libraries for our compute and storage stacks, as well as for Windows Azure Web Sites. In time, we'll be adding more functionality to the libraries. The goal is to give you automation capabilities for everything in Windows Azure.

We're also excited about your feedback and look forward to suggestions during this preview phase. Please try out the Management Libraries, use them in your own experimentation, and let us know what you're using them to facilitate. If you have ideas or questions about the design, we're open to that too. The code for the libraries, like many other things in the Windows Azure stack, are open source. We encourage you to take a look at the code in our GitHub repository.

This Team is Astounding. I am Not Worthy.

Jeff Wilcox’s team of amazing developers have put in a lot of time on the Management Libraries and today we’re excited to share them with you via NuGet. Jeff’s build script and NuGet wizardry have been a lot of fun to watch. The pride this team takes in what it does and the awesomeness of what they’ve produced is evident in how easy the Management Libraries are to use. We think you’ll agree, and welcome your feedback and stories of how you’re finding ways to use them.


Mads created MiniBlog, and I liked it quite a bit. You can't argue with the very idea of MiniBlog, to keep blogging and your web server as simple as possible. I'm kinda into Windows Azure these days, so I had some ideas on  how to make MiniBlog run better on Windows Azure. So this is the first step - becoming a user of MiniBlog to learn more about the project and to contribute to it.

I've been a huge fan, advocate, and support of Orchard for years. Orchard's a fantastic blogging tool, and my switching is no indication of my lack of love for Orchard. Orchard, to me, is one of those amazing CMS systems that you can make do anything. I chose to use it as a blog, and to be honest it may've been overkill in a few places over the years but I stuck with it because I really enjoy using Orchard. The truth is, I think MiniBlog is neat and I'm teammates with Mads so we decided we'd tinker and see what we could make it do. The first place to start is to dogfood it, so that's where this post comes in.

Welcome to the MiniBlog era on bradygaster.com.


This past week I was able to attend the //build/ conference in San Francisco, and whilst at the conference I and some teammates and colleagues were invited to hang out with the awesome dudes from New Relic. To correspond with the Web Sites GA announcement this week, New Relic announced their support for Windows Azure Web Sites. I wanted to share my experiences getting New Relic set up with my Orchard CMS blog, as it was surprisingly simple. I had it up and running in under 5 minutes, and promptly tweeted my gratification.

Hanselman visited New Relic a few months ago and blogged about how he instrumented his sites using New Relic in order to save money on compute resources. Now that I’m using their product and really diving in I can’t believe the wealth of information available to me, on an existing site, in seconds.

FTP, Config, Done.

Basically, it’s all FTP and configuration. Seriously. I uploaded a directory, added some configuration settings using the Windows Azure portal, Powershell Cmdlets, or Node.js CLI tools, and partied. There’s extensive documentation on setting up New Relic with Web Sites on their site that starts with a Quick Install process.

In the spirit of disclosure, when I set up my first MVC site with New Relic I didn’t follow the instructions, and it didn’t work quite right. One of New Relic’s resident ninja, Nick Floyd, had given Vstrator’s Rob Zelt and myself a demo the night before during the Hackathon. So I emailed Nick and was all dude meet me at your booth and he was all dude totally so we like got totally together and he hooked me up with the ka-knowledge and stuff. I’ll ‘splain un momento. The point in my mentioning this? RT#M when you set this up and life will be a lot more pleasant.

I don’t need to go through the whole NuGet-pulling process, since I’ve already got an active site running, specifically using Orchard CMS. Plus, I’d already created a Visual Studio Web Project to follow Nick’s instructions so I had the content items that the New Relic Web Sites NuGet package imported when I installed it.


So, I just FTPed those files up to my blog’s root directory. The screen shot below shows how I’ve got a newrelic folder at the root of my site, with all of New Relic’s dependencies and configuration files.

They’ve made it so easy, I didn’t even have to change any of the configuration before I uploaded it and the stuff just worked.


Earlier, I mentioned having had one small issue as a result of not reading the documentation. In spite of the fact that their docs say, pretty explicitly, to either use the portal or the Powershell/Node.js CLI tools, I’d just added the settings to my Web.config file, as depicted in the screen shot below.


Since the ninjas at New Relic support non-.NET platforms too, they do expect those application settings to be set at a deeper level than the *.config file. New Relic needs these settings to be at the environment level. Luckily the soothsayer PM’s on the Windows Azure team predicted this sort of thing would happen, so when you use some other means of configuring your Web Site, Windows Azure persists those settings at that deeper level. So don’t do what I did, okay? Do the right thing.

Just to make sure you see the right way. Take a look at this screen shot below, which I lifted from the New Relic documentation tonight. It’s the Powershell code you’d need to run to automate the configuration of these settings.


Likewise, you could configure New Relic using the Windows Azure portal.


Bottom line is this:

  • If you just use the Web.config, it won’t work
  • Once you light it up in the portal, it works like a champ

Deep Diving into Diagnostics

Once I spent 2 minutes and got the monitoring activated on my site, it worked just fine. I was able to look right into what Orchard’s doing all the way back to the database level. Below, you’ll see a picture of the most basic monitoring page looks like when I log into New Relic. I can see a great snapshot of everything right away.


Where I’m spending some time right now is on the Database tab in the New Relic console. I’m walking through the SQL that’s getting executed by Orchard against my SQL database, learning all sort of interesting stuff about what’s fast, not-as-fast, and so on.


I can’t tell you how impressed I was  by the New Relic product when I first saw it, and how stoked I am that it’s officially unveiled on Windows Azure Web Sites. Now you can get deep visibility and metrics information about your web sites, just like what was available for Cloud Services prior to this week’s release.

I’ll have a few more of these blog posts coming out soon, maybe even a Channel 9 screencast to show part of the process of setting up New Relic. Feel free to sound off if there’s anything on which you’d like to see me focus. In the meantime, happy monitoring!


I’ve been a huge fan of Orchard for some time. Last year the Orchard team put together a conference they called the Orchard Harvest, and they’re doing the conference again this year in Europe. Specifically, in Amsterdam. If you’re an Orchard user or site owner I’d encourage you take a look at the Harvest. Some great speakers will be at the event in a great location and I’m sure there’ll be some awesome information. Find out more about the harvest at http://orchardharvest.org/.


If you’re a web developer working with ASP.NET, Node.js, PHP, Python, or you have plans on building your site in C++, Windows Azure Web Sites is the best thing since sliced bread. With support for virtually every method of deployment and with support for most of the major web development models you can’t beat it. Until recently, SSL was the only question mark for a lot of web site owners, as WAWS doesn’t yet support SSL out of the box (trust me, it’s coming, I promise). The good news is that there’s a method of achieving SSL-secured sites now. In this blog post I’ll introduce the idea of a workaround my engineering friends in the Web Sites team call the SSL Forwarder, and to demonstrate how you can get up and running with an SSL-protected Windows Azure-hosted web site in just a few minutes’ work.


First, I’d like to point out one very important point about the SSL Forwarder solution. This solution works, and we have a handful of community members actively using this solution to provide an SSL front-end for their web sites. So feel comfortable using it, but understand that this isn’t something you’ll have to do forever, as SSL is indeed coming as an in-the-box feature for Web Sites. If you love the idea of Windows Azure Web Sites but the lack of in-the-box SSL support is a deal-breaker for you and your organization, this is a viable option to get you up and running now. However, the SSL Forwarder isn’t an officially supported solution, in spite of one being actively used by numerous customers. So if you set this up and you experience anything weird, feel free to contact me directly via the comment form below, or on Twitter, or by email (and I’ll give you my email address on Twitter if you need it). All that being said, I’ve heard from quite a few in the community who are using this solution that it has mitigated their concern and they appear to be running quite well with this in place.

Architectural Overview

Don’t panic when you see this solution. Do read the introduction, once you see grok how it all works, the SSL Forwarding solution is a whole lot less intimidating. I admit to having freaked out with fear when I first saw this. I’m no expert at most of the things involved in this exercise, but the Web Sites team literally put together a “starter project” for me to use, and it took me 1 hour to get it working. If I can do this, you can do this.

SSL-Forwarder-DiagramThe idea of the SSL Forwarder is pretty simple. You set up a Cloud Service using the Windows Azure portal that redirects traffic to your Windows Azure Web Site. You can use all the niceties of Web Sites (like Git deployment, DropBox integration, and publishing directly to your site using Visual Studio or WebMatrix) to actually build your web site, but the requests actually resolve to your Cloud Service endpoint, which then proxies HTTP traffic into your Web Site.

The diagram to the right shows how this solution works, at a high level. The paragraph below explains it in pretty simple terms. I think you’ll agree that it isn’t that complicated and that the magic that occurs works because of tried-and-true IIS URL Rewrite functionality. In order to obtain the 99.9% uptime as outlined in the Windows Azure SLA, you’ll need to deploy at least 2 instances of the Cloud Service, so the diagram shows 2 instances running. As well, the code provided with this blog post as a starting point is defaulted to start 2 instances. You can back this off or increase it however you want, but the 99.9% uptime is only guaranteed if you deploy the Cloud Service in 2 instances or more (and there’s no SLA in place yet for Web Sites, since it’s still in preview at the time of this blog post’s release, so you can host your Web Site on as many or as few instances as you like).

You map your domain name to your Cloud Service. Traffic resolves to the Cloud Service, and is then reverse-proxied back to your Web Site. The Cloud Service has 1 Web Role in it, and the Web Role consists of a single file, the Web.config file. The Web.config in the Web Role contains some hefty IISRewrite rules that direct traffic to the Web Site in which your content is hosted. In this way, all traffic – be it HTTP or HTTPS traffic – comes through the Cloud Service and resolves onto the Web Site you want to serve. Since Cloud Services support the use of custom SSL certificates, you can place a certificate into the Cloud Service, and serve up content via an HTTPS connection.


To go along with this blog post, there’s a GitHub.com repository containing a Visual Studio 2012 solution you can use to get started. This solution contains three projects:

  • A Windows Azure Cloud Project
  • A web site that’s used as a Web Role for the Cloud Project
  • A web site that’s deployed to Windows Azure Web Sites (you’ll want to replace this one with the project you’re deploying or just remove it, it’s just there as part of the sample)

Create the Cloud Service and Web Site

First thing is, I’ll need to create a Web Site to host the site’s code. Below is a screen shot of me creating a simple web site myself using the Windows Azure portal.


Obviously, I’ll need to create a Windows Azure Cloud Service, too. In this demo, I’ll be using a new Cloud Service called SSLForwarder, since I’m not too good at coming up with funky names for things that don’t end in a capital R (and when I do, Phil teases me, so I’ll spare him the ammunition). Below is another screen shot of the Windows Azure portal, with the new Cloud Service being created.


If you’re following along at home work, leave your browser open when you perform the next step, if you even need to perform the next step, as it is an optional one.

Create a Self-signed Certificate

This next step is optional, and only required if you don’t already have an SSL certificate in mind that you’d like to use. I’ll use the IIS Manager to create my own self-signed certificate. In the IIS Manager I’ll click the Server Certificates applet, as shown below.

When I browse this site secured with this certificate, there’ll be an error message in the browser informing me that this cert isn’t supposed to be used by the domain name from where it’s being served. Since you’ll be using a real SSL certificate, you shouldn’t have to worry about that error when you go through this process (and I trust you’ll forgive a later screen shot where the error is visible).


Once that applet loads up in the manager, I’ll click the link in the actions pane labeled Create Self-Signed Certificate.


I’ll name my certificate SSLForwarderTesting, and then it appears in the list of certificates I have installed on my local development machine. I select that certificate from the list and click the link in the Actions pane labeled Export to save the cert somewhere as a file.


Then I find the location where I’ll save the file and provide it with a password (which I’ll need to remember for the next step).


Now that this [optional] step is complete I have a *.PFX file I can use to install my certificate in the Cloud Service.

Install the SSL Certificate into a Cloud Service

To activate SSL on the Cloud Service I’ll need to install an SSL certificate into the service using the Windows Azure portal. Don’t panic, this is easier than it sounds. Promise. Five minutes, tops.

Back in my browser, on the Windows Azure portal page, I’ll click the Cloud Service that’ll be answering HTTP/S requests for my site. The service’s dashboard page will open up.


I’ll click the Certificates tab in the navigation bar.


I’m going to want to upload my certificate, so this next step should be self-explanatory.


The next dialog gives me a pretty hard-to-screw-up dialog. Unless I forgot that password.

(cue the sound of hands ruffling through hundreds of post-its)


Once the certificate is uploaded, I’ll click the new cert and copy the thumbprint to my clipboard, maybe paste it into Notepad just for the moment…


Configuring the Cloud Service’s SSL Certificate

With the SSL cert installed and the thumbprint copied, I’ll open up the ServiceConfiguration.cloud.cscfg file in Visual Studio 2012 and set the thumbprint’s configuration. I could also do this using the built-in Windows Azure tools in Visual Studio, but since I’ve got the thumbprint copied this is just as easy to do directly editing the files. Plus, the Web Sites team made it pretty obvious where to put the thumbprint, as you’ll see from the screen shot below.


Configuring the URL Rewrite Rules in the Web Role

Remember the architectural overview from earlier. The main