本主题介绍如何配置 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对象。