Home/Web API/Overview/Chapter 11. Extensibility/Configuring ASP.NET Web API

This topic describes how to configure ASP.NET Web API.

• Global Configuration Settings (ASP.NET Hosting)
• Global Configuration Settings (Self-Hosting)
• Services
• Per-Controller Configuration

Global Configuration Settings (ASP.NET Hosting)

If you are hosting in ASP.NET, the global configuration settings for Web API are stored in the GlobalConfiguration object, which is contains a singleton HttpConfiguration instance. The HttpConfiguration object contains the following members.

Make any configuration changes inside the Application_Start method. The Visual Studio "ASP.NET MVC 4 Web Application" project template includes a class named WebApiConfig that is intended for Web API configuration.

If you create a new project using this template and open the Global.asax file, you will see that the Application_Start method looks like this:

protected void Application_Start()
{
    AreaRegistration.RegisterAllAreas();

    WebApiConfig.Register(GlobalConfiguration.Configuration);
    FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
}

The call to WebApiConfig.Register configures Web API. The definition for the WebApiConfig class is located in the App_Start directory.

The WebApiConfig.Register method adds the default Web API route, and is a good place to add any other global configuration code for Web API.

You don't need to use the WebApiConfig class; it's simply a convenient way to organize your code.

Global Configuration Settings (Self-Hosting)

If you self-host Web API, the configuration settings are stored in the HttpSelfHostConfiguration class, which derives from HttpConfiguration. For example:

var config = new HttpSelfHostConfiguration("http://localhost:8080");

// Add a route
config.Routes.MapHttpRoute(
    "API Default", 
    "api/{controller}/{id}", 
    new { id = RouteParameter.Optional });

// Add a media-type formatter
config.Formatters.Add(new MyFormatter()); 

For more information about self-hosting, see Self-Host a Web API.

Services

The HttpConfiguration.Services collection contains a set of global services that Web API uses to perform various tasks, such as controller selection and content negotiation.

The Services collection is not a general-purpose mechanism for service discovery or dependency injection. The Services collection only stores service types that are known to the framework.

The Services collection is initialized with a default set of services, and you can provide your own custom implementations. Some services support multiple instances, while others can have only one instance. (However, you can also provide services at the controller level; see Per-Controller Configuration.

To replace a single-instance service with your own implementation, call Replace on the Services collection:

config.Services.Replace(typeof(ITraceWriter), new MyTraceWriter());

For multiple-instance services, call Add or Insert to add a new instance to the collection:

config.Services.Add(typeof(IFilterProvider), new MyFilterProvider());

Per-Controller Configuration

The HttpConfiguration object holds global settings for Web API. You can also override certain settings for a particular controller. The settings that you can override per controller are:

• Media-type formatters
• Parameter binding rules
• Services

To configure a controller, create a custom attribute that implements the IControllerConfiguration interface. For example:

public class ControllerConfigAttribute : Attribute, IControllerConfiguration
{
    public void Initialize(HttpControllerSettings settings, 
        HttpControllerDescriptor descriptor)
    {
        // Remove the JSON formatter.
        var jsonFormatter = settings.Formatters.JsonFormatter;
        settings.Formatters.Remove(jsonFormatter);

        // Add a custom media-type formatter.
        settings.Formatters.Add(new MyFormatter());

        // Add a custom action selector.
        settings.Services.Replace(typeof(IHttpActionSelector), new MyActionSelector());
    }
}

Then apply the attribute to the controller:

[ControllerConfig]
public class ValuesController : ApiController
{
    // ...
}

The IControllerConfiguration.Initialize method takes two parameters:

• An HttpControllerSettings object
• An HttpControllerDescriptor object

The HttpControllerDescriptor contains a description of the controller, which you can examine for informational purposes (say, to distinguish between two controllers).

Use the HttpControllerSettings object to configure the controller. This object contains the subset of configuration parameters that you can override on a per-controller basis. The previous example modified the formatter collection and replaced the IHttpActionSelector service. Any settings that you don't change will default to the global HttpConfiguration object.

By Mike Wasson, Mike Wasson is a programmer-writer at Microsoft.