Step 1. Create a new Web API project

Start with a new Web API template.

Step 2. Uninstall the Microsoft.AspNet.Mvc.FixedDisplayModes package.

This package is not needed and will prevent you from updating to the latest nightly build.

Step 3. Install Microsoft.AspNet.WebApi.Cors package from the nightly builds

See the instruction here on using the nightly builds. Once the package source is set, you should be able to see the CORS package (Microsoft.AspNet.WebApi.Cors).

There’s one more step you need to follow (Step 4) before running the application. Otherwise you’ll see the following error.

Step 4. Fix up the binding redirects in web.config

You can just replace the existing <assemblyBinding> with the following.

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:bcl="urn:schemas-microsoft-com:bcl">
  <dependentAssembly>
    <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
    <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
  </dependentAssembly>
  <dependentAssembly>
    <assemblyIdentity name="System.Web.WebPages.Razor" publicKeyToken="31bf3856ad364e35" />
    <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
  </dependentAssembly>
  <dependentAssembly>
    <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
    <bindingRedirect oldVersion="1.0.0.0-5.0.0.0" newVersion="5.0.0.0" />
  </dependentAssembly>
  <dependentAssembly>
    <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
    <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
  </dependentAssembly>
  <dependentAssembly>
    <assemblyIdentity name="EntityFramework" publicKeyToken="b77a5c561934e089" />
    <bindingRedirect oldVersion="0.0.0.0-5.0.0.0" newVersion="5.0.0.0" />
  </dependentAssembly>
  <dependentAssembly>
    <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
    <bindingRedirect oldVersion="1.0.0.0-1.3.0.0" newVersion="1.3.0.0" />
  </dependentAssembly>
</assemblyBinding>

After that, your application should run just fine.

Trying it out

To make a quick cross-origin request you can just browse to the test client that I have hosted on Azure: https://webapisample.azurewebsites.net/Help/Api/GET-api-Values

Click on “Test API”, paste the full URI to your Web API and click “Send”. You’ll see that the request failed because your Web API doesn’t have CORS enabled by default.

Now, let’s enable CORS for your APIs by calling config.EnableCors(new EnableCorsAttribute()) as shown in the sample below. This will enable CORS for all your controllers and allow all origins.  See the feature spec for more information.

Update 04/26/13: The EnableCorsAttribute now requires the allowed origins, headers and methods in the constructor. To allow all, use EnableCorsAttribute(“*”, “*”, “*”).

using System.Web.Http;
using System.Web.Http.Cors;

namespace MvcApplication20
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

            config.EnableSystemDiagnosticsTracing();

            config.EnableCors(new EnableCorsAttribute());
        }
    }
}

After that, the same request will succeed and we get back the response.

Few notes when testing this with IE

• IE does not consider the port to be a part of the Security Identifier (origin) used for Same Origin Policy enforcement. This means if you have test client on localhost:3030 and the Web API on localhost:8080, IE won’t be making a cross-origin request
• When using the test client hosted on azure, you might need to add it to the trusted site to call the Web API hosted on your local machine (localhost)

Hope you find this useful!

Yao

This is especially useful when you want to provide any kind of tooling for Web API. E.g. generating proxies for your Web APIs as part of the build process. Another scenario that can benefit from this is when you want to host the help page separately from your application – you can simply generate the help page as HTML files and then host the generated files anywhere that supports HTML.

To show you how this can be done, I’ve created a simple command-line utility (WebApiHelpPageGenerator.exe) that will statically generate the help page as HTML files. All you need to provide is the path to you application assembly.

The source code can be downloaded at: https://code.msdn.microsoft.com/Design-time-help-page-3048fb43

The binaries can be downloaded at: WebApiHelpPageGenerator.zip

Using the WebApiHelpPageGenerator.exe

The WebApiHelpPageGenerator.exe takes one required parameter (-p) which is the path to your application assembly.

WebApiHelpPageGenerator.exe -p MvcApplication1.dll

You do need to follow a convention in order to opt-in: Having a public static “WebApiConfig” class with a static “Register” method where the API routes are specified. This is the pattern that we have in the default Web API templates.

public static class WebApiConfig

{

    public static void Register(HttpConfiguration config)

    {

        config.Routes.MapHttpRoute(

            name: "DefaultApi",

            routeTemplate: "api/{controller}/{id}",

            defaults: new { id = RouteParameter.Optional }

        );

    }

}

If everything goes well, you will see the following HTML files generated.

You can open the HTML files and even browse through them locally.

Clicking on “GET api/Values” will take you to the “GET-api-values.html”.

Including Controllers from different assembly

Very often you can have the controllers defined on different assemblies. In order to get all of them, simply use the -r flag.

WebApiHelpPageGenerator.exe -p MvcApplication1.dll –r ControllerLibrary1.dll ControllerLibrary2.dll

Generating proxy or other types of documentation

You can extend the WebApiHelpPageGenerator.exe to generate proxy/client or other types of documentation.

To do this, first you need to add the reference to WebApiHelpPageGenerator.exe.

Then, implement the IOutputGenerator. For illustration, I simply printed things out to the console but you can use any templating engine to generate the documentation and save it to files.

using System;

using WebApiHelpPageGenerator;

namespace MyExtension

{

    public class MyOutputGenerator : IOutputGenerator

    {

        public void GenerateIndex(System.Collections.ObjectModel.Collection<System.Web.Http.Description.ApiDescription> apis)

        {

            Console.WriteLine("Generating index.");

        }

        public void GenerateApiDetails(WebApiHelpPage.Models.HelpPageApiModel apiModel)

        {

            Console.WriteLine("Generating something for {0}", apiModel.ApiDescription.ID);

        }

    }

}

Next, just use the -e option to load the assembly where the custom IOutputGenerator is defined.

WebApiHelpPageGenerator.exe -p MvcApplication1.dll -e MyExtension.dll

Update

I’ve implemented a custom IOutputGenerator that will generate a simple JavaScript client. You can download the binary here: WebApiJsClientGenerator.zip

To try it, simply use the -e option.

WebApiHelpPageGenerator.exe -p MvcApplication1.dll -e WebApiJsClientGenerator.dll

It will spit out a file that look like this:

   1: function GetUsers(id) {

   2:     return $.ajax({

   3:         url: "/api/Users/" + id,

   4:         type: "GET"});

   5: }

   6:  

   7: function PostUsers(user) {

   8:     return $.ajax({

   9:         url: "/api/Users",

  10:         type: "POST",

  11:         contentType: "application/json",

  12:         data: JSON.stringify(user)});

  13: }

  14:  

  15: function GetValues() {

  16:     return $.ajax({

  17:         url: "/api/Values",

  18:         type: "GET"});

  19: }

  20:  

  21: function GetValues1(id) {

  22:     return $.ajax({

  23:         url: "/api/Values/" + id,

  24:         type: "GET"});

  25: }

  26:  

  27: function PostValues(value) {

  28:     return $.ajax({

  29:         url: "/api/Values",

  30:         type: "POST",

  31:         contentType: "application/json",

  32:         data: JSON.stringify(value)});

  33: }

  34:  

  35: function PutValues(id, value) {

  36:     return $.ajax({

  37:         url: "/api/Values/" + id,

  38:         type: "PUT",

  39:         contentType: "application/json",

  40:         data: JSON.stringify(value)});

  41: }

  42:  

  43: function DeleteValues(id) {

  44:     return $.ajax({

  45:         url: "/api/Values/" + id,

  46:         type: "DELETE"});

  47: }

* If you’re getting error like “Could not load file or assembly…”, it means that the WebApiJsClientGenerator.dll file is blocked. To unblock it, go to file Properties and click Unblock. After that, the error should go away.

Enjoy!

Yao