ASP.NET Web API自身对CORS的支持: EnableCorsAttribute特性背后的故事

简介:

从编程的角度来讲,ASP.NET Web API针对CORS的实现仅仅涉及到HttpConfiguration的扩展方法EnableCors和EnableCorsAttribute特性。但是整个CORS体系不限于此,在它们背后隐藏着一系列的类型,我们将会利用本章余下的内容对此作全面讲述,今天我们就来讨论一下用于定义CORS授权策略的EnableCorsAttribute特性背后的故事。

目录
一、CorsPolicy
二、CorsPolicyProvider
三、CorsPolicyProviderFactory
四、CorsPolicyProviderFactory的注册
五、总结

一、CorsPolicy

通过将EnableCorsAttribute特性应用到HttpController类型或者定义其中的某个Action方法上,我们可以为提供的资源定义相应的授权策略。ASP.NET Web API最终会利用这些策略对请求(包括预检请求)进行解析并生成相应的CORS响应报头。在ASP.NET Web API的应用编程接口中,CORS授权策略通过CorsPolicy类型表示。

通过《W3C的CORS规范》的介绍,我们知道针对跨域资源的授权策略不仅仅要求请求的源站点值得信任,还涉及到对请求采用的HTTP方法、携带的自定义报头和用户凭证的要求,以及针对自定义响应报头的授权等。除此之外,为了避免频繁浏览器频繁地发送预检请求,它可以将响应的结果进行缓存,而这又涉及到对缓存过期时间的控制。总得来说,这些授权策略体现在如下6个CORS响应报头上。

  • Access-Control-Allow-Origin
  • Access-Control-Expose-Headers
  • Access-Control-Allow-Methods
  • Access-Control-Allow-Headers
  • Access-Control-Max-Age
  • Access-Control-Allow-Credentials

在ASP.NET Web API的应用编程接口中,围绕着这6个CORS响应报头的授权策略通过类型System.Web.Cors.CorsPolicy来表示。CorsPolicy具有如下6个属性正好与上面这6个CORS响应报头一一对应。

   1: public class CorsPolicy
   2: {
   3:     //其他成员
   4:     public IList<string>     Origins { get; }
   5:     public IList<string>     ExposedHeaders { get; }
   6:     public IList<string>     Headers { get; }
   7:     public IList<string>     Methods { get;; }
   8:     public long?             PreflightMaxAge { get; set; }
   9:     public bool              SupportsCredentials { get; set; }
  10: }

除了上述这6个属性之外,CorsPolicy还具有如下3个布尔类型的属性(AllowAnyOrigin、AllowAnyHeader和AllowAnyMethod),它们分别表示是否支持所有的源站点、自定义请求报头和HTTP方法。

   1: public class CorsPolicy
   2: {
   3:     //其他成员
   4:     public bool AllowAnyOrigin { get; set; }
   5:     public bool AllowAnyHeader { get; set; }
   6:     public bool AllowAnyMethod { get; set; }
   7: }

 

二、CorsPolicyProvider

作为跨域资源请求进行授权检查的依据,同时用于生成相应的CORS报头的CorsPolicy对象通过另一个名为CorsPolicyProvider的对象来提供,所有的CorsPolicyProvider类型均实现了的接口System.Web.Http.Cors.ICorsPolicyProvider。如下面的代码片断所示,该接口具有的唯一方法GetCorsPolicyAsync会根据代表但前请求的HttpRequestMessage对象得到表示CORS授权策略的CorsPolicy对象。

   1: public interface ICorsPolicyProvider
   2: {
   3:     Task<CorsPolicy> GetCorsPolicyAsync(HttpRequestMessage request, CancellationToken cancellationToken);
   4: }

实际上我们通过应用在目标HttpController类型或者定义其中的Action方法上用于定义CORS授权策略的System.Web.Http.Cors.EnableCorsAttribute就是ICorsPolicyProvider接口的实现者之一。如下面的代码片断所示,EnableCorsAttribute同样具有6个针对CORS响应报头的属性。在实现的GetCorsPolicyAsync方法中,它就是通过这6个属性对返回的CorsPolicy对象进行初始化。

   1: [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple=false)]
   2: public sealed class EnableCorsAttribute : Attribute, ICorsPolicyProvider
   3: {    
   4:     public EnableCorsAttribute(string origins, string headers, string methods);
   5:     public EnableCorsAttribute(string origins, string headers, string methods,string exposedHeaders);
   6:  
   7:     public Task<CorsPolicy> GetCorsPolicyAsync(HttpRequestMessage request, CancellationToken cancellationToken);
   8:     
   9:     public IList<string> Origins { get; }
  10:     public IList<string> ExposedHeaders { get; }
  11:     public IList<string> Headers { get; }
  12:     public IList<string> Methods { get; }
  13:     public long          PreflightMaxAge { get; set; }
  14:     public bool          SupportsCredentials { get; set; }
  15: }

授权的源站点和允许的自定义请求报头和HTTP方法,以及暴露给客户端JavaScript程序的自定义响应报头均可以直接通过构造函数参数来指定。对于这4个参数,我们可以指定某个单一的值(比如origin="http://www.artech.com"),也可以指定一个通过逗号分割的列表(比如origin="http://www.artech.com, http://www.jinnan.me")。除了exposedHeaders之外,我们还可以指定“*”作为其参数值,意味着不对此作任何限制,它们会控制生成CorsPolicy对象的3个对应布尔类型属性值(AllowAnyOrigin、AllowAnyHeader和AllowAnyMethod)。

除了EnableCorsAttribute特性之外,在“System.Web.Http.Cors”命名空间下还定义着另一个与之相对的特性DisableCorsAttribute。顾名思义,如果DisableCorsAttribute特性被应用到某个HttpController类型或者定义其中的某个Action方法上,意味着目标HttpController或者Action不支持跨域资源共享。如下面的代码片断所示,在实现的GetCorsPolicyAsync方法中,并没有一个具体的CorsPolicy返回。

   1: [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple=false)]
   2: public sealed class DisableCorsAttribute : Attribute, ICorsPolicyProvider
   3: {
   4:     public Task<CorsPolicy> GetCorsPolicyAsync(HttpRequestMessage request, CancellationToken cancellationToken)
   5:     {
   6:         return Task.FromResult<CorsPolicy>(null);
   7:     }
   8: }

由于应用在Action方法上的CorsPolicyProvider特性比应用在HttpController类型上的特性具有更好的选择优先级,所以对于一个定义了众多Action方法的HttpController类型来说,如果绝大部分Action方法均需要提供跨域资源共享的支持并具有相同的资源授权策略,可以直接在HttpController类型上应用EnableCorsAttribute特性并作相应的设置。对于不需要支持跨域资源共享的Action来说,直接在对应的方法上应用DisableCorsAttribute特性即可。如果某个Action具有特殊的授权需求,可以通过应用的EnableCorsAttribute特性作针对性设置。反之亦然。

三、CorsPolicyProviderFactory

CorsPolicyProvider用于提供用于描述CORS授权策略的CorsPolicy对象,其自身又通过对应的CorsPolicyProviderFactory来创建,所有的CorsPolicyProviderFactory类型均实现了接口System.Web.Http.Cors.ICorsPolicyProviderFactory。如下面的代码片断所示,该接口具有的唯一方法GetCorsPolicyProvider会根据代表当前请求的HttpRequestMessage对象来提供对应的CorsPolicyProvider对象。

   1: public interface ICorsPolicyProviderFactory
   2: {
   3:     ICorsPolicyProvider GetCorsPolicyProvider(HttpRequestMessage request);
   4: }

由于提供的两个具体CorsPolicyProvider类型(EnableCorsAttribute和DisableCorsAttribute)都是特性,所以ASP.NET Web API定义了如下一个AttributeBasedPolicyProviderFactory类型的CorsPolicyProviderFactory以解析特性的方式提供对应的CorsPolicyProvider。

   1: public class AttributeBasedPolicyProviderFactory : ICorsPolicyProviderFactory
   2: {    
   3:     public virtual ICorsPolicyProvider GetCorsPolicyProvider(HttpRequestMessage request);
   4:     public ICorsPolicyProvider DefaultPolicyProvider { get; set; }
   5: }

实现在GetCorsPolicyProvider方法中的CorsPolicyProvider提供机制很简单:它直接利用注册到当前ServicesContainer上的HttpActionSelector根据当前请求获取用于描述目标Action的HttpActionDescriptor对象,然后调用其GetCustomAttributes<T>方法得到应用到对应Action方法上的第一个实现了ICorsPolicyProvider接口的特性。如果这样的特性不存在,则获取描述所在HttpController类型的HttpControllerDescritor对象,采用同样的方式得到应用在目标HttpController类型上的第一个实现了ICorsPolicyProvider接口的特性。

关于针对目标Action的选择问题,有一个核心的核心的细节值得关注:如果当前请求并非真正的跨域资源请求,而仅仅是一个采用“OPTIONS”作为HTTP方法的预检请求(Preflight Request),利用注册的HttpActionSelector根据当前请求是无法将目标Action选择出来的,所以需要将请求的HTTP方法替换成真正跨域资源请求采用的HTTP方法。通过上面针对W3C的CORS规范的介绍我们知道,此HTTP方法可以通过预检请求的“Access-Control-Request-Method”报头获得。实际上在上一个“通过自定义HttpMessageHandler实现CORS”的实例中,我们已经对此作个过演示了。

从上面给出的针对AttributeBasedPolicyProviderFactory的定义可以看出,除了实现的方法GetCorsPolicyProvider方法之外,它还具有一个DefaultPolicyProvider属性。该属性表示默认采用的CorsPolicyProvider,如果没有任何实现ICorsPolicyProvider接口的特性被应用到目标Action方法和它所在的HttpController类型上,该属性将会作为GetCorsPolicyProvider方法的返回值。

四、CorsPolicyProviderFactory的注册

ASP.NET Web API默认使用的CorsPolicyProviderFactory需要注册到当前的HttpConfiguration上。具体来说,所谓注册CorsPolicyProviderFactory实际上就是将它保存到当前HttpConfiguration的Properties属性表示的字典中。CorsPolicyProviderFactory的注册可以通过HttpConfiguration如下所示的扩展方法SetCorsPolicyProviderFactory来完成。

另一扩展方法GetCorsPolicyProviderFactory 则用于获取成功注册的CorsPolicyProviderFactory。如果调用该方法CorsPolicyProviderFactory尚未被注册,一个AttributeBasedPolicyProviderFactory对象会被创建出来并注册到HttpConfiguration上。

   1: public static class CorsHttpConfigurationExtensions
   2: {
   3:     //其他成员
   4:     public static ICorsPolicyProviderFactory GetCorsPolicyProviderFactory(this HttpConfiguration httpConfiguration);
   5:     public static void SetCorsPolicyProviderFactory(this HttpConfiguration httpConfiguration, ICorsPolicyProviderFactory corsPolicyProviderFactory);
   6: }

五、总结

综上所述,CorsPolicy用于描述具体的CORS资源授权策略,它由CorsPolicyProvider来提供,而后者又通过CorsPolicyProviderFactory来创建。如右图所示的UML揭示了CorsPolicy、CorsPolicyProvider和CorsPolicyProviderFactory相关接口和类之间的关系。对于这些类型来说,除了CorsPolicy定义在程序集System.Web.Cors.dll,其余的类型均定义在程序集System.Web.Http.Cors.dll中。

 

CORS系列文章
[1] 同源策略与JSONP
[2] 利用扩展让ASP.NET Web API支持JSONP
[3] W3C的CORS规范
[4] 利用扩展让ASP.NET Web API支持CORS
[5] ASP.NET Web API自身对CORS的支持: 从实例开始
[6] ASP.NET Web API自身对CORS的支持: CORS授权策略的定义和提供
[7] ASP.NET Web API自身对CORS的支持: CORS授权检验的实施
[8] ASP.NET Web API自身对CORS的支持: CorsMessageHandler


作者:蒋金楠
微信公众账号:大内老A
微博: www.weibo.com/artech
如果你想及时得到个人撰写文章以及著作的消息推送,或者想看看个人推荐的技术资料,可以扫描左边二维码(或者长按识别二维码)关注个人公众号(原来公众帐号 蒋金楠的自媒体将会停用)。
本文版权归作者和博客园共有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出原文连接,否则保留追究法律责任的权利。
相关文章
|
5月前
|
开发框架 前端开发 JavaScript
ASP.NET Web Pages - 教程
ASP.NET Web Pages 是一种用于创建动态网页的开发模式,采用HTML、CSS、JavaScript 和服务器脚本。本教程聚焦于Web Pages,介绍如何使用Razor语法结合服务器端代码与前端技术,以及利用WebMatrix工具进行开发。适合初学者入门ASP.NET。
|
7月前
|
Java API 数据库
构建RESTful API已经成为现代Web开发的标准做法之一。Spring Boot框架因其简洁的配置、快速的启动特性及丰富的功能集而备受开发者青睐。
【10月更文挑战第11天】本文介绍如何使用Spring Boot构建在线图书管理系统的RESTful API。通过创建Spring Boot项目,定义`Book`实体类、`BookRepository`接口和`BookService`服务类,最后实现`BookController`控制器来处理HTTP请求,展示了从基础环境搭建到API测试的完整过程。
113 4
|
7月前
|
SQL 安全 PHP
PHP 自发布以来一直在 Web 开发领域占据重要地位,PHP 8 更是带来了属性、刚性类型等新特性。
【10月更文挑战第1天】PHP 自问世以来,凭借其易用性和灵活性,在 Web 开发领域迅速崛起。从简单的网页脚本语言逐步演进为支持面向对象编程的现代语言,尤其自 PHP 5.3 引入命名空间后,代码组织和维护变得更加高效。PHP 7 的性能优化和 PHP 8 的新特性(如属性和刚性类型)进一步巩固了其地位。框架如 Laravel、Symfony、Yii2 和 CodeIgniter 等简化了开发流程,提高了效率和安全性。
115 2
|
4月前
|
开发框架 数据可视化 .NET
.NET 中管理 Web API 文档的两种方式
.NET 中管理 Web API 文档的两种方式
79 14
|
6月前
|
开发框架 .NET 程序员
驾驭Autofac,ASP.NET WebApi实现依赖注入详细步骤总结
Autofac 是一个轻量级的依赖注入框架,专门为 .NET 应用程序量身定做,它就像是你代码中的 "魔法师",用它来管理对象的生命周期,让你的代码更加模块化、易于测试和维护
179 4
驾驭Autofac,ASP.NET WebApi实现依赖注入详细步骤总结
|
5月前
|
开发框架 .NET PHP
ASP.NET Web Pages - 添加 Razor 代码
ASP.NET Web Pages 使用 Razor 标记添加服务器端代码,支持 C# 和 Visual Basic。Razor 语法简洁易学,类似于 ASP 和 PHP。例如,在网页中加入 `@DateTime.Now` 可以实时显示当前时间。
|
7月前
|
开发框架 .NET API
Windows Forms应用程序中集成一个ASP.NET API服务
Windows Forms应用程序中集成一个ASP.NET API服务
154 9
|
7月前
|
安全 编译器 API
探索PHP 8的新特性及其对现代Web开发的影响
【10月更文挑战第5天】随着PHP 8的发布,这门历史悠久的脚本语言重获新生。PHP 8引入了联合类型、命名参数、属性、空安全运算符及JIT编译器等一系列新特性,不仅提升了开发者的编程体验,还增强了PHP在现代Web开发领域的竞争力。本文将详细介绍这些新特性及其对Web开发的影响。例如,联合类型允许函数参数接受多种类型,提高代码灵活性;命名参数则使函数调用更加直观易懂;属性可用于装饰类、方法等,提供额外信息;空安全运算符避免了访问未定义属性时的错误;JIT编译器则显著提升了性能。这些改进共同提升了代码质量和开发效率,巩固了PHP在Web开发中的地位。
53 4
|
7月前
|
存储 开发框架 .NET
.NET 8 实现无实体库表 API 部署服务
【10月更文挑战第12天】在.NET 8中,可通过以下步骤实现无实体库表的API部署:首先安装.NET 8 SDK及开发工具,并选用轻量级Web API框架如ASP.NET Core;接着创建新项目并设计API,利用内存数据结构模拟数据存储;最后配置项目设置并进行测试与部署。此方法适用于小型项目或临时解决方案,但对于大规模应用仍需考虑持久化存储以确保数据可靠性与可扩展性。
|
7月前
|
监控 安全 API
Docker + .NET API:简化部署和扩展
Docker + .NET API:简化部署和扩展
92 1

热门文章

最新文章