[CORS：跨域資源共享] 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響應報頭一一對應。

---

using System;
using System.Collections.Generic;

namespace System.Web.Cors
{
    public class CorsPolicy
    {
        //其他成員

        // Access-Control-Expose-Headers 
        public IList<string> ExposedHeaders { get; }
        // Access-Control-Allow-Headers 
        public IList<string> Headers { get; }
        // Access-Control-Allow-Methods 
        public IList<string> Methods { get; }
        // Access-Control-Allow-Origin 
        public IList<string> Origins { get; }
        // Access-Control-Max-Age 
        public long? PreflightMaxAge { get; set; }
        // Access-Control-Allow-Credentials 
        public bool SupportsCredentials { get; set; }


    }
}

---

除了上述這6個屬性之外，CorsPolicy還具有如下3個布爾類型的屬性（AllowAnyOrigin、AllowAnyHeader和AllowAnyMethod），它們分別表示是否支持所有的源站點、自定義請求報頭和HTTP方法。

---

using System;
using System.Collections.Generic;

namespace System.Web.Cors
{
    public class CorsPolicy
    {
        //其他成員
        //自定義請求報頭
        public bool AllowAnyHeader { get; set; }
        //HTTP方法。
        public bool AllowAnyMethod { get; set; }
        //源站點
        public bool AllowAnyOrigin { get; set; }

    }
}

二、CorsPolicyProvider

作爲跨域資源請求進行授權檢查的依據，同時用於生成相應的CORS報頭的CorsPolicy對象通過另一個名爲CorsPolicyProvider的對象來提供，所有的CorsPolicyProvider類型均實現了的接口System.Web.Http.Cors.ICorsPolicyProvider。如下面的代碼片斷所示，該接口具有的唯一方法GetCorsPolicyAsync會根據代表但前請求的HttpRequestMessage對象得到表示CORS授權策略的CorsPolicy對象。

 public interface ICorsPolicyProvider
{
    Task<CorsPolicy> GetCorsPolicyAsync(HttpRequestMessage request, CancellationToken cancellationToken);
}

---

實際上我們通過應用在目標HttpController類型或者定義其中的Action方法上用於定義CORS授權策略的System.Web.Http.Cors.EnableCorsAttribute就是ICorsPolicyProvider接口的實現者之一。如下面的代碼片斷所示，EnableCorsAttribute同樣具有6個針對CORS響應報頭的屬性。在實現的GetCorsPolicyAsync方法中，它就是通過這6個屬性對返回的CorsPolicy對象進行初始化。

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

namespace System.Web.Http.Cors
{

    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false)]
    public sealed class EnableCorsAttribute : Attribute, ICorsPolicyProvider
    {

        public EnableCorsAttribute(string origins, string headers, string methods);

        public EnableCorsAttribute(string origins, string headers, string methods, string exposedHeaders);

        public IList<string> ExposedHeaders { get; }

        public IList<string> Headers { get; }

        public IList<string> Methods { get; }

        public IList<string> Origins { get; }

        public long PreflightMaxAge { get; set; }

        public bool SupportsCredentials { get; set; }

        public Task<System.Web.Cors.CorsPolicy> GetCorsPolicyAsync(HttpRequestMessage request, CancellationToken cancellationToken);
    }
}

---

授權的源站點和允許的自定義請求報頭和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返回。

---

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

---

由於應用在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對象。

---

public interface ICorsPolicyProviderFactory
{
     ICorsPolicyProvider GetCorsPolicyProvider(HttpRequestMessage request);
}

---

由於提供的兩個具體CorsPolicyProvider類型（EnableCorsAttribute和DisableCorsAttribute）都是特性，所以ASP.NET Web API定義瞭如下一個AttributeBasedPolicyProviderFactory類型的CorsPolicyProviderFactory以解析特性的方式提供對應的CorsPolicyProvider。

---

public class AttributeBasedPolicyProviderFactory : ICorsPolicyProviderFactory
{    
     public virtual ICorsPolicyProvider GetCorsPolicyProvider(HttpRequestMessage request);
     public ICorsPolicyProvider DefaultPolicyProvider { get; set; }
}

---

實現在GetCorsPolicyProvider方法中的CorsPolicyProvider提供機制很簡單：它直接利用註冊到當前ServicesContainer上的HttpActionSelector根據當前請求獲取用於描述目標Action的HttpActionDescriptor對象，然後調用其GetCustomAttributes方法得到應用到對應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上。

---

public static class CorsHttpConfigurationExtensions
{
  //其他成員
  public static ICorsPolicyProviderFactory GetCorsPolicyProviderFactory(this HttpConfiguration httpConfiguration);
  public static void SetCorsPolicyProviderFactory(this HttpConfiguration httpConfiguration, ICorsPolicyProviderFactory corsPolicyProviderFactory);
}

---

五、總結

綜上所述，CorsPolicy用於描述具體的CORS資源授權策略，它由CorsPolicyProvider來提供，而後者又通過CorsPolicyProviderFactory來創建。如右圖所示的UML揭示了CorsPolicy、CorsPolicyProvider和CorsPolicyProviderFactory相關接口和類之間的關係。對於這些類型來說，除了CorsPolicy定義在程序集System.Web.Cors.dll，其餘的類型均定義在程序集System.Web.Http.Cors.dll中。

---

本文轉載：http://www.cnblogs.com/artech/p/cors-4-asp-net-web-api-06.html