配置 ASP.NET Web API 2

ゝ一纸荒年。 2021-06-26 16:06 407阅读 0赞

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

## 配置设置 ##

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

<table> 
 <thead> 
  <tr> 
   <th>成员</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><strong>DependencyResolver</strong></td> 
   <td>使控制器的依赖关系注入。 请参阅<a rel="nofollow">使用 Web API 依赖关系解析程序</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>筛选器</strong></td> 
   <td>操作筛选器。</td> 
  </tr> 
  <tr> 
   <td><strong>格式化程序</strong></td> 
   <td><a rel="nofollow">媒体类型格式化程序</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IncludeErrorDetailPolicy</strong></td> 
   <td>指定服务器是否应在 HTTP 响应消息中包含错误详细信息，例如异常消息和堆栈跟踪。 请参阅<a href="https://msdn.microsoft.com/library/system.web.http.includeerrordetailpolicy%28v=vs.108%29" rel="nofollow">IncludeErrorDetailPolicy</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>初始值设定项</strong></td> 
   <td>执行的最终初始化的函数<strong>HttpConfiguration</strong>。</td> 
  </tr> 
  <tr> 
   <td><strong>MessageHandlers</strong></td> 
   <td><a rel="nofollow">HTTP 消息处理程序</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>ParameterBindingRules</strong></td> 
   <td>规则的控制器操作上的绑定参数集合。</td> 
  </tr> 
  <tr> 
   <td><strong>属性</strong></td> 
   <td>一个泛型属性包。</td> 
  </tr> 
  <tr> 
   <td><strong>路由</strong></td> 
   <td>路由的集合。 请参阅<a rel="nofollow">ASP.NET Web API 中路由</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>服务</strong></td> 
   <td>服务集合。 请参阅<a rel="nofollow">Services</a>。</td> 
  </tr> 
 </tbody> 
</table>

## 系统必备 ##

[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 项目**对话框。  
![在这里插入图片描述][20210131005200325.png]  
项目模板将创建一个名为在应用中的 `WebApiConfig.cs` 文件`\_`开始文件夹。 此代码文件定义应放置到 `Web API` 配置代码的委托。  
![在这里插入图片描述][20210131005312890.png]

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**集合初始化与一组默认的服务，并可以提供自己的自定义实现。 某些服务支持多个实例，而其他人可以只有一个实例。 (但是，您还可以提供在控制器级别的服务; 请参阅每个控制器配置。

单实例服务

<table> 
 <thead> 
  <tr> 
   <th>服务</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><strong>IActionValueBinder</strong></td> 
   <td>获取参数绑定。</td> 
  </tr> 
  <tr> 
   <td><strong>IApiExplorer</strong></td> 
   <td>获取应用程序公开的 Api 的说明。 请参阅<a rel="nofollow">创建 Web API 帮助页</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IAssembliesResolver</strong></td> 
   <td>获取应用程序的程序集的列表。 请参阅<a rel="nofollow">路由和操作选择</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IBodyModelValidator</strong></td> 
   <td>验证从请求正文的媒体类型格式化程序读取的模型。</td> 
  </tr> 
  <tr> 
   <td><strong>IContentNegotiator</strong></td> 
   <td>执行内容协商。</td> 
  </tr> 
  <tr> 
   <td><strong>IDocumentationProvider</strong></td> 
   <td>提供了有关 Api 文档。 默认值是<strong>null</strong>。 请参阅<a rel="nofollow">创建 Web API 帮助页</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IHostBufferPolicySelector</strong></td> 
   <td>指示主机是否应缓冲 HTTP 消息实体正文。</td> 
  </tr> 
  <tr> 
   <td><strong>IHttpActionInvoker</strong></td> 
   <td>调用控制器操作。 请参阅<a rel="nofollow">路由和操作选择</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IHttpActionSelector</strong></td> 
   <td>选择了控制器操作。 请参阅<a rel="nofollow">路由和操作选择</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IHttpControllerActivator</strong></td> 
   <td>激活一个控制器。 请参阅<a rel="nofollow">路由和操作选择</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IHttpControllerSelector</strong></td> 
   <td>选择控制器。 请参阅<a rel="nofollow">路由和操作选择</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IHttpControllerTypeResolver</strong></td> 
   <td>提供了一系列应用程序中的 Web API 控制器类型。 请参阅<a rel="nofollow">路由和操作选择</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>ITraceManager</strong></td> 
   <td>初始化跟踪框架。 请参阅<a rel="nofollow">在 ASP.NET Web API 中进行跟踪</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>ITraceWriter</strong></td> 
   <td>提供了跟踪编写器。 默认值为"no op"跟踪编写器。 请参阅<a rel="nofollow">在 ASP.NET Web API 中进行跟踪</a>。</td> 
  </tr> 
  <tr> 
   <td><strong>IModelValidatorCache</strong></td> 
   <td>提供模型验证程序的缓存。</td> 
  </tr> 
 </tbody> 
</table>

多实例服务

<table> 
 <thead> 
  <tr> 
   <th>服务</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><strong>IFilterProvider</strong></td> 
   <td>返回控制器操作的筛选器的列表。</td> 
  </tr> 
  <tr> 
   <td><strong>ModelBinderProvider</strong></td> 
   <td>返回给定类型的模型联编程序。</td> 
  </tr> 
  <tr> 
   <td><strong>ModelMetadataProvider</strong></td> 
   <td>提供模型元数据。</td> 
  </tr> 
  <tr> 
   <td><strong>ModelValidatorProvider</strong></td> 
   <td>为模型提供验证程序。</td> 
  </tr> 
  <tr> 
   <td><strong>ValueProviderFactory</strong></td> 
   <td>创建值提供程序。 有关详细信息，请参阅 Mike Stall 博客文章<a href="https://blogs.msdn.com/b/jmstall/archive/2012/04/23/how-to-create-a-custom-value-provider-in-webapi.aspx" rel="nofollow">如何在 WebAPI 中创建的自定义值提供程序</a></td> 
  </tr> 
 </tbody> 
</table>

若要添加到多实例服务的自定义实现，调用**外**或**插入**上**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**对象。

[HttpConfiguration]: https://msdn.microsoft.com/library/system.web.http.httpconfiguration.aspx
[Visual Studio 2017]: https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=button+cta&utm_content=download+vs2017
[GlobalConfiguration.Configure]: https://msdn.microsoft.com/library/system.web.http.globalconfiguration.configure.aspx
[20210131005200325.png]: /images/20210626/30f65ad8980942c6acc2f527b78b2fe9.png
[20210131005312890.png]: /images/20210626/495b06120282453086c7270f88b97152.png