If you are building Windows Azure websites, chances are you've had to build supporting web services to provide data to those front ends, typically
accessed thru Ajax or jQuery. In this article, we'll examine the preview 5 version of the WCF Web API, available for free on CodePlex, which gives you
a first-class experience for building REST-style services to support your website UIs. I'll show you how to leverage the WCF Web API from within a
Windows Azure ASP.NET MVC 3 web role.
Getting Started
The best way to approach the WCF Web API is to get your hands dirty! In this sample, we will build a variant of the simple contact manager application
included with the WCF Web API samples. I will show how to get the WCF Web API up and running in a web role, then explore some of the API's features. To
get started, make sure you have the Windows Azure SDK August 2011 release installed with Visual Studio 2010, as well as the Fiddler web debugging proxy and the WCF Web API. The easiest way to install the WCF Web API is to use NuGet, which you will want to install before
continuing. You can download NuGet directly from nuget.codeplex.com.
Creating the Project
One of the new cloud project types introduced in the August release of the Azure SDK is ASP.NET MVC 3 Web Role. We begin by creating a new Windows
Azure project and adding to it the .NET 4 role ASP.NET MVC 3 Web Role, as shown in Figure 1. In the New ASP.NET MVC 3 Project dialog (Figure 2), simply
choose an Empty project and click OK.
Figure 1: Creating an ASP.NET MVC 3 web role
Figure 2: Adding an empty MVC project to the web role
Adding the Web API to the Project
To download and add the Web API, just right-click MvcWebRole1, then select Add Library Package Reference. In the dialog, click the Online tab at the
left, and in the search box enter webapi.all, as shown in Figure 3.
Figure 3: Finding the WCF Web API via NuGet
Incidentally, if you type just "webapi", you'll see there's already a small community of contributions built around the WCF Web API. The WebApi.all
package includes the HttpClient, JsonValue, WebApi.Core, WebApi.Enhancements, and WebApi.dll packages. Next, click the Install button, then review and
accept the license.
After the process is completed (the WebApi.dll entry in the dialog will contain a green checkmark-see Figure 4), click Close on the Add Library Package
Reference dialog. You now have several references to WebApi assemblies added to your MVC 3 Web Role project.
Figure 4: Message showing that the WCF Web API is installed
You will find that, conveniently, all the newly added assemblies have been set with a CopyLocal value of true, so that the DLLs will be deployed with
your Windows Azure project (these assemblies are not included in the current Windows Azure OS).
Creating the Service Class
Now, let us turn to creating the create, read, update, and delete (CRUD) service for managing contacts. We add a folder named APIs to the MVC 3 Web
Role project and within that folder add a class named ContactsApi. Decorate the ContactsApi class with the ServiceContract attribute (you will need to
add a using statement for System.ServiceModel).
The next step is to create an MVC route for the service, so it is accessible at api/contacts. This is accomplished by using the MapServiceRoute
extension method included with the WCF Web API. Within Global.asax.cs, we add a using statement for Microsoft.ApplicationServer.Http.Activation and one
for the service type (MvcWebRole1.APIs). Within the RegisterRoutes method, we add a call to MapServiceRoute<T>(), as shown in Figure 5.
Figure 5: Registering the service route
public static void RegisterRoutes(RouteCollection routes)
{
routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
var config = new Microsoft.ApplicationServer.Http.WebApiConfiguration()
{ EnableTestClient = true };
routes.MapServiceRoute<ContactsApi>("api/contacts", config);
routes.MapRoute(
"Default", // Route name
"{controller}/{action}/{id}", // URL with parameters
new { controller = "Home", action = "Index", id = UrlParameter.Optional } // Parameter defaults
);
}
Creating the Entity
Within the MVC 3 Web Role, we create a new folder called Resources that will hold all entity types used. Then we add a new class named Contact.cs
within that folder and give the class an integer ContactId property and a string Name property, as shown in Figure 6.
Figure 6: Simple contact entity
namespace MvcWebRole1.Resources
{
public class Contact
{
public int ContactId { get; set; }
public string Name { get; set; }
}
}