Developers need to grok Windows Azure, especially developers who want to distribute consumption of an application in a web-based API. A great use for Microsoft Azure, obviously, is to use it to host an application’s web service API layer. This post will demonstrate how to host WCF services in an Azure worker role in a manner that will offer REST-like JSON API support.
WCF Can do JSON, and it isn’t Difficult
I promise. Most of the examples you’ll see cover possibly too much of the configuration specifics and focus on how Visual Studio can generate proxies for you. Though that’s a great facet of the IDE, there are some natural limitations to comprehending the moving parts within WCF if you always let the IDE take care of the plumbing. Once you get into implementing JSON services in WCF, the IDE generation can actually make things more difficult. If you'd like to follow along in the Visual Studio solution you can download it here.
To start with, here’s a snap shot of the Visual Studio solution. Each project should be relatively self-explanatory in purpose. Each will be examined in a moment.
At this point, a closer examination of each project is in order. Don’t worry, there’s not a lot to each project. This won’t take long. You’ll be amazed how easy it could’ve been the whole time and even more amazed how easy it is to get your JSON API’s into Windows Azure.
Service Contract and Implementation
This example will be a simple and familiar one; the service layer will expose calculator functionality. Hopefully, a later blog post will go into more detail on complex messaging, but for now, a calculator serves the explanation well.
The screen shot below demonstrates the ICalculator service interface. Note it has been decorated with the typical service model attributes, as well as the WebInvoke attribute. Within the WebInvoke attribute’s constructor, JSON is being used as a request and response style.
This attribute code simply says “when the application hosts this service, use JSON as the serialization syntax.” It’ll be important that those attributes are on the interface later on in this post. For now, just take a look at the implementation in the screen shot below.
As you’ve seen, the service contract interface is not only where the abstraction is defined, but how the service is used from within WCF. The next piece of the puzzle is how the service will be hosted within a Windows Azure worker role process.
Hosting WCF JSON Services in Windows Azure
There are a number of great resources on StackOverflow or CodeProject on the details of hosting a WCF service in Azure, so this article won’t dive too deeply into the intricacies. Rather, this next section will dive right in and get things done.
WCF Services can be hosted in numerous ways. A few options are available via Windows Azure, from hosting in a typical web application environment to being hosted and configured manually in a Worker Role. The code below demonstrates the second option via a worker role class.
The important method, HostService<TService, TImplementation> is closed in the screen shot above, as it’ll be examined in somewhat more detail below. The HostService method does just what it says – it hosts a WCF service implementation as represented by a decorated WCF interface in the Windows Azure worker role.
This method just declares a new ServiceHost instance, then sets that instance up on the WebHttp binding so that JSON communication can take place. In particular, the code requires one step of configuration take place. The code that looks at the Worker Role environment’s end points collection is shown below.
This stipulates a convention. That each service endpoint will be named in the endpoints configuration according to it’s type’s name. In this example case, the Calculator class is the one that’ll actually be placed on the WCF binding. The screen shot below demonstrate how and in which file this can be set using Visual Studio 2010.
At this point, the worker role should be configured and ready to run. If the project is run in debug mode at this point the computer emulator will open and the trace output is visible. The screen shot below shows the compute emulator running. The highlighted sections are the custom trace messages the code writes at run-time.
The final step is to write a client to consume the service while it is being hosted in Windows Azure.
Calling via a Unit Test
This service only exposes one small unit of functionality, so it stands to reason a unit test could be a good method of testing the service. Sure, it’s test-after, but that argument is for another time! For now, let’s finish this example up by calling the WCF service being hosted in Windows Azure. Just to prove there are no smoke and mirrors, here’s what the URL from the compute emulator will expose when suffixed with the UrlTemplate format from the ICalculator service definition from earlier.
To know about the service, the unit test project will have a reference set to the contracts project. So that the unit test will know how to call the service in the cloud, the unit test project will need a tiny bit of configuration added to it’s app.config file. The screen shot below demonstrates both of these steps.
I mentioned early on that this post would demonstrate proxy formation without the use of the service references functionality of Visual Studio. The class below demonstrates how this can be achieved. By inheriting from the ClientBase<T> class and the interface being exposed by the service, you can create a custom proxy class in a minimal amount of work.
Finally, the unit test can be authored.
When executed, provided the calculator service is being hosted in Azure, the results should be immediate. The test passes, the result of the calculation yielding a correct result.
Looking back at the compute emulator that was running when the unit test client was executed, the evidence the service is handling requests is apparent. The screen shot below highlights a pair of executions from when the test was executed.
This article took a no-nonsense approach to demonstrating how simple it is to host JSON-serialized WCF services in Windows Azure. Azure is an amazing resource for developers who want to expose aspects of their application in open web API’s. Hopefully, this example has demonstrated how easy it is to get started doing just that. Soon, you’ll be RESTing in the Cloud, with your very own WCF JSON API’s.