ASP.NET Core 中的篩選條件

作者：Kirk Larkin \(英文\)、Rick Anderson \(英文\)、Tom Dykstra \(英文\) 及 Steve Smith \(英文\)

ASP.NET Core 中的篩選條件可讓程式碼在要求處理管線中的特定階段之前或之後執行。

內建篩選條件會處理工作，例如：

• 授權，避免存取使用者未獲授權的資源。
• 回應快取，縮短要求管線，傳回快取的回應。

可以建立自訂篩選條件來處理跨領域關注。 跨領域關注的範例包括錯誤處理、快取、設定、授權及記錄。 篩選能避免重複的程式碼。 例如，錯誤處理例外狀況篩選條件中可以合併錯誤處理。

本文件適用於 Razor Pages、API 控制器，以及具有檢視的控制器。 篩選無法直接與 Razor 元件搭配使用。 篩選條件只能在以下情況下間接影響元件：

• 元件內嵌在頁面或檢視中。
• 頁面或控制器和檢視會使用篩選。

篩選條件如何運作

篩選條件會在「ASP.NET Core 動作引動過程管線」中執行，其有時也被稱為「篩選條件管線」。 在 ASP.NET Core 之後執行的篩選條件管線會選取要執行的動作：

篩選類型

每個篩選類型會在篩選條件管線中的不同階段執行：

• 授權篩選條件：

  • 先執行。
  • 判斷使用者是否獲得此要求的授權。
  • 如果要求未獲得授權，則縮短管線的線路。

• 資源篩選條件：

  • 會在授權之後執行。
  • OnResourceExecuting 會在其餘的篩選條件管線之前執行程式碼。 例如，OnResourceExecuting 會在模型繫結之前執行程式碼。
  • OnResourceExecuted 會在其餘的管線皆已完成之後執行程式碼。

• 動作篩選條件：

  • 在呼叫動作方法之前和之後立即執行。
  • 可以變更傳遞至動作的引數。
  • 可以變更從動作傳回的結果。
  • Razor Pages 不支援。

• 端點篩選：

  • 在呼叫動作方法之前和之後立即執行。
  • 可以變更傳遞至動作的引數。
  • 可以變更從動作傳回的結果。
  • Razor Pages 不支援。
  • 可以在動作和以路由處理常式為基礎的端點上叫用。

• 例外狀況篩選條件會將通用原則套用到在寫入回應主體之前發生的未處理例外狀況。

• 結果篩選條件：

  • 在執行動作結果之前和之後立即執行。
  • 只有當動作方法成功執行時，才會執行。
  • 適用於必須包圍檢視或格式器執行的邏輯。

下圖顯示篩選條件類型如何在篩選條件管線中互動：

Razor Pages 也支援在 Razor Page 處理常式之前和之後執行的 Razor Page 篩選。

實作

篩選條件同時支援透過不同介面定義的同步和非同步實作。

同步篩選可以在其管線階段之前和之後執行。 例如，系統會在呼叫動作方法之前呼叫 OnActionExecuting。 系統會在傳回動作方法之後呼叫 OnActionExecuted：

public class SampleActionFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    {
        // Do something before the action executes.
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        // Do something after the action executes.
    }
}

非同步篩選會定義 On-Stage-ExecutionAsync 方法。 例如 OnActionExecutionAsync：

public class SampleAsyncActionFilter : IAsyncActionFilter
{
    public async Task OnActionExecutionAsync(
        ActionExecutingContext context, ActionExecutionDelegate next)
    {
        // Do something before the action executes.
        await next();
        // Do something after the action executes.
    }
}

在上述程式碼中，SampleAsyncActionFilter 具有會執行動作方法的 ActionExecutionDelegate (next)。

多個篩選條件階段

可以在單一類別中實作多個篩選條件階段的介面。 例如，ActionFilterAttribute 類別會實作：

• 同步：IActionFilter 和 IResultFilter
• 非同步：IAsyncActionFilter 和 IAsyncResultFilter
• IOrderedFilter

請實作同步或非同步版本的篩選條件介面，而不要同時實作這兩者。 執行階段會先檢查以查看篩選條件是否會實作非同步介面，如果是，便會呼叫該介面。 如果沒有，它會呼叫同步介面的方法。 如果同時在單一類別中實作非同步和同步介面，系統只會呼叫非同步方法。 使用抽象類別 (例如 ActionFilterAttribute) 時，請僅覆寫每個篩選條件類型的同步方法或非同步方法。

內建篩選條件屬性

ASP.NET Core 包含內建的屬性型篩選條件，可對其進行子類別化和自訂。 例如，下列結果篩選條件會將標頭新增至回應：

public class ResponseHeaderAttribute : ActionFilterAttribute
{
    private readonly string _name;
    private readonly string _value;

    public ResponseHeaderAttribute(string name, string value) =>
        (_name, _value) = (name, value);

    public override void OnResultExecuting(ResultExecutingContext context)
    {
        context.HttpContext.Response.Headers.Add(_name, _value);

        base.OnResultExecuting(context);
    }
}

屬性可讓篩選條件接受引數，如上述範例所示。 將 ResponseHeaderAttribute 新增至控制器或動作方法，並指定 HTTP 標頭的名稱和值：

[ResponseHeader("Filter-Header", "Filter Value")]
public class ResponseHeaderController : ControllerBase
{
    public IActionResult Index() =>
        Content("Examine the response headers using the F12 developer tools.");

    // ...

使用瀏覽器開發人員工具之類的工具來檢查標頭。 回應標頭底下會顯示 filter-header: Filter Value。

下列程式碼會同時將 ResponseHeaderAttribute 套用到控制器和動作：

[ResponseHeader("Filter-Header", "Filter Value")]
public class ResponseHeaderController : ControllerBase
{
    public IActionResult Index() =>
        Content("Examine the response headers using the F12 developer tools.");

    // ...

    [ResponseHeader("Another-Filter-Header", "Another Filter Value")]
    public IActionResult Multiple() =>
        Content("Examine the response headers using the F12 developer tools.");
}

Multiple 動作的回應會包括下列標頭：

• filter-header: Filter Value
• another-filter-header: Another Filter Value

有幾個篩選條件介面有對應的屬性，可用來作為自訂實作的基底類別。

篩選條件屬性：

• ActionFilterAttribute
• ExceptionFilterAttribute
• ResultFilterAttribute
• FormatFilterAttribute
• ServiceFilterAttribute
• TypeFilterAttribute

篩選條件無法套用至 Razor Page 處理常式方法。 可以套用至 Razor Page 模型或全域套用。

篩選條件範圍和執行的順序

篩選條件能以三個「範圍」之一新增至管線：

• 針對控制器或 Razor Page 使用屬性。
• 針對控制器動作使用屬性。 篩選屬性無法套用至 Razor Pages 處理常式方法。
• 可全域套用至所有控制器、動作和 Razor Page，如下列程式碼所示：

  var builder = WebApplication.CreateBuilder(args);
  
  // Add services to the container.
  builder.Services.AddControllersWithViews(options =>
  {
      options.Filters.Add<GlobalSampleActionFilter>();
  });
  

預設執行順序

當管線的特定階段有多個篩選條件時，範圍會決定篩選條件的預設執行順序。 全域篩選條件會圍繞類別篩選條件，後者又圍繞方法篩選條件。

因為篩選條件巢狀結構的原因，篩選條件的「之後」程式碼的執行順序會與「之前」程式碼相反。 篩選條件序列：

• 全域篩選條件的「之前」程式碼。
  • 控制器篩選條件的「之前」程式碼。
    • 動作方法篩選條件的「之前」程式碼。
    • 動作方法篩選條件的「之後」程式碼。
  • 控制器篩選條件的「之後」程式碼。
• 全域篩選條件的「之後」程式碼。

下列範例說明針對同步動作篩選執行篩選方法的順序：

序列	篩選條件範圍	篩選條件方法
1	全域	OnActionExecuting
2	控制器	OnActionExecuting
3	動作	OnActionExecuting
4	動作	OnActionExecuted
5	控制器	OnActionExecuted
6	全域	OnActionExecuted

控制器層級篩選

繼承自 Controller 的每個控制器都包含 OnActionExecuting、OnActionExecutionAsync 和 OnActionExecuted 方法。 這些方法會包裝針對指定動作執行的篩選條件：

• OnActionExecuting 會在任何動作的篩選之前執行。
• OnActionExecuted 會在動作的所有篩選之後執行。
• OnActionExecutionAsync 會在任何動作的篩選之前執行。 呼叫 next 之後的程式碼會在動作的篩選之後執行。

下列 ControllerFiltersController 類別：

• 將 SampleActionFilterAttribute ([SampleActionFilter]) 套用至控制器。
• 覆寫 OnActionExecuting 和 OnActionExecuted。

[SampleActionFilter]
public class ControllerFiltersController : Controller
{
    public override void OnActionExecuting(ActionExecutingContext context)
    {
        Console.WriteLine(
            $"- {nameof(ControllerFiltersController)}.{nameof(OnActionExecuting)}");

        base.OnActionExecuting(context);
    }

    public override void OnActionExecuted(ActionExecutedContext context)
    {
        Console.WriteLine(
            $"- {nameof(ControllerFiltersController)}.{nameof(OnActionExecuted)}");

        base.OnActionExecuted(context);
    }

    public IActionResult Index()
    {
        Console.WriteLine(
            $"- {nameof(ControllerFiltersController)}.{nameof(Index)}");

        return Content("Check the Console.");
    }
}

瀏覽至 https://localhost:<port>/ControllerFilters 執行下列程式碼：

• ControllerFiltersController.OnActionExecuting
  • GlobalSampleActionFilter.OnActionExecuting
    • SampleActionFilterAttribute.OnActionExecuting
      • ControllerFiltersController.Index
    • SampleActionFilterAttribute.OnActionExecuted
  • GlobalSampleActionFilter.OnActionExecuted
• ControllerFiltersController.OnActionExecuted

控制器層級篩選會將 Order 屬性設定為 int.MinValue。 控制器層級篩選無法設定為在套用至方法的篩選之後執行。 下一節會說明順序。

針對 Razor Pages，請參閱覆寫篩選方法來實作 Razor Page 篩選。

覆寫預設順序

可以藉由實作 IOrderedFilter 來覆寫預設執行序列。 IOrderedFilter 會公開 Order 屬性，其優先順序會高於範圍以決定執行順序。 具有較低 Order 值的篩選條件：

• 在具有較高 Order 值的篩選條件之前執行「之前」程式碼。
• 在具有較高 Order 值的篩選條件之後執行「之後」程式碼。

在控制器層級篩選範例中，GlobalSampleActionFilter具有全域範圍，因此會在具有控制器範圍的 SampleActionFilterAttribute 之前執行。 若要先執行 SampleActionFilterAttribute，請將其順序設定為 int.MinValue：

[SampleActionFilter(Order = int.MinValue)]
public class ControllerFiltersController : Controller
{
    // ...
}

若要先執行全域篩選 GlobalSampleActionFilter，請將其 Order 設定為 int.MinValue：

builder.Services.AddControllersWithViews(options =>
{
    options.Filters.Add<GlobalSampleActionFilter>(int.MinValue);
});

取消和縮短

可以設定提供給篩選條件方法之 ResourceExecutingContext 參數上的 Result 屬性，以縮短篩選條件管線。 例如，下列資源篩選條件可防止管線的其餘部分執行：

public class ShortCircuitingResourceFilterAttribute : Attribute, IResourceFilter
{
    public void OnResourceExecuting(ResourceExecutingContext context)
    {
        context.Result = new ContentResult
        {
            Content = nameof(ShortCircuitingResourceFilterAttribute)
        };
    }

    public void OnResourceExecuted(ResourceExecutedContext context) { }
}

在下列程式碼中，[ShortCircuitingResourceFilter] 和 [ResponseHeader] 篩選條件都以 Index 動作方法為目標。 ShortCircuitingResourceFilterAttribute 篩選條件：

• 最先執行，因為它是資源篩選條件，且 ResponseHeaderAttribute 是動作篩選條件。
• 縮短管線的其餘部分。

因此，Index 動作的 ResponseHeaderAttribute 篩選條件永遠不會執行。 如果這兩個篩選條件都套用在動作方法層級，此行為也會相同，假設 ShortCircuitingResourceFilterAttribute 先執行的話。 ShortCircuitingResourceFilterAttribute 會因為其篩選類型而先執行：

[ResponseHeader("Filter-Header", "Filter Value")]
public class ShortCircuitingController : Controller
{
    [ShortCircuitingResourceFilter]
    public IActionResult Index() =>
        Content($"- {nameof(ShortCircuitingController)}.{nameof(Index)}");
}

相依性插入

可以依類型或執行個體新增篩選條件。 如果新增執行個體，該執行個體將用於每個要求。 如果新增類型，其將會由類型啟動。 由類型啟動的篩選條件表示：

• 系統會針對每個要求建立執行個體。
• 任何建構函式相依性都會由相依性插入 (DI) 所填入。

實作為屬性並直接新增至控制器類別或動作方法的篩選條件，不能由相依性插入 (DI) 提供建構函式相依性。 建構函式相依性無法由 DI 提供，因為屬性必須在其套用位置提供其建構函式參數。

下列篩選條件支援由 DI 所提供的建構函式相依性：

• ServiceFilterAttribute
• TypeFilterAttribute
• 在屬性上實作 IFilterFactory。

上述篩選條件可以被套用至控制器或動作。

DI 會提供記錄器。 不過，請避免僅針對記錄目的建立並使用篩選條件。 內建架構記錄通常便可以提供記錄所需的項目。 新增至篩選條件的記錄：

• 應該專注在篩選條件特定的商務領域考量或行為。
• 不應該記錄動作或其他架構事件。 內建篩選條件已記錄動作和架構事件。

ServiceFilterAttribute

服務篩選條件實作類型會註冊在 Program.cs 中。 ServiceFilterAttribute 會從 DI 擷取篩選條件的執行個體。

下列程式碼會顯示使用 DI 的 LoggingResponseHeaderFilterService 類別：

public class LoggingResponseHeaderFilterService : IResultFilter
{
    private readonly ILogger _logger;

    public LoggingResponseHeaderFilterService(
            ILogger<LoggingResponseHeaderFilterService> logger) =>
        _logger = logger;

    public void OnResultExecuting(ResultExecutingContext context)
    {
        _logger.LogInformation(
            $"- {nameof(LoggingResponseHeaderFilterService)}.{nameof(OnResultExecuting)}");

        context.HttpContext.Response.Headers.Add(
            nameof(OnResultExecuting), nameof(LoggingResponseHeaderFilterService));
    }

    public void OnResultExecuted(ResultExecutedContext context)
    {
        _logger.LogInformation(
            $"- {nameof(LoggingResponseHeaderFilterService)}.{nameof(OnResultExecuted)}");
    }
}

在下列程式碼中，會將 LoggingResponseHeaderFilterService 新增至 DI 容器：

builder.Services.AddScoped<LoggingResponseHeaderFilterService>();

在下列程式碼中，ServiceFilter 屬性會從 DI 擷取 LoggingResponseHeaderFilterService 篩選條件的執行個體：

[ServiceFilter<LoggingResponseHeaderFilterService>]
public IActionResult WithServiceFilter() =>
    Content($"- {nameof(FilterDependenciesController)}.{nameof(WithServiceFilter)}");

使用 ServiceFilterAttribute 時，設定 ServiceFilterAttribute.IsReusable：

• 能提供篩選條件執行個體「可能」可以在其建立的要求範圍之外重複使用的提示。 ASP.NET Core 執行階段並不保證：
  • 將會建立篩選條件的單一執行個體。
  • 將不會於稍後的時間從 DI 容器重新要求篩選條件。
• 不應該搭配仰賴具有非單一資料庫存留期之服務的篩選條件使用。

ServiceFilterAttribute 會實作 IFilterFactory。 IFilterFactory 會公開 CreateInstance 方法來建立 IFilterMetadata 執行個體。 CreateInstance 會從 DI 載入指定的類型。

TypeFilterAttribute

TypeFilterAttribute 類似於 ServiceFilterAttribute，但其類型不會直接從 DI 容器解析。 它會使用 Microsoft.Extensions.DependencyInjection.ObjectFactory 來具現化類型。

由於 TypeFilterAttribute 類型不會直接從 DI 容器解析：

• 使用 TypeFilterAttribute 參考的類型不需要向 DI 容器註冊。 不過它們的相依性會由 DI 容器滿足。
• TypeFilterAttribute 可以選擇性地接受類型的建構函式引數。

使用 TypeFilterAttribute 時，設定 TypeFilterAttribute.IsReusable：

• 能提供篩選條件執行個體「可能」可以在其建立的要求範圍之外重複使用的提示。 ASP.NET Core 執行階段不保證將建立篩選條件的單一執行個體。

• 不應該搭配仰賴具有非單一資料庫存留期之服務的篩選條件使用。

下列範例示範如何使用 TypeFilterAttribute 將引數傳遞至類型：

[TypeFilter(typeof(LoggingResponseHeaderFilter),
    Arguments = new object[] { "Filter-Header", "Filter Value" })]
public IActionResult WithTypeFilter() =>
    Content($"- {nameof(FilterDependenciesController)}.{nameof(WithTypeFilter)}");

授權篩選條件

授權篩選條件：

• 是篩選條件管線內最先執行的篩選條件。
• 控制動作方法的存取。
• 有之前的方法，但沒有之後的方法。

自訂授權篩選條件需要自訂的授權架構。 最好是設定授權原則或撰寫自訂授權原則，而不要撰寫自訂篩選條件。 內建的授權篩選條件：

• 呼叫授權系統。
• 不會授權要求。

不會在授權篩選條件內擲回例外狀況：

• 該例外狀況將不會被處理。
• 例外狀況篩選條件將不會處理例外狀況。

請考慮在例外狀況於授權篩選條件中發生時發出挑戰。

深入了解授權。

資源篩選條件

資源篩選條件：

• 實作 IResourceFilter 或 IAsyncResourceFilter 介面。
• 執行會包裝大部分的篩選條件管線。
• 只有授權篩選條件會在資源篩選條件之前執行。

資源篩選條件很適合用來縮短大部分的管線。 比方說，快取篩選條件可以避免快取命中上的其餘管線。

資源篩選條件範例：

• 先前所示的縮短資源篩選條件。

• DisableFormValueModelBindingAttribute \(英文\)：

  • 防止模型繫結存取表單資料。
  • 用於大型檔案上傳，以避免將表單資料讀入記憶體。

動作篩選條件

動作篩選條件不會套用到 Razor Pages。 Razor Pages 支援 IPageFilter 與 IAsyncPageFilter。 如需詳細資訊，請參閱 Razor Pages 的篩選方法。

動作篩選條件：

• 實作 IActionFilter 或 IAsyncActionFilter 介面。
• 它們執行會包圍動作方法的執行。

下列程式碼會顯示範例動作篩選條件：

public class SampleActionFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    {
        // Do something before the action executes.
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        // Do something after the action executes.
    }
}

ActionExecutingContext 提供下列屬性：

• ActionArguments - 允許讀取動作方法的輸入。
• Controller - 提供對控制器執行個體的管理。
• Result - 設定 Result 會縮短動作方法和後續動作篩選條件的執行。

在動作方法中擲回例外狀況：

• 防止執行後續篩選條件。
• 和設定 Result 不同，會被視為失敗而非成功結果。

ActionExecutedContext 提供 Controller 與 Result，加上下列屬性：

• Canceled - 如果動作執行被另一個篩選條件縮短，則為 true。
• Exception - 如果動作或先前所執行的動作篩選條件擲回例外狀況，則為非 Null。 將此屬性設定為 Null：
  • 實際上會「處理」例外狀況。
  • 會執行 Result，有如它是從動作方法傳回一般。

對於 IAsyncActionFilter，呼叫 ActionExecutionDelegate 會：

• 執行任何後續的動作篩選條件和動作方法。
• 傳回 ActionExecutedContext。

若要縮短，請指派 Microsoft.AspNetCore.Mvc.Filters.ActionExecutingContext.Result 給某個結果執行個體，並且不要呼叫 next (ActionExecutionDelegate)。

架構提供抽象 ActionFilterAttribute，其可被子類別化。

OnActionExecuting 動作篩選條件可以用來：

• 驗證模型狀態。
• 如果狀態無效，則傳回錯誤。

public class ValidateModelAttribute : ActionFilterAttribute
{
    public override void OnActionExecuting(ActionExecutingContext context)
    {
        if (!context.ModelState.IsValid)
        {
            context.Result = new BadRequestObjectResult(context.ModelState);
        }
    }
}

注意

以 [ApiController] 屬性標注的控制器會自動驗證模型狀態，並傳回 400 回應。 如需詳細資訊，請參閱自動 HTTP 400 回應。

OnActionExecuted 方法會在動作方法之後執行：

• 並可以透過 Result 屬性查看及操作動作的結果。
• Canceled 會在動作執行被另一個篩選條件縮短時被設為 true。
• Exception 會在動作或後續的動作篩選條件擲回例外狀況時被設為非 Null 值。 將 Exception 設定為 null：
  • 實際上會「處理」例外狀況。
  • 執行 ActionExecutedContext.Result，彷彿它已正常地從動作方法傳回。

例外狀況篩選條件

例外狀況篩選條件：

• 實作 IExceptionFilter 或 IAsyncExceptionFilter。
• 可以用來實作常見的錯誤處理原則。

下列範例例外狀況篩選會顯示在開發應用程式時發生的例外狀況詳細資料：

public class SampleExceptionFilter : IExceptionFilter
{
    private readonly IHostEnvironment _hostEnvironment;

    public SampleExceptionFilter(IHostEnvironment hostEnvironment) =>
        _hostEnvironment = hostEnvironment;

    public void OnException(ExceptionContext context)
    {
        if (!_hostEnvironment.IsDevelopment())
        {
            // Don't display exception details unless running in Development.
            return;
        }

        context.Result = new ContentResult
        {
            Content = context.Exception.ToString()
        };
    }
}

下列程式碼會測試例外狀況篩選：

[TypeFilter<SampleExceptionFilter>]
public class ExceptionController : Controller
{
    public IActionResult Index() =>
        Content($"- {nameof(ExceptionController)}.{nameof(Index)}");
}

例外狀況篩選條件：

• 沒有之前和之後的事件。
• 實作 OnException 或 OnExceptionAsync。
• 處理在 Razor Page 或控制器建立、模型繫結、動作篩選條件或動作方法中發生的未處理例外狀況。
• 不會攔截在資源篩選條件、結果篩選條件或 MVC 結果執行中發生的例外狀況。

若要處理例外狀況，請將 ExceptionHandled 屬性設定為 true 或指派 Result 屬性。 這樣會阻止傳播例外狀況。 例外狀況篩選條件無法將例外狀況變成「成功」。 只有動作篩選條件可以這麼做。

例外狀況篩選條件：

• 適合用於設陷在動作內發生的例外狀況。
• 不像錯誤處理中介軟體那麼有彈性。

偏好使用中介軟體進行例外狀況處理。 只有在錯誤處理會根據所呼叫的動作方法而「不同」時才使用例外狀況篩選條件。 比方說，應用程式可能會有適用於 API 端點及檢視/HTML 的動作方法。 API 端點可能將錯誤資訊傳回為 JSON，而以檢視為基礎的動作則可能將錯誤頁面傳回為 HTML。

結果篩選條件

結果篩選條件：

• 實作介面：
  • IResultFilter 或 IAsyncResultFilter
  • IAlwaysRunResultFilter 或 IAsyncAlwaysRunResultFilter
• 它們執行會包圍動作結果的執行。

IResultFilter 和 IAsyncResultFilter

下列程式碼會顯示範例結果篩選條件：

public class SampleResultFilter : IResultFilter
{
    public void OnResultExecuting(ResultExecutingContext context)
    {
        // Do something before the result executes.
    }

    public void OnResultExecuted(ResultExecutedContext context)
    {
        // Do something after the result executes.
    }
}

執行的結果類型會取決於動作。 傳回檢視的動作會在執行中的 ViewResult 裡包含處理中的所有 Razor。 API 方法可能在結果執行當中執行某種序列化。 深入了解動作結果。

只有在動作或動作篩選產生動作結果時，才會執行結果篩選。 在下列情況下不會執行結果篩選：

• 授權篩選或資源篩選縮短管線。
• 例外狀況篩選條件會產生動作結果來處理例外狀況。

藉由將 Microsoft.AspNetCore.Mvc.Filters.ResultExecutingContext.Cancel 設為 true，Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuting 方法可以縮短動作結果和後續結果篩選條件的執行。 在縮短時寫入至回應物件，以避免產生空的回應。 擲回 IResultFilter.OnResultExecuting 中的例外狀況：

• 導致無法執行動作結果和後續。
• 視為失敗，而不是成功的結果。

當 Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuted 方法執行時，回應可能已傳送至用戶端。 如果回應已傳送至用戶端，則無法變更。

如果動作結果執行被另一個篩選條件縮短，則 ResultExecutedContext.Canceled 會被設為 true。

如果動作結果或後續的結果篩選條件擲回例外狀況，則 ResultExecutedContext.Exception 會被設為非 Null 值。 將 Exception 設為 null 可有效處理例外狀況，並且使管線中稍後不會擲回例外狀況。 並沒有可以在處理結果篩選條件中的例外狀況時，將資料寫入回應的可靠方式。 當動作結果擲回例外狀況時，如果標頭已清除至用戶端，則沒有任何可靠的機制能傳送失敗碼。

針對 IAsyncResultFilter 而言，對 ResultExecutionDelegate 上的 await next 的呼叫會執行任何後續的結果篩選條件和動作結果。 若要縮短，請將 ResultExecutingContext.Cancel 設為 true，且不要呼叫 ResultExecutionDelegate：

public class SampleAsyncResultFilter : IAsyncResultFilter
{
    public async Task OnResultExecutionAsync(
        ResultExecutingContext context, ResultExecutionDelegate next)
    {
        if (context.Result is not EmptyResult)
        {
            await next();
        }
        else
        {
            context.Cancel = true;
        }
    }
}

架構提供抽象 ResultFilterAttribute，其可被子類別化。 先前所示的 ResponseHeaderAttribute 類別是結果篩選條件屬性的範例。

IAlwaysRunResultFilter 和 IAsyncAlwaysRunResultFilter

IAlwaysRunResultFilter 和 IAsyncAlwaysRunResultFilter 介面會宣告針對所有動作結果執行的 IResultFilter 實作。 這包括下列動作所產生的動作結果：

• 縮短的授權篩選和資源篩選。
• 例外狀況篩選。

例如，下列篩選一律會執行，並會在內容交涉失敗時，為動作結果 (ObjectResult) 設定「422 無法處理的實體」狀態碼：

public class UnprocessableResultFilter : IAlwaysRunResultFilter
{
    public void OnResultExecuting(ResultExecutingContext context)
    {
        if (context.Result is StatusCodeResult statusCodeResult
            && statusCodeResult.StatusCode == StatusCodes.Status415UnsupportedMediaType)
        {
            context.Result = new ObjectResult("Unprocessable")
            {
                StatusCode = StatusCodes.Status422UnprocessableEntity
            };
        }
    }

    public void OnResultExecuted(ResultExecutedContext context) { }
}

IFilterFactory

IFilterFactory 會實作 IFilterMetadata。 因此，IFilterFactory 執行個體可用來在篩選條件管線中任何位置作為 IFilterMetadata 執行個體。 當執行階段準備要叫用篩選條件時，它會嘗試將它轉換成 IFilterFactory。 如果該轉換成功，系統會呼叫 CreateInstance 方法來建立被叫用的 IFilterMetadata 執行個體。 因為在應用程式啟動時不需要明確設定精確的篩選條件管線，所以這提供了具有彈性的設計。

IFilterFactory.IsReusable：

• 這是處理站的提示，表示處理站所建立的篩選實例可以在其建立的要求範圍之外重複使用。
• 不應該搭配仰賴具有非單一資料庫存留期之服務的篩選條件使用。

ASP.NET Core 執行階段並不保證：

• 將會建立篩選條件的單一執行個體。
• 將不會於稍後的時間從 DI 容器重新要求篩選條件。

警告

只有在篩選來源明確、篩選是無狀態，而且篩選可安全地用於多個 HTTP 要求時，才能將 IFilterFactory.IsReusable 設定為傳回 true。 例如，如果 IFilterFactory.IsReusable 傳回 true，則不要從註冊為限定範圍或暫時性的 DI 傳回篩選。

可以使用自訂屬性實作作為另一種建立篩選條件的方法，來實作 IFilterFactory：

public class ResponseHeaderFilterFactory : Attribute, IFilterFactory
{
    public bool IsReusable => false;

    public IFilterMetadata CreateInstance(IServiceProvider serviceProvider) =>
        new InternalResponseHeaderFilter();

    private class InternalResponseHeaderFilter : IActionFilter
    {
        public void OnActionExecuting(ActionExecutingContext context) =>
            context.HttpContext.Response.Headers.Add(
                nameof(OnActionExecuting), nameof(InternalResponseHeaderFilter));

        public void OnActionExecuted(ActionExecutedContext context) { }
    }

篩選條件會在下列程式碼中套用：

[ResponseHeaderFilterFactory]
public IActionResult Index() =>
    Content($"- {nameof(FilterFactoryController)}.{nameof(Index)}");

在屬性上實作的 IFilterFactory

實作 IFilterFactory 的篩選條件很適合用於下列類型的篩選條件：

• 不需要傳遞參數。
• 有需要由 DI 滿足的建構函式相依性。

TypeFilterAttribute 會實作 IFilterFactory。 IFilterFactory 會公開 CreateInstance 方法來建立 IFilterMetadata 執行個體。 CreateInstance 會從服務容器 (DI) 載入指定的類型。

public class SampleActionTypeFilterAttribute : TypeFilterAttribute
{
    public SampleActionTypeFilterAttribute()
         : base(typeof(InternalSampleActionFilter)) { }

    private class InternalSampleActionFilter : IActionFilter
    {
        private readonly ILogger<InternalSampleActionFilter> _logger;

        public InternalSampleActionFilter(ILogger<InternalSampleActionFilter> logger) =>
            _logger = logger;

        public void OnActionExecuting(ActionExecutingContext context)
        {
            _logger.LogInformation(
                $"- {nameof(InternalSampleActionFilter)}.{nameof(OnActionExecuting)}");
        }

        public void OnActionExecuted(ActionExecutedContext context)
        {
            _logger.LogInformation(
                $"- {nameof(InternalSampleActionFilter)}.{nameof(OnActionExecuted)}");
        }
    }
}

下列程式碼會顯示套用篩選條件的三種方式：

[SampleActionTypeFilter]
public IActionResult WithDirectAttribute() =>
    Content($"- {nameof(FilterFactoryController)}.{nameof(WithDirectAttribute)}");

[TypeFilter<SampleActionTypeFilterAttribute>]
public IActionResult WithTypeFilterAttribute() =>
    Content($"- {nameof(FilterFactoryController)}.{nameof(WithTypeFilterAttribute)}");

[ServiceFilter<SampleActionTypeFilterAttribute>]
public IActionResult WithServiceFilterAttribute() =>
    Content($"- {nameof(FilterFactoryController)}.{nameof(WithServiceFilterAttribute)}");

在上述程式碼中，偏好使用套用篩選的第一種方法。

在篩選條件管線中使用中介軟體

資源篩選條件的運作與中介軟體相似之處在於，它們會圍繞管線中稍後的所有項目執行。 但篩選條件與中介軟體不同之處在於，它們是執行階段的一部分，這表示它們能存取內容和建構。

若要使用中介軟體作為篩選條件，請建立一個具有 Configure 方法的類型，其能指定要插入到篩選條件管線的中介軟體。 下列範例會使用中介軟體來設定回應標頭：

public class FilterMiddlewarePipeline
{
    public void Configure(IApplicationBuilder app)
    {
        app.Use(async (context, next) =>
        {
            context.Response.Headers.Add("Pipeline", "Middleware");

            await next();
        });
    }
}

使用 MiddlewareFilterAttribute 來執行中介軟體：

[MiddlewareFilter<FilterMiddlewarePipeline>]
public class FilterMiddlewareController : Controller
{
    public IActionResult Index() =>
        Content($"- {nameof(FilterMiddlewareController)}.{nameof(Index)}");
}

中介軟體篩選條件與資源篩選條件在相同的篩選條件管線階段執行：模型繫結之前和管線的其餘部分之後。

執行緒安全

將篩選的實例傳遞至 Add (而不是其 Type) 時，篩選條件是單一類型且不是安全執行續。

其他資源

• 檢視或下載範例 \(英文\) (如何下載)。
• ASP.NET Core 中 Razor Pages 的篩選方法