38 Comments
   

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.

Authenticating

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.

Comments

Comment by Dejisys

Lovely stuff. This would be very useful. Thanks for the detailed information.

Comment by Phil Arena

Pure awesomeness. I look forward to putting this to use in so many sweet ways. Thanks team. :)

Phil Arena
Comment by Hernan Meydac Jean

Hi Brady, I'm trying to create a Windows Phone "Hello World" app using the Management Libraries. At the beginning of the post you mentioned that the libraries "Supports Portable Class Library (PCL), which targets apps that are built for .NET Framework 4.5, Windows Phone 8, Windows Store, and Silverlight", but I can't instantiate the class CertificateCloudCredentials because it doesn't exist for WP8. I tried a Console App and the class it's there in Microsoft.WindowsAzure namespace. Is the support for WP8 in the Preview limited or am I missing something? I would love to see it in action for WP8! Excellent post by the way :)

Hernan Meydac Jean
Comment by brady gaster

Thanks for the comment and the question. This is one we've had a few times, and some folks have even posted blogs on the idea borrowing some of our PowerShell code as inspiration. The SubscriptionCloudCredentials is within the Common area, which is, of course, a PCL. At this time the implementation used in the NuGets is the CertificateCloudCredentials. Since that particular implementation relies on the use of X509 certificates, which as you point out aren't yet implemented in WP8, Store, and Silverlight platforms, we don't have a full story in those areas.

That said, you've also seen growing support for the AAD credential methodology, via VS and our PowerShell code, which support that method. We're working on that implementation and I feel confident an option will be available once we reach the 1.0 release. If you've got any other ideas for credential implementations, or thoughts on the topic in general, you know how to find me. :)

Thanks a lot for reaching out! It has been too long since we've hung out!

brady gaster
Comment by Hernan Meydac Jean

Thanks for replying! The tooling and the libraries available are a great asset for us, so congratulations for getting these available to the public as soon as possible. I'll look forward for the new updates of this great library. :)

Hernan Meydac Jean
Comment by Tomas Foltynek

Hi Brady, does the Management Library have support for rolling upgrade of deployed service? I.e. is it possible to start the upgrade using UpgradeDeployment command, and then upgrade one upgrade domain at the time using the WalkUpgradeDomain command?

Tomas Foltynek
Comment by brady gaster

Tomas - Yes, that's supported in the WAML. You can totally do that.

brady gaster
Comment by bit

Thanks so much for bringing attention of WAML to the Azure development community; our organization had been waiting quite a while for an SDK wrapper of the Azure Management REST APIs. The sample you provided is a wonderful introduction and within a short amount of time we were successfully able to extend it in order to programmatically create or delete VM instances and delete VM disks to break leases on Blob VHDs so that they can be reused immediately. We look forward to the AAD support in version 1.0 as well as a little more documentation. Cheers!

bit
Comment by Julian Elve

Luckily I had only spent four hours starting to write my own client for the management interface when I found this! Long overdue, looks really promising...

Julian Elve
Comment by Max

I've started using your preview nuget package for our deployment automation. Hopefully this will come out of preview pretty soon! -) Very handy and useful! knocked together a small app that creates a hosted service with storage account in less than half-day.

One thing I would like to suggest: at the moment there is no documentation on the library, that's fine. People can look on code. But can you possibly separate classes into a separate files?

ComputeManagementClient.cs is a massive beast with 41K lines of code in one file(sic!). It is impossible to navigate in any shape or form. The classes themselves are small and very manageable, but because they are in one file, I'm having a scrolling nightmares trying to read your code.

Thanks,
Max

Comment by brady gaster

Max -

We are working on prototyping the clients as multiple files. Though we don't have a roadmap for when this'll be released it is something we're considering doing. Dif reports in GitHub on those files is also painful, so I'm familiar in part with your frustrations (though from a different perspective, of course).

Also, our documentation is very close to being done. I've recently reviewed the documentation, which was quite deep and navigable. I'll update this comment thread once those docs have been released.

brady gaster
Comment by Ayush Sharma

Thanks a lot of making this available. We are hooking it onto out continuous deployment system. However, I see that RollbackUpdateOrUpgradeByDeploymentSlotAsync is always returning me an exception "InvalidXml". My deployment does have RollbackAllowed = true. I am calling Rollback after I manually start walking upgrade domains [and before I have walked over all upgrade domains]. I am calling this with same params that I call my BeginUpgradingBySlotAsync and BeginWalkingUpgradeDomainByDeploymentSlotAsync with.

Ayush Sharma
Comment by brady gaster

Ayush - thanks so much for the feedback and the report. Since we've taken this to email I'll just forego a long-winded reply here. :) We'll be working on this for you for sure.

brady gaster
Comment by jd

I'm curious if there's any plan to release a similar SDK for the Azure SQL Management API? If so, any plan to include the ability to create/update/delete SQL logins?

If not, can anybody suggest a way to programmatically maintain SQL logins on a Azure SQL? My goal is to have a way to programmatically create SQL logins when a new employee is hired and to remove the SQL login when an employee quits or is terminated.

Comment by jd

Regarding my last comment: I see that SQL management is something that has been asked before and you've already started working on it. That's great, but I don't see any mention of managing SQL logins though

http://feedback.windowsazure.com/forums/170031-sdk-and-tools/suggestions/1350881-extend-management-api-with-sql-azure-support

Comment by brady gaster

The SQL WAML library does give you the ability to change administrative passwords, but at this time there's no support for creating/changing/deleting logins. That's a great feature suggestion though, and I'd like to ask if you could submit an issue to our public repository to request the feature. We'll discuss this feature with our colleagues in the SQL team and will scope it out if the feature is something the team feels should be added. Our repo link is here: https://github.com/WindowsAzure/azure-sdk-for-net

brady gaster
Comment by yauhen.f

Nice library. Is it compatible with Windows Azure Pack? As far as I could see calls and formats are similar but at least authentication differs (token vs certificate). Not sure how easy it will be to inject custom authentication.

yauhen.f
Comment by Brian MacKay

Is there a way to add domain names to a web site? Right now I'm trying: Site.HostNames.Add("test.com") and nothing seems to happen. I feel like I'm missing some kind of save or commit command.

Brian MacKay
Comment by Brian MacKay

Nevermind, I found Client.WebSites.Update! Awesome! I particularly appreciate the exceptions, they are informative and give me a sense of things making sense as I play with this.

Brian MacKay
Comment by rob

Any ETC on when this will come out of preview. I've been utilizing the api and it's working great, but I'm a bit gunshy to role with it in production until the api comes out of preview.

thx and keep up the good work

rob
Comment by rob

that should be ETA above, not ETC...

rob
Comment by brady gaster

Rob - this set of libraries will be released very soon. I can't comment on actual release dates, but we have a large event coming up soon that I'd like to show these off at, and we'd like to GA them before that session lands. It won't be long, that much I can promise.

brady gaster
Comment by Abz

I would like to know how can I deploy a package or website files to Azure Web Sites using Microsoft.WindowsAzure.Management.WebSites? The library is very helpful by the way.

Comment by brady gaster

Abz - I have a blog post in the works to demonstrate that very thing. I'll make sure to get that published by Monday of next week. Thanks for the feedback!

brady gaster
Comment by Hani

Hi Brady,

Thank you for the great content, it much appreciated. I have two questions:

1. Is there a way to programmatically gather Azure metrics such as CPU, memory, disk and interface utilization?

2. Does Microsoft have a RESTful billing API? If yes, can you please provide a link to the documentation.

Sincerely,

Hani.

Hani
Comment by brady gaster

Hani:

1: I think the Monitoring SDK, which Gu blogged about here (http://weblogs.asp.net/scottgu/archive/2013/11/21/windows-azure-general-availability-release-of-biztalk-services-traffic-manager-azure-ad-app-access-xamarin-support-for-mobile-services.aspx) can help you out with that. Not 100% sure but I think it would be a good first spot to check.

2: There is no billing API that I've seen or know of at this time.

brady gaster