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 ページでは、Razor ページ ハンドラーの前後に実行する Razor ページ フィルターもサポートされます。

実装

フィルターは、異なるインターフェイス定義を介して、同期と非同期の実装をサポートします。

同期フィルターは、そのパイプライン ステージの前後に実行します。 たとえば、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 があります。

複数のフィルター ステージ

複数のフィルター ステージのためのインターフェイスを 1 つのクラスで実装できます。 たとえば、ActionFilterAttribute クラスでは次のものが実装されます。

• 同期: IActionFilter と IResultFilter
• 非同期: IAsyncActionFilter と IAsyncResultFilter
• IOrderedFilter

フィルター インターフェイスの同期と非同期バージョンの両方ではなく、いずれかを実装します。 ランタイムは、最初にフィルターが非同期インターフェイスを実装しているかどうかをチェックして、している場合はそれを呼び出します。 していない場合は、同期インターフェイスのメソッドを呼び出します。 非同期インターフェイスと同期インターフェイスの両方が 1 つのクラスで実装される場合、非同期メソッドのみが呼び出されます。 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 ページ ハンドラー メソッドにフィルターを適用することはできません。 これらは、Razor ページ モデルに適用するか、グローバルに適用することが可能です。

フィルターのスコープと実行の順序

フィルターは、3 つのスコープのいずれかでパイプラインに追加することができます。

• コントローラーまたは Razor ページでの属性の使用。
• コントローラー アクションでの属性の使用。 フィルター属性を Razor Pages ハンドラー メソッドに適用することはできません。
• 次のコードのように、すべてのコントローラー、アクション、および Razor Pages に対してグローバルに:

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

実行の既定の順序

パイプラインの特定のステージに対して複数のフィルターがある場合に、スコープがフィルターの実行の既定の順序を決定します。 グローバル フィルターがクラス フィルターを囲み、クラス フィルターがメソッド フィルターを囲みます。

フィルターの入れ子の結果として、フィルターの after コードが before コードと逆の順序で実行されます。 フィルター シーケンス:

• グローバル フィルターの before コード。
  • コントローラー フィルターの before コード。
    • アクション メソッド フィルターの before コード。
    • アクション メソッド フィルターの after コード。
  • コントローラー フィルターの after コード。
• グローバル フィルターの after コード。

次の例は、同期アクション フィルターに対してフィルター メソッドが実行される順序を示しています。

シークエンス	フィルターのスコープ	フィルター メソッド
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 ページにフィルターを実装する方法に関するページを参照してください。

既定の順序をオーバーライドする

IOrderedFilter を実装することで、実行の既定の順序をオーバーライドできます。 IOrderedFilter により、実行の順序を決定するために、スコープよりも優先される Order プロパティが公開されます。 より低い Order 値を持つフィルター:

• より高い Order の値を持つフィルターのそれよりも前に before コードが実行されます。
• より高い Order の値を持つフィルターのそれよりも後に after コードが実行されます。

コントローラー レベルのフィルターの例では、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 ランタイムで保証されないこと:
  • フィルターのインスタンスが 1 つ作成されます。
  • フィルターが後の時点で、DI コンテナーから再要求されることはありません。
• シングルトン以外で有効期間があるサービスに依存するフィルターと共にを使用しないでください。

ServiceFilterAttribute は、IFilterFactory を実装します。 IFilterFactory は、IFilterMetadata インスタンスを作成するために CreateInstance メソッドを公開します。 CreateInstance により、DI から指定の型が読み込まれます。

TypeFilterAttribute

TypeFilterAttribute はServiceFilterAttribute と似ていますが、その型は DI コンテナーから直接解決されません。 Microsoft.Extensions.DependencyInjection.ObjectFactory を使って型をインスタンス化します。

TypeFilterAttribute 型は DI コンテナーから直接解決されないためです。

• TypeFilterAttribute を利用して参照される型は、DI コンテナーに登録する必要がありません。 DI コンテナーによって依存関係が満たされています。
• TypeFilterAttribute は必要に応じて、型のコンストラクター引数を受け取ることができます。

TypeFilterAttribute を使用する場合、TypeFilterAttribute.IsReusable を設定します。

• フィルター インスタンスが、それが作成された要求範囲の外で再利用される可能性があることを示唆します。 ASP.NET Core ランタイムでは、フィルターの 1 インスタンスが作成されるという保証はありません。

• シングルトン以外で有効期間があるサービスに依存するフィルターと共に使用しないでください。

次の例は、TypeFilterAttribute を使用して、型に引数を渡す方法を示しています。

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

承認フィルター

承認フィルター:

• フィルター パイプライン内で実行される最初のフィルターです。
• アクション メソッドへのアクセスを制御します。
• before メソッドが与えられ、after メソッドは与えられません。

カスタム承認フィルターには、カスタム承認フレームワークが必要です。 カスタム フィルターを記述するよりも、独自の承認ポリシーを構成するか、カスタム承認ポリシーを記述することを選びます。 組み込み承認フィルター:

• 承認システムを呼び出します。
• 要求は承認されません。

承認フィルター内で例外をスローしません。

• 例外は処理されません。
• 例外フィルターで例外が処理されません。

承認フィルターで例外が発生した場合、チャレンジ発行を検討してください。

承認の詳細については、こちらを参照してください。

リソース フィルター

リソース フィルター:

• 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);
        }
    }
}

Note

[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)}");
}

例外フィルター:

• before イベントと after イベントが与えられません。
• 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.IResultFilter.OnResultExecuting メソッドは、Microsoft.AspNetCore.Mvc.Filters.ResultExecutingContext.Cancel を true に設定することで、アクションの結果と後続の結果フィルターの実行をショートサーキットできます。 ショートサーキットする場合は、空の応答が生成されないように応答オブジェクトに記述します。 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 の実装が宣言されます。 これには、以下によって生成されるアクションの結果が含まれます。

• ショートサーキットが行われる承認フィルターとリソース フィルター。
• 例外フィルター。

たとえば、次のフィルターは常に実行され、コンテンツ ネゴシエーションが失敗した場合に "422 処理不可エンティティ" 状態コードを使ってアクションの結果 (ObjectResult) を設定します。

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 へのキャストが試行されます。 そのキャストが成功した場合、呼び出される IFilterMetadata インスタンスを作成するために CreateInstance メソッドが呼び出されます。 これにより、アプリの起動時に正確なフィルター パイプラインを明示的に設定する必要がないため、柔軟なデザインが可能になります。

IFilterFactory.IsReusable:

• ファクトリによって作成されたフィルター インスタンスは、それが作成された要求範囲の外で使用される可能性があることがファクトリによって示されています。
• シングルトン以外で有効期間があるサービスに依存するフィルターと共に使用しないでください。

ASP.NET Core ランタイムで保証されないこと:

• フィルターのインスタンスが 1 つ作成されます。
• フィルターが後の時点で、DI コンテナーから再要求されることはありません。

警告

フィルターが明確ではない、フィルターがステートレスである、フィルターは複数の HTTP 要求で安全に使用できる場合にのみ、true を返すように IFilterFactory.IsReusable を構成します。 たとえば、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 は、IFilterMetadata インスタンスを作成するために CreateInstance メソッドを公開します。 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)}");
        }
    }
}

次のコードでは、フィルターを適用する 3 つの手法を確認できます。

[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)}");
}

ミドルウェア フィルターは、フィルター パイプラインのリソース フィルターと同じステージ (モデル バインドの前、残りのパイプラインの後) で実行されます。

スレッド セーフ

その Type の代わりにフィルターの "インスタンス" を Add に渡すとき、フィルターはシングルトンであり、スレッドセーフではありません。

その他のリソース

• サンプルを表示またはダウンロードします (ダウンロード方法)。
• ASP.NET Core の Razor Pages のフィルター メソッド