配置 ASP.NET Web API 2

本主题介绍如何配置 ASP.NET Web API。

• 配置设置
• 使用 ASP.NET 托管配置 Web API
• 使用 OWIN 自行托管配置 Web API
• 全局 Web API 服务
• Per-Controller 配置

配置设置

Web API 配置设置在 HttpConfiguration 类中定义。

先决条件

Visual Studio 2017 社区版、专业版或企业版。

使用 ASP.NET 托管配置 Web API

在 ASP.NET 应用程序中，通过在 Application_Start 方法中调用 GlobalConfiguration.Configure 来配置 Web API。 Configure 方法接收一个参数类型为 HttpConfiguration 的委托。 在委托对象内执行所有配置。

下面是使用匿名委托的示例：

using System.Web.Http;
namespace WebApplication1
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            GlobalConfiguration.Configure(config =>
            {
                config.MapHttpAttributeRoutes();

                config.Routes.MapHttpRoute(
                    name: "DefaultApi",
                    routeTemplate: "api/{controller}/{id}",
                    defaults: new { id = RouteParameter.Optional }
                );
            });
        }
    }
}

在 Visual Studio 2017 中，“ASP.NET Web 应用程序”项目模板会自动设置配置代码，如果在“ 新建 ASP.NET 项目 ”对话框中选择“Web API”。

“新建 ASP.NET 项目”对话框的屏幕截图，其中选中了“Web API”复选框以自动设置配置代码。

项目模板在App_Start文件夹中创建一个名为WebApiConfig.cs的文件。 此代码文件定义了一个委托，您应在此处放置 Web API 配置代码。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace WebApplication1
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // TODO: Add any additional configuration code.

            // Web API routes
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

项目模板还会添加用于在 Application_Start 中调用委托的代码。

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
    }
}

使用 OWIN Self-Hosting 配置 Web API

如果使用 OWIN 进行自承载，请创建新的 HttpConfiguration 实例。 在此实例上执行任何配置，然后将该实例传递给 Owin.UseWebApi 扩展方法。

public class Startup 
{ 
    public void Configuration(IAppBuilder appBuilder) 
    { 
        HttpConfiguration config = new HttpConfiguration(); 

        config.Routes.MapHttpRoute( 
            name: "DefaultApi", 
            routeTemplate: "api/{controller}/{id}", 
            defaults: new { id = RouteParameter.Optional } 
        ); 

        appBuilder.UseWebApi(config); 
    } 
}

本教程 使用 OWIN Self-Host ASP.NET Web API 2 演示了完整的步骤。

全局 Web API 服务

HttpConfiguration.Services 集合包含一组全局服务，Web API 用于执行各种任务，例如控制器选择和内容协商。

服务集合使用一组默认的服务进行初始化，你可以提供自己的自定义实现。 某些服务支持多个实例，而另一些服务只能有一个实例。 （但是，还可以在控制器级别提供服务;请参阅 Per-Controller 配置。

单实例服务

多实例服务

若要将自定义实现添加到多实例服务，请在服务集合上调用“添加”或“插入”：

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

若要将单实例服务替换为自定义实现，请对服务集合调用 Replace：

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

每个控制器的配置

可以按控制器替代以下设置：

• 媒体类型格式化程序
• 参数绑定规则
• Services

为此，请定义实现 IControllerConfiguration 接口的自定义属性。 然后将该属性应用于控制器。

以下示例将默认媒体类型格式化程序替换为自定义格式化程序。

using System;
using System.Web.Http;
using System.Web.Http.Controllers;

namespace WebApplication1.Controllers
{

    public class UseMyFormatterAttribute : Attribute, IControllerConfiguration
    {
        public void Initialize(HttpControllerSettings settings,
            HttpControllerDescriptor descriptor)
        {
            // Clear the formatters list.
            settings.Formatters.Clear();

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

    [UseMyFormatter]
    public class ValuesController : ApiController
    {
        // Controller methods not shown...
    }
}

IControllerConfiguration.Initialize 方法采用两个参数：

• HttpControllerSettings 对象
• HttpControllerDescriptor 对象

HttpControllerDescriptor 包含控制器的说明，你可以出于信息性目的检查此说明（例如，区分两个控制器）。

使用 HttpControllerSettings 对象配置控制器。 此对象包含可以按控制器替代的配置参数的子集。 未更改的任何设置将默认为全局 HttpConfiguration 对象。