asp.net core系列 68 Filter管道過濾器

一.概述

　　本篇詳細瞭解一下asp.net core filters，filter叫"篩選器"也叫"過濾器"，是請求處理管道中的特定階段以前或以後運行代碼。filter用於處理橫切關注點。 橫切關注點的示例包括：錯誤處理、緩存、配置、受權和日誌記錄。 filter能夠避免重複代碼，經過Attribute特性來實現filter過濾。Filter適應於 Razor Pages,  API controllers,  mvc controllers。filter基類是IFilterMetadata 接口，該接口只是用來標記是一個filter過濾器。

　　前段時間在項目中實現了IAsyncAuthorizationFilter接口對用戶訪問controller或action進行了受權，在OnAuthorizationAsync方法中使用context.Result可以使管道短道。IAsyncAuthorizationFilter是屬於受權過濾器中的一種。勿在受權過濾器內拋出異常，這是由於所拋出的異常不會被處理。下面是簡要的實現受權代碼：

　　 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
    public class PermissionFilter : Attribute,IAsyncAuthorizationFilter
　　{
　　　　public   Task OnAuthorizationAsync(AuthorizationFilterContext context)
        {
                IIdentity user = context.HttpContext.User.Identity;
                if (!user.IsAuthenticated)
           　　　　 {
　　　　　　　　　　　　//跳轉到登陸頁
  　　　　　　　　　　　　context.Result = new LocalRedirectResult(url);
　　　　　　　　　　　　 return Task.CompletedTask;
   　　　　　　　　　 }
 
 　　　　　　　　//根據當前用戶，判斷當前訪問的action，沒有權限時返回403錯誤
　　　　　　　　 context.Result = new ForbidResult();
            
         　　  return Task.CompletedTask;
　　　　　}
    }

　　在官方文檔中說到："自定義受權篩選器Filter須要自定義受權框架， 建議配置受權策略或編寫自定義受權策略，而不是編寫自定義Filter篩選器"。

　　這裏的意思是說，若是在項目中不使用asp.net core自帶的identity，那麼須要自定義受權框架，也就是須要本身創建一套用戶權限表。 若是使用了identity建議配置受權策略或編寫自定義受權策略。若是不用identity本身創建用戶權限表，那麼就能夠編寫自定義Filter篩選器。我在項目開發中是本身創建了用戶權限表沒有用identity。由於使用identity表還須要擴展字段，並且與EF core結合緊密，若是不使用EF core須要重寫訪問identity表的實現。

　　下面是identity與ef core相關的代碼：　

   services.AddIdentity<ApplicationUser, IdentityRole>()
                .AddEntityFrameworkStores<ApplicationDbContext>()
                .AddDefaultTokenProviders();

   -- TContext必須是DbContext類型
    public static IdentityBuilder AddEntityFrameworkStores<TContext>(this IdentityBuilder builder) where TContext : DbContext

 

二．Filter 篩選器類型

　　　　Authorization filters  受權篩選器

　　　　Resource filters       資源篩選器

　　　　Action filters            操做篩選器 (Razor Pages 中使用 IPageFilter 和 IAsyncPageFilter)

　　　　Exception filters      異常篩選器

　　　　Result filters            結果篩選器

　　　　每種Filter 類型都在Filter 管道中的不一樣階段執行，當用戶請求進來時，通過Filter管道，執行Filter的階段順序以下所示：

　　　　上面每種Filter 類型都有本身的接口，都同時支持同步和異步實現，上面的受權示例就是一個異步實現受權篩選器IAsyncAuthorizationFilter。Filter 接口或直接或間接實現了IFilterMetadata接口，IFilterMetadata接口只是用來標記是一個Filter 。

 

三．filter篩選器做用域

　　(1) 將 attribute特性應用在 action上。

　　(2) 將 attribute特性應用在 controller上。

　　(3) 全局篩選器應用在controller和action上

　　　　下面使用全局篩選器，使用MvcOptions.Filters 集合，添加三個篩選器，以下面的代碼所示：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options =>
    {
        options.Filters.Add(new AddHeaderAttribute("GlobalAddHeader",
            "Result filter added to MvcOptions.Filters"));         // An instance
        options.Filters.Add(typeof(MySampleActionFilter));         // By type
        options.Filters.Add(new SampleGlobalActionFilter());       // An instance
    }).SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

//實現了內置篩選器屬性
public class AddHeaderAttribute : ResultFilterAttribute
//實現了操做篩選器
public class MySampleActionFilter : IActionFilter
//實現了操做篩選器
public class SampleGlobalActionFilter : IActionFilter

 

四．內置篩選器Attribute屬性

　　　　下面都是filter內置的屬性類，須要去實現這些抽象屬性類。

　　　　　　ActionFilterAttribute
　　　　　　ExceptionFilterAttribute
　　　　　　ResultFilterAttribute
　　　　　　FormatFilterAttribute
　　　　　　ServiceFilterAttribute
　　　　　　TypeFilterAttribute

　　下面一個示例是爲響應添加標頭，開發人員來實現ResultFilterAttribute抽象類：

public class AddHeaderAttribute : ResultFilterAttribute
{
    private readonly string _name;
    private readonly string _value;

    public AddHeaderAttribute(string name, string value)
    {
        _name = name;
        _value = value;
    }

    public override void OnResultExecuting(ResultExecutingContext context)
    {
        context.HttpContext.Response.Headers.Add( _name, new string[] { _value });
        base.OnResultExecuting(context);
    }
}

 　　　　經過使用屬性，篩選器可接收參數，將 AddHeaderAttribute 添加到控制器或操做方法，並指定 HTTP 標頭的名稱和值，以下所示：

        [AddHeader("Author", "Steve Smith @ardalis")]
        public IActionResult Hello(string name)
        {
            return Content($"Hello {name}");
        }
    

 

五.Filter三種依賴關係注入

　　　　(1)ServiceFilterAttribute
　　　　(2)TypeFilterAttribute
　　　　(3)在屬性上實現 IFilterFactory。

　　5.1 ServiceFilterAttribute演示

　　　　下面是在 ConfigureServices 中註冊服務篩選器實現類型，內置的ServiceFilterAttribute會從DI 檢索篩選器實例。

public class AddHeaderResultServiceFilter : IResultFilter
{
    private ILogger _logger;
    public AddHeaderResultServiceFilter(ILoggerFactory loggerFactory)
    {
        _logger = loggerFactory.CreateLogger<AddHeaderResultServiceFilter>();
    }

    public void OnResultExecuting(ResultExecutingContext context)
    {
        var headerName = "OnResultExecuting";
        context.HttpContext.Response.Headers.Add(
            headerName, new string[] { "ResultExecutingSuccessfully" });
        _logger.LogInformation($"Header added: {headerName}");
    }

    public void OnResultExecuted(ResultExecutedContext context)
    {
        // Can't add to headers here because response has started.
    }
}

 　　　　在如下代碼中，AddHeaderResultServiceFilter 將添加到 DI 容器中：

　　　　services.AddScoped<AddHeaderResultServiceFilter>();

　　　　在如下代碼中，經過ServiceFilter 屬性，將從 DI 中檢索 AddHeaderResultServiceFilter 篩選器的實例：

[ServiceFilter(typeof(AddHeaderResultServiceFilter))]
public IActionResult Index()
{
    return View();
}

 

六. 各類篩選器介紹

　　6.1 Authorization filters　

　　　　是篩選器管道中第一個運行的篩選器。是控制對Action方法的訪問。

　　　　 在Action以前執行的方法，沒有在Action以後執行的方法。

  　　　  注意：不要在受權篩選器中引起異常

　　　　場景:

　　　　　　若是使用identity,可用配置受權策略或編寫自定義受權策略。詳情查看identity部分。

　　　　　　若是不使用identity，可編寫自定義篩選器。

 

　　6.2 Resource filters

　　　　實現 IResourceFilter 或 IAsyncResourceFilter 接口。

　　　　它執行會覆蓋篩選器管道的絕大部分。

　　　　它在受權篩選器以後運行。

　　　　場景：

　　　　　　能夠防止模型綁定訪問表單數據。

　　　　　　用於上傳大型文件，以防止表單數據被讀入內存。

 

　　6.3 Action filters

　　　　實現 IActionFilter 或 IAsyncActionFilter 接口。

　　　　它圍繞着Action方法的執行。

　　　　它方法中有個重要屬性ActionArguments ，用於讀取action的輸入參數。

　　　　場景:

　　　　　　能夠在該接口的OnActionExecuting方法中進行驗證模型狀態(ModelState.IsValid)，若是狀態無效，則返回錯誤(這個場景頗有用)。

 

　　6.4 Exception filters

　　　　實現 IExceptionFilter 或 IAsyncExceptionFilter。

　　　　它沒有以前和以後的事件,

　　　　可實現該接口的 OnException 或 OnExceptionAsync方法。

　　　　處理 Razor 頁面或控制器建立、模型綁定、操做篩選器或操做方法中發生的未經處理的異常。

　　　　若要處理異常(再也不throw)，請將 ExceptionHandled 屬性設置爲 true。

　　　　場景：

　　　　　　實現常見的錯誤處理策略。

　　　　　　很是適合捕獲發生在action中的異常。

 

　　6.5 Result filters

　　　　實現 IResultFilter 或 IAsyncResultFilter 或 IAlwaysRunResultFilter 或 IAsyncAlwaysRunResultFilter

　　　　它執行圍繞着action結果的執行。當異常篩選器處理異常時，不執行結果篩選器。

　　　　若是在 IResultFilter.OnResultExecuting 中引起異常，則會致使：

　　　　　　(1) 阻止action結果和後續篩選器的執行。

　　　　　　(2) 結果被視爲失敗。

 

 

　　更詳細的資料參考官網文檔，後續在實際項目中應用到的篩選器，將會再本篇繼續補上。

　　參考資料：

　　　　官方文檔

　　　　官方示例代碼