配置 ASP.NET Web API 2

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

配置设置

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

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

系统必备

Visual Studio 2017 Community、 Professional 或 Enterprise edition。

配置与 ASP.NET 托管的 Web API

在 ASP.NET 应用程序，通过调用来配置 Web API GlobalConfiguration.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 应用程序"项目模板会自动设置的配置代码，如果选择"Web API"中新建 ASP.NET 项目对话框。
在这里插入图片描述
项目模板将创建一个名为在应用中的 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 }
            );
        }
    }
}

项目模板还将添加调用从委托的代码应用程序_启动。

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

配置 `Web API` 与 `OWIN` 自托管

如果带 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 自托管 ASP.NET Web API 2显示了完成的步骤。

全局 Web API 服务

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

[!NOTE]
Services集合不是一种用于服务发现或依赖关系注入的通用机制。它只存储到 Web API 框架已知的服务类型。
Services集合初始化与一组默认的服务，并可以提供自己的自定义实现。某些服务支持多个实例，而其他人可以只有一个实例。 (但是，您还可以提供在控制器级别的服务; 请参阅每个控制器配置。

单实例服务

服务	描述
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	提供了跟踪编写器。默认值为"no op"跟踪编写器。请参阅在 ASP.NET Web API 中进行跟踪。
IModelValidatorCache	提供模型验证程序的缓存。

多实例服务

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

若要添加到多实例服务的自定义实现，调用外或插入上Services集合：

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

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

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对象。