[ASP.NET MVC 小牛之路]11 - Filter

Filter（篩選器）是基於AOP（面向切面程式設計）的設計，它的作用是對MVC框架處理客戶端請求注入額外的邏輯，以非常簡單優美的方式實現橫切關注點(Cross-cutting Concerns)。橫切關注點是指橫越應該程式的多個甚至所有模組的功能，經典的橫切關注點有日誌記錄、快取處理、異常處理和許可權驗證等。本文將分別介紹MVC框架所支援的不同種類的Filter的建立和使用，以及如何控制它們的執行。

本文目錄

四種基本 Filter 概述

MVC框架支援的Filter可以歸為四類，每一類都可以對處理請求的不同時間點引入額外的邏輯處理。這四類Filter如下表：

在MVC框架呼叫acion之前，它會先判斷有沒有實現上表中的介面的特性，如果有，則在請求管道的適當的點呼叫特性中定義的方法。

MVC框架為這些種類的Filter介面實現了預設的特性類。如上表，ActionFilterAttribute 類實現了 IActionFilter 和 IResultFilter 兩個介面，這個類是一個抽象類，必須對它提供實現。另外兩個特性類，AuthorizeAttribute 和 HandleErrorAttribute， 已經提供了一些有用的方法，可以直接使用。

Filter 既能應用在單個的ation方法上，也能應用在整個controller上，並可以在acion和controller上應用多個Filter。如下所示：

[Authorize(Roles="trader")]  // 對所有action有效
public class ExampleController : Controller { 
 
    [ShowMessage]  // 對當前ation有效
    [OutputCache(Duration=60)] // 對當前ation有效
    public ActionResult Index() { 
        // ...  
    } 
}

注意，對於自定義的controller的基類，應用於該基類的Filter也將對繼承自該基類的所有子類有效。

Authorization Filter

Authorization Filter是在action方法和其他種類的Filter之前執行的。它的作用是強制實施許可權策略，保證action方法只能被授權的使用者呼叫。Authorization Filter實現的介面如下：

namespace System.Web.Mvc {
    public interface IAuthorizationFilter { 
        void OnAuthorization(AuthorizationContext filterContext); 
    } 
} 

自定義Authorization Filter

你可以自己實現 IAuthorizationFilter 介面來建立自己的安全認證邏輯，但一般沒有這個必要也不推薦這樣做。如果要自定義安全認證策略，更安全的方式是繼承預設的 AuthorizeAttribute 類。

我們下面通過繼承 AuthorizeAttribute 類來演示自定義Authorization Filter。新建一個空MVC應用程式，和往常的示例一樣新增一個 Infrastructure 資料夾，然後新增一個 CustomAuthAttribute.cs 類檔案，程式碼如下：

namespace MvcApplication1.Infrastructure {
    public class CustomAuthAttribute : AuthorizeAttribute {
        private bool localAllowed;
        public CustomAuthAttribute(bool allowedParam) {
            localAllowed = allowedParam;
        }
        protected override bool AuthorizeCore(HttpContextBase httpContext) {
            if (httpContext.Request.IsLocal) {
                return localAllowed;
            }
            else {
                return true;
            }
        }
    }
}

這個簡單的Filter，通過重寫 AuthorizeCore 方法，允許我們阻止本地的請求，在應用該Filter時，可以通過建構函式來指定是否允許本地請求。AuthorizeAttribte 類幫我們內建地實現了很多東西，我們只需把重點放在 AuthorizeCore 方法上，在該方法中實現許可權認證的邏輯。

為了演示這個Filter的作用，我們新建一個名為 Home 的 controller，然後在 Index action方法上應用這個Filter。引數設定為false以保護這個 action 不被本地訪問，如下：

public class HomeController : Controller {

    [CustomAuth(false)]
    public string Index() {
        return "This is the Index action on the Home controller";
    }
}

執行程式，根據系統生成的預設路由值，將請求 /Home/Index，結果如下：

我們通過把 AuthorizeAttribute 類作為基類自定義了一個簡單的Filter，那麼 AuthorizeAttribute 類本身作為Filter有哪些有用的功能呢？

使用內建的Authorization Filter

當我們直接使用 AuthorizeAttribute 類作為Filter時，可以通過兩個屬性來指定我們的許可權策略。這兩個屬性及說明如下：

• Users屬性，string型別，指定允許訪問action方法的使用者名稱，多個使用者名稱用逗號隔開。
• Roles屬性，string型別，用逗號分隔的角色名，訪問action方法的使用者必須屬於這些角色之一。

使用如下：

public class HomeController : Controller {

    [Authorize(Users = "jim, steve, jack", Roles = "admin")]
    public string Index() {
        return "This is the Index action on the Home controller";
    }
}

這裡我們為Index方法應用了Authorize特性，並同時指定了能訪問該方法的使用者和角色。要訪問Index action，必須兩者都滿足條件，即使用者名稱必須是 jim, steve, jack 中的一個，而且必須屬性 admin 角色。

另外，如果不指定任何使用者名稱和角色名（即 [Authorize] ），那麼只要是登入使用者都能訪問該action方法。

你可以通過建立一個Internet模板的應用程式來看一下效果，這裡就不演示了。

對於大部分應用程式，AuthorizeAttribute 特性類提供的許可權策略是足夠用的。如果你有特殊的需求，則可以通過繼承AuthorizeAttribute 類來滿足。

Exception Filter

Exception Filter，在下面三種來源丟擲未處理的異常時執行：

• 另外一種Filter（如Authorization、Action或Result等Filter）。
• Action方法本身。
• Action方法執行完成（即處理ActionResult的時候）。

Exception Filter必須實現 IExceptionFilter 介面，該介面的定義如下：

namespace System.Web.Mvc { 
    public interface IExceptionFilter { 
        void OnException(ExceptionContext filterContext); 
    } 
} 

ExceptionContext 常用屬性說明

在 IExceptionFilter 的介面定義中，唯一的 OnException 方法在未處理的異常引發時執行，其中引數的型別：ExceptionContext，它繼承自 ControllerContext 類，ControllerContext 包含如下常用的屬性：

• Controller，返回當前請求的controller物件。
• HttpContext，提供請求和響應的詳細資訊。
• IsChildAction，如果是子action則返回true（稍後將簡單介紹子action）。
• RequestContext，提供請求上下文資訊。
• RouteData，當前請求的路由例項資訊。

作為繼承 ControllerContext 類的子類，ExceptionContext 類還提供了以下對處理異常的常用屬性：

• ActionDescriptor，提供action方法的詳細資訊。
• Result，是一個 ActionResult 型別，通過把這個屬性值設為非空可以讓某個Filter的執行取消。
• Exception，未處理異常資訊。
• ExceptionHandled，如果另外一個Filter把這個異常標記為已處理則返回true。

一個Exception Filter可以通過把 ExceptionHandled 屬性設定為true來標註該異常已被處理過，這個屬性一般在某個action方法上應用了多個Exception Filter時會用到。ExceptionHandled 屬性設定為true後，就可以通過該屬性的值來判斷其它應用在同一個action方法Exception Filter是否已經處理了這個異常，以免同一個異常在不同的Filter中重複被處理。

示例演示

在 Infrastructure 資料夾下新增一個 RangeExceptionAttribute.cs 類檔案，程式碼如下：

public class RangeExceptionAttribute : FilterAttribute, IExceptionFilter {
    public void OnException(ExceptionContext filterContext) {
        if (!filterContext.ExceptionHandled && filterContext.Exception is ArgumentOutOfRangeException) {
            filterContext.Result = new RedirectResult("~/Content/RangeErrorPage.html");
            filterContext.ExceptionHandled = true;
        }
    }
}

這個Exception Filter通過重定向到Content目錄下的一個靜態html檔案來顯示友好的 ArgumentOutOfRangeException 異常資訊。我們定義的 RangeExceptionAttribute 類繼承了FilterAttribute類，並且實現了IException介面。作為一個MVC Filter，它的類必須實現IMvcFilter介面，你可以直接實現這個介面，但更簡單的方法是繼承 FilterAttribute 基類，該基類實現了一些必要的介面並提供了一些有用的基本特性，比如按照預設的順序來處理Filter。

在Content資料夾下面新增一個名為RangeErrorPage.html的檔案用來顯示友好的錯誤資訊。如下所示：

<!DOCTYPE html> 
<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
    <title>Range Error</title> 
</head> 
<body> 
    <h2>Sorry</h2> 
    <span>One of the arguments was out of the expected range.</span> 
</body> 
</html>

在HomeController中新增一個值越限時丟擲異常的action，如下所示：

    public class HomeController : Controller { 
        [RangeException]
        public string RangeTest(int id) { 
            if (id > 100) { 
                return String.Format("The id value is: {0}", id); 
            } else { 
                throw new ArgumentOutOfRangeException("id", id, ""); 
            } 
        } 
    } 

當對RangeTest應用自定義的的Exception Filter時，執行程式URL請求為 /Home/RangeTest/50，程式丟擲異常後將重定向到RangeErrorPage.html頁面：

由於靜態的html檔案是和後臺脫離的，所以實際專案中更多的是用一個View來呈現友好的錯誤資訊，以便很好的對它進行一些動態的控制。如下面把示例改動一下，RangeExceptionAttribute 類修改如下：

    public class RangeExceptionAttribute : FilterAttribute, IExceptionFilter {
        public void OnException(ExceptionContext filterContext) {
            if (!filterContext.ExceptionHandled && filterContext.Exception is ArgumentOutOfRangeException) {
                int val = (int)(((ArgumentOutOfRangeException)filterContext.Exception).ActualValue);
                filterContext.Result = new ViewResult {
                    ViewName = "RangeError",
                    ViewData = new ViewDataDictionary<int>(val)
                };
                filterContext.ExceptionHandled = true;
            }
        }
    }

我們建立一個ViewResult物件，指定了發生異常時要重定向的View名稱和傳遞的model物件。然後我們在Views/Shared資料夾下新增一個RangeError.cshtml檔案，程式碼如下：

@model int

<!DOCTYPE html> 
<html> 
<head> 
    <meta name="viewport" content="width=device-width" /> 
    <title>Range Error</title> 
</head> 
<body> 
    <h2>Sorry</h2> 
    <span>The value @Model was out of the expected range.</span> 
    <div> 
        @Html.ActionLink("Change value and try again", "Index") 
    </div> 
</body> 
</html> 

執行結果如下：

禁用異常跟蹤

很多時候異常是不可預料的，在每個Action方法或Controller上應用Exception Filter是不現實的。而且如果異常出現在View中也無法應用Filter。如RangeError.cshtml這個View加入下面程式碼：

@model int

@{ 
    var count = 0; 
    var number = Model / count; 
} 

...

執行程式後，將會顯示如下資訊：

顯然程式釋出後不應該顯示這些資訊給使用者看。我們可以通過配置Web.config讓應用程式不管在何時何地引發了異常都可以顯示統一的友好錯誤資訊。在Web.config檔案中的<system.web>節點下新增如下子節點：

  <system.web>
    
    ...
    <customErrors mode="On" defaultRedirect="/Content/RangeErrorPage.html"/>
  </system.web>

這個配置只對遠端訪問有效，本地執行站點依然會顯示跟蹤資訊。

使用內建的 Exceptin Filter

通過上面的演示，我們理解了Exceptin Filter在MVC背後是如何執行的。但我們並不會經常去建立自己的Exceptin Filter，因為微軟在MVC框架中內建的 HandleErrorAttribute(實現了IExceptionFilter介面) 已經足夠我們平時使用。它包含ExceptionType、View和Master三個屬性。當ExceptionType屬性指定型別的異常被引發時，這個Filter將用View屬性指定的View（使用預設的Layout或Mast屬性指定的Layout）來呈現一個頁面。如下面程式碼所示：

... 
[HandleError(ExceptionType = typeof(ArgumentOutOfRangeException), View = "RangeError")] 
public string RangeTest(int id) { 
    if (id > 100) { 
        return String.Format("The id value is: {0}", id); 
    } else { 
        throw new ArgumentOutOfRangeException("id", id, ""); 
    } 
} 
... 

使用內建的HandleErrorAttribute，將異常資訊呈現到View時，這個特性同時會傳遞一個HandleErrorInfo物件作為View的model。HandleErrorInfo類包含ActionName、ControllerName和Exception屬性，如下面的 RangeError.cshtml 使用這個model來呈現資訊：

@model HandleErrorInfo 
@{ 
    ViewBag.Title = "Sorry, there was a problem!"; 
} 
 
<!DOCTYPE html> 
<html> 
<head> 
    <meta name="viewport" content="width=device-width" /> 
    <title>Range Error</title> 
</head> 
<body> 
    <h2>Sorry</h2> 
    <span>The value @(((ArgumentOutOfRangeException)Model.Exception).ActualValue) 
        was out of the expected range.</span>         
    <div> 
        @Html.ActionLink("Change value and try again", "Index") 
    </div> 
    <div style="display: none"> 
        @Model.Exception.StackTrace 
    </div> 
</body> 
</html>

Action Filter

顧名思義，Action Filter是對action方法的執行進行“篩選”的，包括執行前和執行後。它需要實現 IActionFilter 介面，該介面定義如下：

namespace System.Web.Mvc { 
    public interface IActionFilter { 
        void OnActionExecuting(ActionExecutingContext filterContext); 
        void OnActionExecuted(ActionExecutedContext filterContext); 
    } 
}

其中，OnActionExecuting方法在action方法執行之前被呼叫，OnActionExecuted方法在action方法執行之後被呼叫。我們來看一個簡單的例子。
在Infrastructure資料夾下新增一個ProfileActionAttribute類，程式碼如下：

using System.Diagnostics; 
using System.Web.Mvc; 

namespace MvcApplication1.Infrastructure { 
    public class ProfileActionAttribute : FilterAttribute, IActionFilter { 
        private Stopwatch timer; 
        public void OnActionExecuting(ActionExecutingContext filterContext) { 
            timer = Stopwatch.StartNew(); 
        } 
        public void OnActionExecuted(ActionExecutedContext filterContext) { 
            timer.Stop();
            if (filterContext.Exception == null) { 
                filterContext.HttpContext.Response.Write( 
                    string.Format("<div>Action method elapsed time: {0}</div>", timer.Elapsed.TotalSeconds)); 
            } 
        } 
    } 
} 

在HomeController中新增一個Action並應用該Filter，如下：

... 
[ProfileAction] 
public string FilterTest() { 
    return "This is the ActionFilterTest action"; 
} 
...

執行程式，URL定位到/Home/FilterTest，結果如下：

我們看到，ProfileAction的 OnActionExecuted 方法是在 FilterTest 方法返回結果之前執行的。確切的說，OnActionExecuted 方法是在action方法執行結束之後和處理action返回結果之前執行的。

OnActionExecuting方法和OnActionExecuted方法分別接受ActionExecutingContext和ActionExecutedContext物件引數，這兩個引數包含了ActionDescriptor、Canceled、Exception等常用屬性。

Result Filter

Result Filter用來處理action方法返回的結果。用法和Action Filter類似，它需要實現 IResultFilter 介面，定義如下：

namespace System.Web.Mvc { 
    public interface IResultFilter { 
        void OnResultExecuting(ResultExecutingContext filterContext); 
        void OnResultExecuted(ResultExecutedContext filterContext); 
    } 
} 

IResultFilter 介面和之前的 IActionFilter 介面類似，要注意的是Result Filter是在Action Filter之後執行的。兩者用法是一樣的，不再多講，直接給出示例程式碼。

在Infrastructure資料夾下再新增一個 ProfileResultAttribute.cs 類檔案，程式碼如下：

public class ProfileResultAttribute : FilterAttribute, IResultFilter { 
    private Stopwatch timer; 
    public void OnResultExecuting(ResultExecutingContext filterContext) { 
        timer = Stopwatch.StartNew(); 
    } 
    public void OnResultExecuted(ResultExecutedContext filterContext) { 
        timer.Stop(); 
        filterContext.HttpContext.Response.Write( 
            string.Format("<div>Result elapsed time: {0}</div>",  timer.Elapsed.TotalSeconds)); 
    } 
}

應用該Filter：

... 
[ProfileAction] 
[ProfileResult] 
public string FilterTest() { 
    return "This is the ActionFilterTest action"; 
} 
...

內建的 Action 和 Result Filter

MVC框架內建了一個 ActionFilterAttribute 類用來建立action 和 result 篩選器，即可以控制action方法的執行也可以控制處理action方法返回結果。它是一個抽象類，定義如下：

public abstract class ActionFilterAttribute : FilterAttribute, IActionFilter, IResultFilter{ 
        public virtual void OnActionExecuting(ActionExecutingContext filterContext) { 
        } 
        public virtual void OnActionExecuted(ActionExecutedContext filterContext) { 
        } 
        public virtual void OnResultExecuting(ResultExecutingContext filterContext) { 
        } 
        public virtual void OnResultExecuted(ResultExecutedContext filterContext) { 
        } 
    } 
}

使用這個抽象類方便之處是你只需要實現需要加以處理的方法。其他和使用 IActionFilter 和 IResultFilter 介面沒什麼不同。下面是簡單做個示例。

在Infrastructure資料夾下新增一個 ProfileAllAttribute.cs 類檔案，程式碼如下：

public class ProfileAllAttribute : ActionFilterAttribute { 
    private Stopwatch timer; 
    public override void OnActionExecuting(ActionExecutingContext filterContext) { 
        timer = Stopwatch.StartNew(); 
    } 
    public override void OnResultExecuted(ResultExecutedContext filterContext) { 
        timer.Stop(); 
        filterContext.HttpContext.Response.Write(
        string.Format("<div>Total elapsed time: {0}</div>",  timer.Elapsed.TotalSeconds)); 
    } 
}

在HomeController中的FilterTest方法上應用該Filter：

... 
[ProfileAction] 
[ProfileResult] 
[ProfileAll] 
public string FilterTest() { 
    return "This is the FilterTest action"; 
} 
...

執行程式，URL定位到/Home/FilterTest，可以看到一個Action從執行之前到結果處理完畢總共花的時間：

我們也可以Controller中直接重寫 ActionFilterAttribute 抽象類中定義的四個方法，效果和使用Filter是一樣的，例如：

public class HomeController : Controller { 
    private Stopwatch timer; 
    ...
    public string FilterTest() { 
        return "This is the FilterTest action"; 
    } 
    protected override void OnActionExecuting(ActionExecutingContext filterContext) { 
        timer = Stopwatch.StartNew(); 
    } 
    protected override void OnResultExecuted(ResultExecutedContext filterContext) { 
        timer.Stop(); 
        filterContext.HttpContext.Response.Write( 
            string.Format("<div>Total elapsed time: {0}</div>", 
            timer.Elapsed.TotalSeconds)); 
    } 
} 

註冊為全域性 Filter

全域性Filter對整個應用程式的所有controller下的所有action方法有效。在App_Start/FilterConfig.cs檔案中的RegisterGlobalFilters方法，可以把一個Filter類註冊為全域性，如：

using System.Web; 
using System.Web.Mvc; 
using MvcApplication1.Infrastructure; 
 
namespace MvcApplication1 { 
    public class FilterConfig { 
        public static void RegisterGlobalFilters(GlobalFilterCollection filters) { 
            filters.Add(new HandleErrorAttribute()); 
            filters.Add(new ProfileAllAttribute()); 
        } 
    } 
}

我們增加了filters.Add(new ProfileAllAttribute())這行程式碼，其中的filters引數是一個GlobalFilterCollection型別的集合。為了驗證 ProfileAllAttribute 應用到了所有action，我們另外新建一個controller並新增一個簡單的action，如下：

public class CustomerController : Controller { 
        public string Index() { 
            return "This is the Customer controller"; 
        } 
}

執行程式，將URL定位到 /Customer ，結果如下：

其它常用 Filter

MVC框架內建了很多Filter，常見的有RequireHttps、OutputCache、AsyncTimeout等等。下面例舉幾個常用的。

• RequireHttps，強制使用HTTPS協議訪問。它將瀏覽器的請求重定向到相同的controller和action，並加上 https:// 字首。
• OutputCache，將action方法的輸出內容進行快取。
• AsyncTimeout/NoAsyncTimeout，用於非同步Controller的超時設定。（非同步Controller的內容請訪問 xxxxxxxxxxxxxxxxxxxxxxxxxxx）
• ChildActionOnlyAttribute，使用action方法僅能被Html.Action和Html.RenderAction方法訪問。

這裡我們選擇 OutputCache 這個Filter來做個示例。新建一個 SelectiveCache controller，程式碼如下：

public class SelectiveCacheController : Controller {
    public ActionResult Index() { 
        Response.Write("Action method is running: " + DateTime.Now); 
        return View(); 
    } 

    [OutputCache(Duration = 30)] 
    public ActionResult ChildAction() { 
        Response.Write("Child action method is running: " + DateTime.Now); 
        return View(); 
    } 
}

這裡的 ChildAction 應用了 OutputCache filter，這個action將在view內被呼叫，它的父action是Index。

現在我們分別建立兩個View，一個是ChildAction.cshtml，程式碼如下：

@{ 
    Layout = null; 
} 
 
<h4>This is the child action view</h4>

另一個是它的Index.cshtml，程式碼如下：

@{ 
    ViewBag.Title = "Index"; 
} 
 
<h2>This is the main action view</h2> 
 
@Html.Action("ChildAction")

執行程式，將URL定位到  /SelectiveCache ，過幾秒重新整理一下，可看到如下結果：

 

 

---

參考：《Pro ASP.NET MVC 4 4th Edition》