Thursday, July 31, 2014

How to generate strongly typed C# client for ASP.NET Web API

Recently, I was looking out for ways to consume the ASP.NET Web API via strongly typed C# client (i.e. a client similar to C# Web Service Client).

Initially I thought, Microsoft would have a utility to generate the client but, I was wrong, they don't have any such utility.  Why would they not provide such a utility is beyond me, I really don't understand why would they not expose such a utility, it would have benefited everyone who wants to consume Web API using strongly typed classes.

None the less, After a bit of googling, I found this awesome open-source project which does exactly what I needed.

The detailed instruction on how to use it can be found here.  In summary you need to do the following steps to generate the strongly typed C# client for ASP.NET Web API

How do they do it!

Setting up the Server
  • Install the NuGet package "WebApiProxy" into the project that hosts the Web API.  This package will host a proxy endpoint for your service.  This proxy endpoint can be used as the JavaScript client to invoke the Web API via JavaScript.  The endpoint will be hosted at URL "/api/proxies"
  • Once you have this installed in your Web API, if you browse the URL "/api/proxies" you should see a JavaScript client already generated!
  • This package also exposes the metadata necessary to automatically generate the C# client.
Creating the client
  • Create a Client project which will be used to invoke the Web API via C#.
  • Install the NuGet package "WebApiProxy.CSharp" into this project.  This package seamlessly integrates the proxy generation build task with the project build step.  
  • Every time you rebuild the project it will try and generate the C# client for the desired Web API.
  • The configuration required to generate the C# client is placed in a file called "WebApiProxy.config"
  • This is the simplest XML file I have ever seen.  It only expects you to provide the 
    • endpoint - The location of the Web API where it will be hosted.
    • namespace - The namespace in which the C# client will be generated.
  • That's about all the setup that is needed to generate the strongly typed C# client for a given Web API
  • Imagine you have an EmployeeController on the Service side. 
  • We can invoke this Web API via our generated client as follows
  • As you can see its very straightforward and intuitive to invoke the Web API with strongly typed C# client.
Further Reading
  •  I went ahead and modified the source code to generate not just the Async method but also the Sync version of the Web API.  
  • This is done so that anyone who wants to invoke the Web API in a Sync manner does not have to deal with the Async behaviour.
  • The above code for Sync invocation can be reduced to the following
  • Updated source can be found here
  • TIP: In case if you are trying to modify the source to suite your needs, make sure that you kill the MSBuild process before you rebuild the Task and the Client.
Thats all folks!  
Have some Fun!