配置 ASP.NET Web API 2

项目
07/13/2023

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

配置设置
使用 ASP.NET 托管配置 Web API
使用 OWIN 自承载配置 Web API
全局 Web API 服务
按控制器配置

配置设置

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

成员	说明
DependencyResolver	为控制器启用依赖项注入。请参阅使用 Web API 依赖项解析程序。
筛选器	操作筛选器。
格式化程序	媒体类型格式化程序。
IncludeErrorDetailPolicy	指定服务器是否应在 HTTP 响应消息中包含错误详细信息，例如异常消息和堆栈跟踪。请参阅 IncludeErrorDetailPolicy。
初始化	执行 HttpConfiguration 的最终初始化的函数。
MessageHandlers	HTTP 消息处理程序。
ParameterBindingRules	用于在控制器操作上绑定参数的规则集合。
属性	泛型属性包。
Routes	路由的集合。请参阅 ASP.NET Web API 中的路由。
服务	服务的集合。请参阅服务。

先决条件

Visual Studio 2017 Community、Professional 或 Enterprise 版本。

使用 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 API”，“ ASP.NET Web 应用程序”项目 模板会自动设置配置代码。

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

“解决方案资源管理器”对话框的屏幕截图，其中“应用开始”文件夹中的 Web A P I 配置点 c 以红色边框显示。

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 使用这些服务来执行各种任务，例如控制器选择和内容协商。

注意

服务集合不是用于服务发现或依赖项注入的常规用途机制。它仅存储 Web API 框架已知的服务类型。

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

Single-Instance服务

服务	说明
IActionValueBinder	获取参数的绑定。
IApiExplorer	获取应用程序公开的 API 的说明。请参阅为 Web API 创建帮助页。
IAssembliesResolver	获取应用程序的程序集列表。请参阅路由和操作选择。
IBodyModelValidator	验证媒体类型格式化程序从请求正文中读取的模型。
IContentNegotiator	执行内容协商。
IDocumentationProvider	提供 API 的文档。默认值为 null。请参阅为 Web API 创建帮助页。
IHostBufferPolicySelector	指示主机是否应缓冲 HTTP 消息实体正文。
IHttpActionInvoker	调用控制器操作。请参阅路由和操作选择。
IHttpActionSelector	选择控制器操作。请参阅路由和操作选择。
IHttpControllerActivator	激活控制器。请参阅路由和操作选择。
IHttpControllerSelector	选择控制器。请参阅路由和操作选择。
IHttpControllerTypeResolver	提供应用程序中的 Web API 控制器类型的列表。请参阅路由和操作选择。
ITraceManager	初始化跟踪框架。请参阅 ASP.NET Web API中的跟踪。
ITraceWriter	提供跟踪编写器。默认值为“无操作”跟踪编写器。请参阅 ASP.NET Web API中的跟踪。
IModelValidatorCache	提供模型验证器的缓存。

Multiple-Instance服务

服务	说明
IFilterProvider	返回控制器操作的筛选器列表。
ModelBinderProvider	返回给定类型的模型联编程序。
ModelMetadataProvider	为模型提供元数据。
ModelValidatorProvider	为模型提供验证程序。
ValueProviderFactory	创建值提供程序。有关详细信息，请参阅 Mike Stall 的博客文章如何在 WebAPI 中创建自定义值提供程序

若要向多实例服务添加自定义实现，请对 Services 集合调用 Add 或 Insert：

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

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

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

Per-Controller配置

可以基于每个控制器替代以下设置：

媒体类型格式化程序
参数绑定规则
服务

为此，请定义实现 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 对象。

通过