3 Comments

Update: Two awesome developers from the Azure Websites team, David Ebbo and Elliott Hamai, took the idea of Deploy to Azure, looked at the code, laughed and pointed at me, and used all kinds of new APIs in Azure to bring the idea to life in a manner that will provide far more value than I'd imagined. Keep reading to learn about the prototype I built, but make sure to learn about the real thing, and try it out yourself. 

Over the weekend I received an email from my friend and colleague Devin Rader. In the email he directed me to a neat feature Heroku offers, called the Heroku Button, and asked me if there was anything in the works like this for Azure. I wasn't aware of anything that was in the works at the time, and given that I'm one of the program managers on the Azure SDK team who builds the Azure Management Libraries, I figured this was a challenge for which I'd be well-suited. So I replied to Devin to let him know I was inspired by the idea and wanted to build it myself. This blog post will introduce you to the idea of the Deploy to Azure Button. My good buddy Vittorio Bertocci has a complementary post on how the identity flow works in Deploy to Azure, as he and I consulted on the idea, so make sure to check that out too.  

What is the Deploy to Azure Button?

The idea of the Deploy to Azure button is to make it dirt simple for owners of pre-packaged web applications to make it dirt simple for their potential customers to deploy their applications to Azure. As a web application's author, I could place a button in my GitHub repository's readme file to give users a visual cue that one-click deployment is possible. Here's a screen shot of the Deploy to Azure button being used in a demonstration repository I created for an early demo of Azure Websites, the "Hello All Worlds" demo.

clip_image001

See that gorgeous blue button? If I click that button, the GitHub repository page URL will be passed as the HTTP referrer and the associated Git repository URI can pretty easily be guessed. Here's the Deploy to Azure site with this GitHub repository as it's referring URL. Note the Git repository URL is pre-populated into the form.

clip_image002

Once I provide a name for my site and select a region, the site name is verified as one that's available. If it isn't I'm informed as such.

clip_image003

Once I find a site name I like, and that is available, clicking the "Deploy to Azure" button will submit the form. The form's data is collected and posted back to a Web API controller, which in turn bubbles up status information about the process of cloning the code, creating the site, and then deploying the site's code via SignalR. As the site's deployed I'm provided real-time status.

clip_image004

Once the site's been deployed, a button is added to the form that I can use to pop open the new site in a new tab or browser window.

clip_image005

I've also added a Deploy to Azure button to my fork of my good buddy Mads' MiniBlog source code, which I've frequently used as a test case for the idea of enabling SaaS with the Management Libraries.

clip_image006

Video is so much more effective at conveying the idea of the Deploy to Azure button, so I've created 3-minute video walking through it on YouTube and embedded it below.

Want to use the Deploy to Azure Button?

Feel free! The app is live and working at http://deployto.azurewebsites.net, and will accept requests today. I'd encourage you to grab the button below or use the direct link to the button in your own GitHub repositories. Just put the button below on your repository, and link over to the URL above and the app will do the rest.

clip_image007

Below I describe how Deploy to Azure works, as well as put forth a few caveats of the app in its current state, so keep reading to understand some of the limitations of Deploy to Azure, as well as some of the plans we have for its future.

How it Works

There are a lot of ideas we could build out of the Deploy to Azure idea, but the code isn't too elegant just yet. The idea was to prove how easy it'd be to enable a one-click deployment story directly from a public repository. Now that we're there, we're seeing a lot of other ideas popping up.

For the time being I'm doing some really simple Git tricks on the server side and then some even simpler tricks on the deployment side. I'll go into the identity stuff later, but the Deploy to Azure code base started with Vittorio's sample on using the new OWIN middleware with Open IDC and multi-tenancy.

The workflow of Deploy to Azure is pretty simple. I'll walk through it at a very high level in this post, then dive a little deeper into the code of the site to explain how it works. The code for the site is open-source, too, so feel free to check out the GitHub repository where the code for Deploy to Azure is stored if you'd like to see more. Feel free to submit a pull request, too, if you feel you can make it better.

  1. A user is authenticated to their Azure account during the AAD handshake, driven by the OpenId Connect OWIN middleware
  2. The OWIN middleware hands over an authentication code to ADAL, which uses it to obtain a new AAD token for accessing the Azure Management API
  3. Once a token is obtained, MAML clients can be used to communicate with the Azure management APIs
  4. The list of regions available to a user's subscription are retrieved and displayed in the form's menu
  5. When a user submits the form the data is sent to a Web API controller
  6. The Web API controller clones the Git repository down to a new folder on the server side
  7. The Web API controller creates an instance of the Web Site Management Client and a site is created
  8. The site's publish profiles are pulled
  9. The site is deployed via Web Deploy back up to Azure Websites

The diagram below demonstrates this process visually.

clip_image008

This code isn't perfect, though, and Deploy to Azure should be considered a beta release. We have some ideas on how to make it better. New APIs are being released frequently, and during my discussions of this prototype with David Ebbo I learned of some upcoming APIs that will mitigate some of this functionality and add some features to the Deploy to Azure application. For now, consider Deploy to Azure a prototype of something awesome that we might push to the next level in the upcoming weeks.

Deploy to Azure is in Beta

As I mention above, Deploy to Azure has a few caveats. I'll cut to the chase real quick and break down some of the limitations of Deploy to Azure. I know you're excited and you want to start using the button, but first I feel I must clarify a few of the limitations it has in this first iteration.

Authentication

Deploy to Azure uses a multi-tenant Active Directory application. This way, users can allow the application access to their own Azure subscriptions and allow it to spin up new sites on their behalf. Since Deploy to Azure uses the multi-tenancy functionality of Azure Active Directory and isn't an official Microsoft application the login functionality is limited to Azure Active Directory users. This means you can't log in using your live.com, hotmail.com, or outlook.com accounts. Instead, you have to create an Active Directory user who is a Global Administrator of your Active Directory domain. Below I got into a little more detail on the identity aspect of Deploy to Azure and link off to a complementary post Vittorio Bertocci wrote up to describe how that portion of Deploy to Azure works.

No Solution Builds

Since the code for Deploy to Azure just clones the repository for a site and then publishes it, everything you want to deploy must be in your repository. Whereas Kudu will facilitate the solution build prior to publishing, which pulls in your NuGet packages, Deploy to Azure simply clones and publishes. This is one area where Mr. Ebbo and I are joining forces and working together to augment Deploy to Azure with more Kudu-like functionality in a later release.

Customizing Deployments

That said, it is highly probably that a Git repository might contain a site and other stuff unrelated to the site. In the case of MiniBlog, for instance, the actual web site that is MiniBlog is contained in a sub folder called "Website." Given this, if I simply re-publish the entire repository up to Azure, the site obviously won't work. For this reason, I've given users of the Deploy to Azure button a JSON file that the server-side code checks during deployments. In the screen shot below from my MiniBlog fork, you'll see two things highlighted. One is the Website folder, which contains the MiniBlog site source code.

clip_image009

See the arrow in the screen shot above? That arrow points to the file named deploytoazure.json. This file has a specific property in it that the Deploy to Azure code checks at run-time. The screen shot below shows this file in GitHub.

clip_image010

Once the Git repository has been cloned, I check for the presence of the deploytoazure.json file in the root of the cloned source. If the file exists, I open it up and check the value of the subdirectoryWithWebsite property. Then, I use the value of that property to determine which folder I'll publish up to the site. This gives developers a little more control over how the deployment works.

I'd imagine a later iteration of Deploy to Azure including other settings and flags in this file, but for now, the path to the web site code was really all I needed.

The Identity Component

One of the components about my own product I'd not really mastered was to work through some complex customer scenarios where the Azure Management Libraries would be used. Repeatedly customers asked me for server-side examples using ADAL and MAML together. The Deploy to Azure button was a perfect scenario for me to learn more about the code our customers would need to author to take advantage of these two together. I knew multi-tenancy would be crucial to Deploy to Azure- I'll host it in one subscription, but users of other (or multiple) subscriptions will want to deploy web applications into their own subscriptions, not into mine. So Deploy to Azure would have to allow for multi-tenant authorization, and I'd need to be able to get the user's AAD token in my code, since the Management Libraries' TokenCloudCredential class needs a bearer token at construction.

I spent the weekend learning some more about Azure Active Directory. By learning more about AAD, I really meant to say "emailing my colleague Vittorio Bertocci." Vittorio and I are working on a lot of things together now - the Azure Management Libraries, Java, Visual Studio, and basically everywhere else where the notion of identity is important in the conversation. Vittorio was interested in supporting my little project some support. My first question - how to get the token on the server side once a user was authenticated via AAD - was answered via Vittorio's excellent sample using the new OWIN middleware with Open IDC and multi-tenancy. The code in this repository was the starting point, in fact, for Deploy to Azure. I just added the functionality once I knew all the identity bits were wired up properly and I could grab the token.

clip_image011

As Deploy to Azure evolved and became a reality and the eventual creation of this blog post arose, Vittorio offered to write a complementary post explaining the details of the AAD-related functionality in Deploy to Azure. His post explains the entire end-to-end of the identity flow in the Deploy to Azure button process really well. I encourage you to continue reading over at Vittorio's post on the topic.

Next Steps

As I pointed out above, Deploy to Azure began as an idea and evolved pretty quickly. It has been a lot of fun to build, and in so doing I've successfully created an example of how you could use the ADAL library along with the Azure Management Libraries on the server side. We're discussing more features and ideas to add to Deploy to Azure. I'll post another, more technical post that walks through the code in more detail, but this post's purpose is to introduce you to the idea of the button and to invite you to try it out. Feel free to fork the code, too, and submit a pull request or issues that you run into as you're using it.

6 Comments

I’d like to officially introduce you to the 1.0 release of the Microsoft Azure Management Libraries. The official announcement of the libraries came out a few days ago on the Microsoft Azure Service Updates blog. Update: Jeff Wilcox wrote up am excellent piece introducing the Management Libraries, in which he covers a lot of ground. 

As I was busy travelling and presenting at the //build conference in San Francisco and enjoying my son Gabriel’s 6th birthday, I was a little tied up and unable to get this post out, but it gave me time to shore up a few little things, publish the code, and prepare a surprise for you that I’ll describe below in this post. Let’s just say I wanted to make it as easy as possible for you to get up and running with the 1.0 bits, since I’m so proud of all the work our teams have put into it. This week at the //build/ 2014 conference I presented a session with my buddy Joe Levy on many new automation stack we’ve added to Microsoft Azure. You can watch our //build/ session on Channel 9, which covers all of the topics from the slide image below. Joe and I talked about the Automation Stack in Microsoft Azure, from the SDK Common NuGet package up through the Microsoft Azure Management Libraries for .NET and into PowerShell and how the new Microsoft Azure Automation Service sits atop all of it for true PowerShell-as-a-service automation that you can use for just about anything.

automation-stack

Demonstrating the Management Libraries

My part of the session was primarily focused on how developers can make use of the Management Libraries (MAML, for short) for various scenarios. I’ve created 2 GitHub projects where the code for these demos, and I also have another surprise I’ll discuss later in the post. First, the demos!

Integration Testing

One scenario in which I think MAML has a lot to offer is to enable integration testing. Imagine having a Web Site that talks to a Storage Account to display data to the user in HTML. Pretty common scenario that can have all sorts of problems. Connection string incorrectness, a dead back-end, misconfiguration – you never know what could happen. Good integration tests offer more confidence that “at least the environment is right and everything is configured properly.” This scenario is represented by the code in the MAML Integration Testing code repository. Using xunit tests and MAML together, I was able to automate the entire process of:

  1. Creating a web site
  2. Publishing the web site’s code
  3. Creating a storage account
  4. Getting that storage account’s connection string
  5. Saving data to the storage account that I intend on displaying on the web site
  6. Configuring the web site’s connection string so that it can find the storage account and pull the data for display
  7. Hit the web site and verify it displays the correct information
  8. Delete the storage account
  9. Delete the web site

If this sounds like a common practice for your Microsoft Azure web apps, you might get some value from this demo, as it could streamline your entire process of integration testing. Here’s the best part – if you’re not really an Azure storage person, and your typical scenario involves a non-cloud-hosted ASP.NET web site that talks to SQL Server, you could still make use of MAML for your own integration tests. Simply use the SQL Management Client to fire up a Microsoft Azure SQL Database, insert a few records, and do basically the rest of the integration testing “stuff” but set up your page to read from the database instead of the storage account. Then, whether you’re deploying your production site to Microsoft Azure or not, you can make sure it all works using a scorched-earth testing environment.

Enabling SaaS

Cloud is a great place for software-as-a-service vendors. In typical SaaS situations, a customer can hit a web site, provide some information, and voila’, their newly-customized web site is all ready. The final demonstration I did during the //build/ session was geared towards these sorts of scenarios. In my demo at //build/, I demonstrated this sort of scenario by creating an MVC application I called MiniBlogger, for it generates live MiniBlog sites running in Microsoft Azure. When the user clicks the button, a Web API controller is invoked using JavaScript. The controller code makes a few calls out to the Microsoft Azure REST API using MAML. It first verifies the site name is available and if not, the user is provided a subtle visual cue that their requested site name isn’t available:

image

When the user finds a name they like that’s also not already in use, they can create the site. As the API controller iterates over each step of the process it sends messages to a SignalR Hub (yes, I can work SignalR in anywhere), and the user is provided real-time status on the process of the site being created and deployed.

image

Once the deployment is complete, the site pops up in a new browser, all ready for use. The code for this demo is also on GitHub, so fork it and party.

Get Your Very Own MAML Project Template (the surprise)

In this session I made use of Sayed and Mads’ work on SideWaffle and Template Builder to create a Visual Studio Extension that makes it easy to get up and running with MAML. Sayed and Mads have long thought SideWaffle would be great for coming up with canned presentations, and this was my first attempt at delivering on their goal. I asked them both tons of questions throughout the process, so first and foremost, thanks to them for SideWaffle and their patience as I fumbled through aspects of getting the hang of using it.

You can get the Microsoft Azure Management Libraries extension now in the Visual Studio Extensions Gallery. I’ve also created a little YouTube video demonstrating its usage. In five minutes, you can have a running Console Application that creates Virtual Machines in Microsoft Azure.

This Visual Studio Extension I created contains a few elements. First, it has a project template that references all of the MAML NuGet packages and the Active Directory Authentication Library NuGet package, which are dependencies for the demonstration. When you install the extension you’ll get a new project template like the one highlighted below.

SNAGHTMLae8a6c3

The project is a basic Console Application, but with all the MAML/ADAL NuGets referenced. Also contained within the extension are five item templates and 6 code snippets that walk you through the process of authoring code that will result in the following workflow:

  1. Authenticate to Microsoft Azure using Azure Active Directory
  2. Retrieve a list of Microsoft Azure subscriptions that the authenticated user can access
  3. Find a specific subscription and associate the AAD token with that subscription
  4. Create a new Cloud Service in the subscription
  5. Create a new Storage Account in the subscription
  6. Get the list of Virtual Machine images containing a filter (this is provided in the snippets as a parameter)
  7. Create a Virtual Machine running in the newly-created Cloud Service container, using the VHD of the image selected earlier
  8. Deploy the Virtual Machine and start it up

The screen shot below is from my own instance of Visual Studio testing out the item templates. I’m on step 2 in this screen shot, about to add the class that facilitates the subscription-selection process described above.

SNAGHTMLaf38d3a

Likewise, here’s my code being edited during step 2. Note how the snippet is really doing the work, and the comments provide guidance.

image

Each step of the process is pretty-well documented. I tried really hard to think of the easiest way to help the Microsoft Azure community get up and running with MAML following our 1.0 release, and this extension seemed to be the best answer I could come up with. I hope you find it as helpful as I think you’ll find it, but I welcome any feedback you may have on the extension and how it could be improved. Same thing for MAML – we’re all about taking feedback, so let us know what we can do to make the future better for you as you automate everything in Microsoft Azure.

Congrats to the Team

I’d definitely like to congratulate my team, and all the teams in Microsoft Azure who brought their awesome in full force this year in preparation for //build/. We had some great releases, amazing announcements, and heard great things from the community. Happy coding!

3 Comments

Some time back, I created the SiteMonitR sample to demonstrate how SignalR could be used to tie together a Web Site and a Cloud Service. Since then Windows Azure has evolved quite rapidly, as have the ASP.NET Web API and SignalR areas. One recent addition to the arsenal of tools available to application developers in Azure is WebJobs. Similar to the traditional Worker Role, a WebJob allows for the continuous or triggered execution of program logic. The main difference between a Worker Role and a WebJob is that the latter runs not in the context of a separate Cloud Service, but as a resource of a Web Site. WebJobs also simplify development of these routine middleware programs, too, since the only requirement on the developer is to reference the WebJobs NuGet package. Developers can write basic console applications with methods that, when decorated with properties resident in the WebJobs SDK, will execute at appropriate times or on schedules. You can learn more about the basics of WebJobs via the introductory article, the WebJobs SDK documentation, or from Hanselman’s blog post on the topic.

In this blog post, I’m going to concentrate on how I’ve used WebJobs and some of my other favorite technologies together to re-create the SiteMonitR sample. I’ve forked the original GitHub repository into my own account to provide you with access to the new SiteMonitR code. Once I wrap up this post I’ll also update the MSDN Code Sample for SiteMonitR, so if you prefer a raw download you’ll have that capability. I worked pretty closely with Pranav Rastogi, Mike Stall and the rest of the WebJobs team as I worked through this re-engineering process. They’ve also recorded an episode of Web Camps TV on the topic, so check that out if you’re interested in more details. Finally, Sayed and Mads have developed a prototype of some tooling features that could make developing and deploying WebJobs easier. Take a look at this extension and give us all feedback on it, as we’re trying to conceptualize the best way to surface WebJobs tooling and we’d love to have your input on how to make the whole process easier. 

Application Overview

SiteMonitR is a very simple application written for a very simple situation. I wanted to know the status of my web sites during a period where my [non-cloud] previous hosting provider wasn’t doing so well with keeping my sites live. I wrote this app up and had a monitor dedicated to it, and since then the app has served as proving ground for each new wave of technology I’d like to learn. This implementation of the application obviously makes use of WebJobs to queue up various points in the work flow of site-monitoring and logging. During this workflow the code also updates a SignalR-enabled dashboard to provide constant, real-time visibility into the health of a list of sites. The workflow diagram below represents how messages move throughout SiteMonitR.

01

The goal for the UX was to keep it elegant and simple. Bootstrap made this easy in the last version of the application, and given the newest release of Boostrap, the templates Pranav and his team made available to us in Visual Studio 2013, it seemed like a logical choice for this new version of SiteMonitoR. I didn’t change much from the last release aside from making it even more simple than before. I’ve been listening to the team, and the community, rave about AngularJS but I’d not had made the time to learn it, so this seemed like a great opportunity. I found I really love AngularJS from reworking this app from Knockout in the previous version. I’ve tried a lot of JavaScript frameworks, and I’m pretty comfortable saying that right now I’m in love with AngularJS. It really is simple, and fun to use.

06

The entire solution is comprised of 4 projects. Two of these projects are basic console applications I use as program logic for the WebJobs. One is [duh] a Web Application, and the last is a Common project that has things like helper methods, constants, and configuration code. Pretty basic structure, that when augmented with a few NuGet packages and some elbow grease, makes for a relatively small set of code to have to understand.

02

With a quick high-level introduction to the application out of the way, I’ll introduce the WebJob methods, and walk through the code and how it works.

Code for Harnessing WebJobs

One of the goals for WebJobs was to provide ASP.NET developers a method of reaching in and doing things with Windows Azure’s storage features without requiring developers to learn much about how Windows Azure storage actually works. The team’s architects thought (rightfully) that via the provision of convenience attributes that referred to abstract use-cases facilitated in many common Windows Azure scenarios, more developers would have the basic functionality they need to use storage without actually needing to learn how to use storage. Sometimes the requirement of having to learn a new API to use a feature mitigates that feature’s usefulness (I know, it sounds crazy, right?).

So, Mike and Pranav and the rest of the team came up with a series of attributes that are explained pretty effectively in their SDK documentation. I’m going to teach via demonstration here, so let’s just dive in and look at the first method. This method, CheckSitesFunction, lives in the executable code for a WebJob that will be executed on a schedule. Whenever the scheduler service wakes up this particular job, the method below will execute with two parameters being passed in. The first parameter references a table of SiteRecord objects, the second is a storage queue into which the code will send messages.

07

You could’ve probably guessed what I’m going to do next. Iterate over all the records in the table, grab the URL of the site that needs to be pinged, then ping it and send the results to a storage queue. The out parameter in this method is actually a queue itself. So the variable resultList below is literally going to represent the list of messages I’m planning on sending into that storage queue.

Now, if you’re obsessive like me you’ll probably have that extra monitor set up just to keep tabs on all your sites, but that’s not the point of this WebJob. As the code executes, I’m also going to call out to the Web API controller in the web site via the UpdateDashboard method. I’ll cover that in more detail later, but that’s mainly to provide the user with real-time visibility into the health of the sites being checked. Realistically all that really matters is the log data for the site health, which is why I’m sending it to a queue to be processed. I don’t want to slow down the iterative processing by needing to wait for the whole process so I queue it up and let some other process handle it.

08

In addition to a scheduled WebJob, there’s another one that will run on events. Specifically, these WebJobs will wake up whenever messages land into specific queues being observed by this WebJob. The method signatures with appropriately-decorated attributes specifying which queues to watch and tables to process, are shown in the code below.

09

One method in particular, AddSite, runs whenever a user event sends a message into a queue used to receive requests to add sites to the list of sites being watched. The user facilitates this use-case via the SiteMonitR dashboard, a message is sent to a queue containing a URL, and then, this method just wakes up and executes. Whenever a user sends a message containing a string URL value for the site they’d like to monitor, the message is then saved to the storage table provided in the second parameter. As you can see from the method below there’s no code that makes explicit use of the storage API or SDK, but rather, it’s just an instance of an IDictionary implementer to which I’m just adding items.

10

The SaveSiteLogEntry method below is similar to the AddSite method. It has a pair of parameters. One of these parameters represents the incoming queue watched by this method, the second represents a table into which data will be stored. In this example, however, the first parameter isn’t a primitive type, but rather a custom type I wrote within the SiteMonitR code. This variation shows the richness of the WebJob API; when methods land on this queue they can be deserialized into object instances of type SiteResult that are then handled by this method. This is a lot easier than needing to write my own polling mechanism to sit between my code and the storage queue. The WebJob service takes care of that for me, and all I need to worry about is how I handle incoming messages. That removes a good bit of the ceremony of working with the storage SDK; of course, the trade-off is that I have little no no control over the inner workings of the storage functionality.

That’s the beauty of it. In a lot of application code, the plumbing doesn’t really matter in the beginning. All that matters is that all the pieces work together.

12

Finally, there’s one more function that deletes sites. This function, like the others, takes a first parameter decorated by the QueueInput attribute to represent a queue that’s being watched by the program. The final parameters in the method represent two different tables from which data will be deleted. First, the site record is deleted, then the logs for that site that’ve been stored up are deleted.

11

The SiteMonitR Dashboard

The UX of SiteMonitR is built using Web API, SignalR, and AngularJS. This section will walk through this part of the code and provide some visibility into how the real-time updates work, as well as how the CRUD functionality is exposed via a Web API Controller. This controller’s add, delete, and list methods are shown below. Note, in this part of the code I’ll actually be using the Storage SDK via a utility class resident in the Web Project.

14

Remember the scheduled WebJob from the discussion earlier? During that section I mentioned the Web API side of the equation and how it would be used with SignalR to provide real-time updates to the dashboard from the WebJob code running in a process external to the web site itself. In essence, the WebJob programs simply make HTTP GET/POST calls over to the Web API side to the methods below. Both of these methods are pretty simple; they just hand off the information they obtained during the HTTP call from the WebJob up to the UX via bubbling up events through SignalR.

15

The SignalR Hub being called actually has no code in it. It’s just a Hub the Web API uses to bubble events up to the UX in the browser.

16

The code the WebJobs use to call the Web API make use of a client I’ll be investigating in more detail in the next few weeks. I’ve been so busy in my own project work I’ve had little time to keep up with some of the awesome updates coming from the Web API team recently. So I was excited to have time to tinker with the Web API Client NuGet’s latest release, which makes it dirt simple to call out to a Web API from client code. In this case, my client code is running in the scheduled WebJob. The utility code the WebJob calls that then calls to the Web API Controller is below.

13

As I mentioned, I’m using AngularJS in the dashboard’s HTML code. I love how similar AngularJS’s templating is to Handlebars. I didn’t have to learn a whole lot here, aside from how to use the ng-class attribute with potential multiple values. The data-binding logic on that line defines the color of the box indicating the site’s status. I love this syntax and how easy it is to update UX elements when models change using AngularJS. I don’t think I’ve ever had it so easy, and have really enjoyed the logical nature of AngularJS and how everything just seemed to work.

17

Another thing that is nice with AngularJS is well-explained by Ravi on his blog on a Better Way of Using ASP.NET SignalR with AngularJS. Basically, since services in AngularJS are Singletons and since AngularJS has a few great ways it does injection, one can easily dial in a service that connects to the SignalR Hub. Then, this wrapper service can fire JavaScript methods that can be handled by Angular controllers on the client. This approach felt very much like DI/IoC acts I’ve taken for granted in C# but never really used too much in JavaScript. The nature of service orientation in JavaScript and how things like abstracting a SignalR connection are really elegant when performed with AngularJS. The code below shows the service I inject into my Angular controller that does just this: it handles SignalR events and bubbles them up in the JavaScript code on the client.

18

Speaking of my AngularJS controller, here it is. This first code is how the Angular controller makes HTTP calls to the Web API running on the server side. Pretty simple.

19

Here’s how the Angular controller handles the events bubbled up from the Angular service that abstracts the SignalR connection back to the server. Whenever events fire from within that service they’re handled by the controller methods, which re-bind the HTML UX and keep the user up-to-date in real-time on what’s happening with their sites.

20

With that terse examination of the various moving parts of the SiteMonitR application code out of the way the time has come to learning how it can be deployed.

Deploying SiteMonitR

There are three steps in the deployment process for getting the site and the WebJobs running in Windows Azure, and the whole set of code can be configured in one final step. The first step should be self-explanatory; the site needs to be published to Windows Azure Web Sites. I won’t go through the details of publishing a web site in this post. There are literally hundreds of resources out there on the topic, from Web Camps TV episodes to Sayed’s blog, as well as demo videos on AzureConf, //build/ keynotes, and so on. Save it to say that publishing and remote debugging ASP.NET sites in Windows Azure Web Sites is pretty simple. Just right-click, select Publish, and follow the steps.

21

Once the code is published the two WebJob executables need to be zipped up and deployed. First, I’ll pop out of Visual Studio to the bin/Release folder of my event-driven WebJob. Then I’ll select all the required files, right-click them, and zip them up into a single zip file.

25

Then in the portal’s widget for the SiteMonitR web site I’ll click the WebJobs tab in the navigation bar to get started creating a new WebJob.

26

I’ll give the WebJob a name, then select the zip file and specify how the WebJob should run. I’ll select Run Continuously for the event-driven WebJob. It has code in it that will halt the process in wait for incoming queue messages, so this selection will be adequate.

27

Next I’ll zip up the output of the scheduled WebJob’s code.

24

This time, when I’m uploading the zip file containing the WebJob, I’ll select the Run on a Schedule option from the How to Run drop-down.

29

Then I’ll set up the schedule for my WebJob. In this example I’m going to be a little obsessive and run the process to check my sites every fifteen minutes. So, every fifteen minutes the scheduled task, which is responsible for checking the sites, will wake up, check all the sites, and enqueue the results of each check so that the results can be logged. If a user were sitting on the dashboard they’d observe this check happen every 15 minutes for each site.

30

The two WebJobs are listed in the portal once they’re created. Controls for executing manual or scheduled WebJobs as well as stopping those currently or continuously running appear at the bottom of the portal.

31

Configuration

The final step in deployment (like always) is configuration. SiteMonitR was built for Windows Azure, so it can be entirely configured from within the portal. The first step in configuring SiteMonitR is to create a Storage Account for it to use for storing data in tables and for the queue being used to send and receive messages. An existing storage account could be used, and each object created in the storage account is prefixed with the sitemonitr phrase. That said, it could be better for some to have an isolated storage account. If so, create a storage account in the portal.

28

Once the storage account has been created, copy the name and either primary or secondary keys so that you can build a storage account connection string. That connection string needs to be used, as does the URL of my site (in this case, sitemonitr.azurewebsites.net, which is in fact a live instance of this code) as connection strings and an appSetting (respectively). See below on how to configure these items right from within the Windows Azure portal.

image

Once these values are configured, the site should be ready to run.

Running SiteMonitR

To test it out, open the site in another browser instance, then go to the WebJobs tab of the site and select the scheduled task. Then, run it from within the portal and you should see the HTML UX reacting as the sites are checked and their status sent back to the dashboard from the WebJob code.

33

Speaking of dashboards, the WebJobs feature itself has a nice dashboard I can use to check on the status of my WebJobs and their history. I’ll click the Logs link in the WebJobs tab to get to the dashboard.

35

The WebJobs Dashboard shows all of my jobs running, or the history for those that’ve already executed.

34

Summary

I’m really enjoying my time spent with WebJobs up to this point. At the original time of this post, WebJobs was in the first Alpha release stage. so they’re still pretty preview. I’m seeing huge potential for WebJobs, where customers who have a small middle-tier or scheduled thing that needs to happen. In those cases a Worker Role could be quite overkill, so WebJobs is a great middle-of-the-road approach to giving web application owners and developers these sorts of scheduled or event-driven programs that enable a second or multiple tiers running. I’ve really enjoyed playing with WebJobs, learning the SDK, and look forward to more interesting things coming out in this space.

17 Comments

Since the initial release of the Windows Azure Management Libraries (WAML) as Portable Class Libraries (PCL, or pickles as I like to call them) we’ve had tons of questions from community members like Patriek asking how Windows Phone applications can be written that make use of the cloud management functionality WAML offers. At first glance it would seem that WAML is “unsupported on Windows Phone,” but the reality is that WAML is fully supported via it being a PCL, but some external factors made it seem just shy of impossible to be able to glue our PCL framework to each of the targeted client platforms. In the case of Phone, there are two blockers:

  1. Since the X509Certificate2 class is unsupported on Windows Phone developers can’t make use of the certificate-based method of authenticating against the Azure REST API
  2. Since there’s no ADAL implementation that targets Phone there’s no way to use ADAL’s slick functionality to get my authentication token. The assumption here is that some creative coding is going to have to be done to go deeper into the OAuth stack. Sounds nasty.

Well, that’s never stopped any motivated coder before, right? Armed with some code from Patriek, a problem statement, and a pretty informative blog post written by none other than Vittorio on how he had some fun tying Phone to REST Services using AAD, I set out to start at ground zero to get some code working on my phone that would enable me to see what’s happening in my Azure subscription, across all my sites, services, and data stores. I set out to create a new type of phone app that will give me complete control over everything I’ve got published to my Azure cloud subscription. This post will walk through the code I worked up to get a baseline Windows Phone mobile cloud management app running.

Creating and Configuring the Phone App

First, a little background is required here. As Vittorio’s post makes very clear, the OAuth dance the WP8 code is going to be doing is pretty interesting, challenging, and results with a great set of functionality and an even greater starting point if this app gives you some ideas on what you could make it do next. In fact, if you’re into that whole social coding thing, the code in this post has a GitHub repository right here. The code in the repository contains the project I created in this screen shot in more detail.

01

The first step is to pull down the NuGet pacakges I’ll need to write this application. In this particular case I’m kind of thinking of writing a Windows Phone app that I’ll use to management my Azure Web Sites, Cloud Services, SQL Databases, Storage Accounts, and everything in between. So I’ll right-click my Phone project and select the correct packages in next step.

02

I’ll go ahead and pull down the entire WAML NuGet set, so I can manage and view all of my asset types throughout the my Azure platform subscription. By selecting the Microsoft.Windows Azure.Management.Libraries package, all of the SDK Common and WAML platform NuGets will all be pulled down for this application to use.

03

The Common SDK, shown below in the project’s references window, provides the baseline HTTP, Parsing, and Tracing functionality that all the higher-order WAML components need to function. Next to that is the newest member of the Common SDK tools, the Common Windows Phone reference, which is new in the latest release of the Common SDK package. This new addition provides the high-level functionality for taking token credentials from within the Windows Phone client and being able to attach those credentials to the SDK client code so that calls made to the Azure REST API from a phone are authenticated properly.

04

If you read my last blog post on using WAAD and WAML together to authenticate WAML-based client applications, there are a few important steps in that post about working through the process of adding an application that can authenticate on behalf of your WAAD tenant. Take a look at that post here to get the values for the App Resources dialog in the screen shot below. In a sense, you’ll be setting application settings here that you can get from the Azure portal. You’ll need to create an application, then get that app’s client id, and your subscription and active directory tenant id or domain name, and place those values into the code’s resources file, as shown below.

06

The Login View

The first view shows a built-in web browser control. This web browser will be used to direct the user to the login page. From there, the browser’s behavior and events will be intercepted. The authentication data the form contains will then be used to manually authenticate the application directly to AAD.

Reminder – As Vittorio’s post pointed out, you might not want to use this exact code in your production app. This is a prototype to demonstrate putting it all together in the lack of important resources. Something better will come along soon. For now the OAuth dance is sort of up to me.

Note the web browser control has already been event-bound to a method named webBrowser_Navigating, so each time the browser tries to make a request this method handler will run first, and allow my code to intercept the response coming back to the browser.

05

Once the login page loads up, I’ll presume a login is in order, so I’ll go ahead and navigate to the login page, passing in a few of my own configuration parameters to make sure I’m hitting my own AAD tenant.

07

Vittorio deep-dives on the workflow of this code a lot better than I’ll try to do here. The basic idea is that the browser flow is being intercepted. Once the code realizes that AAD has authenticated me it hands back a URL beginning with the string I set for the redirectUrl property of this application in the portal. When my code sees my redirectUrl come through, I just run the GetToken() method to perform the authentication. It posts some data over the wire again, and this time, the response activity is handled by the RetrieveTokenEndpointResponse() event handler.

08

Once this handler wakes up to process the HTTP response I’ve received from the AAD authentication workflow (that we did via the OAuth dance), my access token is pulled out of the response. The subscription id value is then persisted via one of my App’s properties, and the next view in the application is shown.

09

When the user first opens the app, the obvious first step is visible. We need to show the user the AAD login site, and allow the user to manually enter in their email address and password. In this window. I could use a Microsoft (Live/Hotmail/etc.) account or an organizational account. The latter, so long as they’ve been marked as Azure subscription co-admins, would be able to log in and make changes, too.

16

Once the user logs in they’ll be shown a list of their subscriptions, so let’s take a look at how the code in the subscriptions view is constructed.

Selecting a Subscription

The subscription selection view just shows a list of subscriptions to the user in a long scrolling list. This list is data-bound to the results of a REST API call made via the SubscriptionClient class, which goes out and gets the list of subscriptions a user can view.

Note – even though I can see my full list of subscriptions, I’ve only installed the Application into one AAD tenant in one of my subscriptions. If I click any of the other subscriptions, things won’t work so well. A subscription and a tenant are tied together. Unless your application gets special permission (it does happen from time to time, I hear) your application can only access Azure assets in the same subscription. If you wanted to work across subscription you’d have a little more work to do.

The XAML code below shows how the list of subscriptions will be data-bound to the view. I may eventually go into this code and add some view/hide logic that would show only those subscriptions I could impact using the application settings I’ve got running in this app. Point is, I can see all of the subscriptions I can manage and conceptually manage them with some additional coding.

10

The code below is what executes to log a user in with their stored access token and subscription id, when the TokenCloudCredentials class is used to wrap their credentials up as a single construction parameter to most of the management client. Since I was able to get a token from the OAuth dance with AAD, and since I know which subscription ID I want to affect, I’ve got everything I need to start working against the rest of the service management REST API endpoints.

11

When the subscriptions page loads, it gives me the chance to select the subscription I want to manage. Note: I just need to be cautious and only click the subscription that matches the subscription where my AAD tenant is set up. In my case, I’ve got the application installed into my AAD tenant that lives in the subscription named Windows Azure MSDN – Visual Studio Ultimate. If I were to select any of my other subscriptions I’d get an exception.

To have true parity across all subscriptions you’d need to have an application setup in each of your directories and some additional configuration, or you’d have to allow other tenants set up multi-tenancy with your AAD tenant.

17

Once the subscription list is data-bound the user can select a subscription to work with. Selection of a subscription item in the list fires the following code.

12

It persists the subscription id of the subscription the user selected, and then navigates the user to the AssetListView page, which will show more details on what’s in a user’s Azure subscription.

Viewing Cloud Assets via Mobile Phone

To provide a simple method of being able to scroll through various asset types rather than emulate the Azure portal, I made use of the LongListSelector and Pivot controls. In each Pivot I display the type of Azure asset being represented by that face of the pivot control. Web Sites, slide, Storage, slide, SQL, slide, Cloud Services… and so on. The idea for the phone prototype was to show how WAML could be used to load ViewModel classes that would then be shown in a series of views to make it easy to get right to a particular asset in your Azure architecture to see details about it in a native Phone interface.

13

Since the assets list page is primarily just a logically-grouped series of lists for each of the types of assets one can own in their Azure stack, the ViewModel class’s main purpose is to expose everything that will be needed on the view. It exposes Observable Collections of each type of Azure asset the app can display.

14

What would be better as controller functionality, the code in the codebehind of the view ends up doing most of the data-acquisition from the Azure REST APIs via WAML calls. In the code sample below the GetWebSites method is highlighted, but the others – GetSqlDatabases, GetStorageAccounts, and GetHostedServices – all do the same sorts of things. Each method creates instances of appropriate management client classes, retrieves asset lists, and data-binds the lists so that the assets are all visible in the Windows Phone client.

15

The web sites pivot is shown below. I’m thinking of adding a deeper screen here, one that would show site statistics over the last N days, maybe add an appSetting and connectionString editor page, or something else. Have any ideas?

18

Here’s a list of my cloud services – 2 empty PaaS instances and 1 newly set-up VM instance.

19

Summary

Though the OAuth dance has a few drawbacks and the code is a little less elegant than when I could make use of ADAL in my previous example, it works. Once I have the token information I need from the browser, I can run with that information by creating an instance of a TokenCloudCredential, passing in the token I received from the OAuth dance to get to authenticate WAML and therefore, make calls out to the Azure Service Management API to automate my asset management. Since WAML is a PCL package, and as a result of the introduction of support for the Windows Phone platform into the SDK Common NuGet package, the community can now freely experiment with solutions combining Windows Phone and the Management Libraries.

Happy Coding!

11 Comments

Integration with Windows Azure Active Directory was one of the main features we wanted to get into the 1.0 release of the Windows Azure Management Libraries. Since Visual Studio and even the PowerShell Cmdlets (which use WAML, in fact) already have support for AAD, it was really important to all of us on the team that we have a method of providing authentication directly via AAD from within C# code using WAML. This makes for a synonymous login experience across all three of these (and more) areas. Most importantly, it makes it easy for Windows Azure users to be able to manage all their subscription assets when they only need to login using their username/password portal credentials rather than go through the process of creating and uploading management certificates. This blog post will answer some of the questions and requests we’ve had from the community on how to tie AAD and WAML together, to create AAD-authenticated applications code that can be used to manage your Windows Azure account assets.

This won’t be a deep-dive into how AAD works, but more a short examination on how it and WAML can be used together.

I worked quite a bit with the AAD team, especially Vittorio Bertocci, on this post. Our teams have a regular meeting so we’re on the same page, but the guys on their team spent some additional cycles with us spelunking, coming up with features, and so on. As we talked about ideas, the AAD team gave me some great resources, like this post which walks through the process of setting up a client app so that it can be authenticated using AAD. Vittorio’s site has a series of great examples on how to go deeper with AAD. I won’t go too deep into the inner-working of AAD in this post, so keep check out those great resources if you want more information. Thanks to the AAD team for all your help and patience and supporting our team!

Create a client app for managing Windows Azure assets

The code for this sample application won’t be too complicated. I’m actually going to retrofit a small command line app I wrote the other day when asked by a peer in another team who wanted to export the list of Virtual Machine images in the gallery. The code for this itty-bitty application’s beginnings is below, which makes use of the Compute Management Management Library.

waad-waml-03

With this code already working using my Management Certificate, and with it being a relatively simple app, it seemed like a great case for demonstrating how easy it is to switch out the CertificateCloudCredentials for the TokenCloudCredentials class once the AAD infrastructure is set up and ready. Speaking of that, this would be a good time to walk through the process using the Windows Azure portal to set up an AAD application in my AAD directory that I can develop that will use the Management Libraries to manage my subscription.

Setting up an AAD application using the portal

To authenticate using AAD I first need to create an application in my Windows Azure subscription’s existing Active Directory tenant. To do this I go to my AAD tenant page in the portal and click the Applications tab at the top.

waad-waml-05

I currently have no applications authenticating against my directory so I’ll click the Add button at the bottom of the portal.

waad-waml-06

Selecting the second option in this list presents me with a huge list of existing applications with which AAD can integrate. Since I’m interested in authenticating an application I’m writing, I’ll click the first option. 

waad-waml-07

The application I’m writing is a small console application, not a web app. Hence I’ll select the second option – Native Client Application - in the Add Application dialog, shown below. If I’d wanted to put an ASP.NET Web API up in the cloud that would use AAD on the back end for authentication, I’d select the top option, Web Application and/or Web API. The API my client app will need to access is the actual Windows Azure Service Management API, which AAD has a special provision for in the portal that will be examined in a moment.

waad-waml-08

Next, I’ll need to provide a redirect URI. Even though the application I’m writing is a native app, I still need to provide this URI to give AAD more details on the specific application that will be authenticating.

waad-waml-09

Once these settings are made, I can see the application’s client id in the portal, along with the information I provided during the application’s creation process. The MSDN code site article I mentioned above, written by the AAD team, walks through more details of how the client application authentication workflow functions and offers more details, so definitely check out that sample if you need more information on these settings. For now, what’s important to remember from this window are the client id text box and the redirect URI created below. Those two strings make up 2 of the 3 strings I’ll need to authenticate a WAML application with AAD.

waad-waml-10

The final piece of information is the AAD tenant id, which can be found by clicking the View Endpoints button in the portal when on the page for the directory I wish to use to authenticate users.

waad-waml-11

The URI provided in each of the text boxes in the resultant dialog contain a GUID. This GUID is the tenant id, so it’ll need to be copied out for use in my code.

waad-waml-12

Changing the WAML code to perform AAD authentication

Back in Visual Studio I’m ready to change the code to make use of AAD authentication. The first step is to reference the required NuGet package, the Active Directory Authentication Library (ADAL). This will enable my project the ability of prompting the user with a login dialog, into which they can enter their Microsoft account username and password. It will also add all sorts of goodness from the AAD folks that you can make use of in your client applications.

waad-waml-01

In the code I’ll add a method called GetAuthorizationHeader that will take my tenant id as a parameter. I’ll presume the calling code might want to make use of the common tenant, but will give callers the ability to pass in their own tenant GUID identifying their custom Active Directory tenant. Take note that within this method I’m making use of the application’s settings, the redirect URL and the client id property from the portal. As well. I’m passing the base URI of the Windows Azure REST API as the value for the resource parameter to the AuthenticationContext.AcquireToken method. Vittorio has a great blog post introducing ADAL and what you can do with it, so if you’re looking to dive deeper on this topic head on over to CloudIdentity.com and check it out. In a more practical implementation I should probably be setting those values up as appSetting variables, but for this demonstration code sheer pasting in the values is sufficient.

waad-waml-04

The final step in the code is to comment out the old authentication mechanism, where I was using the X509Certificate2 class to authenticate using a management certificate. In place of this code, which creates an instance of a new CertificateCloudCredentials class, I’ll make a call to the new GetAuthorizationHeader method to get my token, then use that token as a parameter to an instance of the TokenCloudCredentials class.

waad-waml-15

Authorizing access to the Windows Azure Service Management API to my client application

At this point the code almost works. However, when I run it I get an error that pretty clearly indicates what’s wrong in the exception message. Clearly, this application hasn’t been granted access to the service management API.

waad-waml-19

A recently-added (okay, a personally recently-discovered) feature within the portal allows me to specify which applications I’m going to allow access to this client application. Since I’ve not yet created any APIs that also use AAD as an authentication mechanism I’ll only see the two default items in this drop-down menu (the Graph Explorer and the Service Management API). By selecting the option Windows Azure Service Management API, I effectively grant my client application access to any of the REST API URLs available under https://management.core.windows.net. Once I save this setting, the code should run and give me back the list of Virtual Machine images from the gallery.

waad-waml-20

When I run the code this time, it works as expected. I’m prompted for my credentials, thanks to some of the functionality provided in the ADAL package.

waad-waml-16

Once I log in using my subscription’s credentials, WAML can authenticate and pull down the list of virtual machines.

waad-waml-17

From here, I could use the rest of the functionality available in WAML to do whatever I need. Now that I’m able to authenticate using AAD, I won’t need to create, upload, configure, and track my management certificates. Rather, my applications can just make use of Active Directory to log in and manage my subscription’s assets.

I hope you find this to be an exciting new option available in the Windows Azure Management Libraries. I’ve been looking forward to showing this feature off, as I think it shows two awesome areas of the client developer experience – AAD via ADAL and the REST API via WAML – being used together to create some amazing client-side magic against the Windows Azure cloud. Thanks again to the AAD folks for lending a hand from time to time with some of the details and fine tuning!