Filtry v ASP.NET Core

Kirk Larkin, Rick Anderson, Tom Dykstra a Steve Smith

Filtry v ASP.NET Core umožňují spuštění kódu před nebo po konkrétních fázích v kanálu zpracování požadavků.

Předdefinované filtry zpracovávají úlohy, jako jsou:

• Autorizace bránící přístupu k prostředkům, pro které uživatel nemá oprávnění.
• Ukládání odpovědí do mezipaměti, zkratování kanálu požadavku za účelem vrácení odpovědi uložené v mezipaměti

Vlastní filtry je možné vytvořit pro zpracování problémů s křížovým dělením. Mezi průřezové aspekty patří zpracování chyb, ukládání do mezipaměti, konfigurace, autorizace a protokolování. Filtry se vyhýbají duplikování kódu. Filtr výjimek zpracování chyb může například konsolidovat zpracování chyb.

Tento dokument se vztahuje na Razor stránky, kontrolery rozhraní API a kontrolery se zobrazeními. Filtry nefungují přímo se součástmiRazor. Filtr může pouze nepřímo ovlivnit komponentu v případech, kdy:

• Komponenta je vložena do stránky nebo zobrazení.
• Stránka nebo kontroler a zobrazení používají filtr.

Jak fungují filtry

Filtry se spouští v kanálu vyvolání akce ASP.NET Core, někdy označovaného jako kanál filtru. Kanál filtru se spustí po ASP.NET Core vybere akci, která se má provést:

Typy filtrů

Každý typ filtru se provádí v jiné fázi v kanálu filtru:

• Filtry autorizace:

  • Nejprve spusťte.
  • Určete, jestli má uživatel oprávnění k žádosti.
  • Zkratovat kanál, pokud požadavek není autorizovaný.

• Filtry prostředků:

  • Spusťte po autorizaci.
  • OnResourceExecuting spustí kód před zbývající částí kanálu filtru. Například OnResourceExecuting spustí kód před vazbou modelu.
  • OnResourceExecuted spustí kód po dokončení zbývající části kanálu.

• Filtry akcí:

  • Spusťte bezprostředně před a po zavolání metody akce.
  • Může změnit argumenty předané do akce.
  • Může změnit výsledek vrácený z akce.
  • Stránky se nepodporujíRazor.

• Filtry koncových bodů:

  • Spusťte bezprostředně před a po zavolání metody akce.
  • Může změnit argumenty předané do akce.
  • Může změnit výsledek vrácený z akce.
  • Stránky se nepodporujíRazor.
  • Je možné vyvolat jak u akcí, tak u koncových bodů založených na obslužné rutině směrování.

• Filtry výjimek aplikují globální zásady na neošetřené výjimky, ke kterým dochází před zápisem textu odpovědi.

• Filtry výsledků:

  • Spusťte bezprostředně před a po provedení výsledků akce.
  • Spusťte pouze v případech, kdy se metoda akce úspěšně provede.
  • Jsou užitečné pro logiku, která musí obklopovat provádění zobrazení nebo formátovače.

Následující diagram znázorňuje interakci typů filtrů v kanálu filtru:

Razor Stránky také podporují Razor filtry stránek, které se spouští před a za obslužnou rutinou Razor stránky.

Implementace

Filtry podporují synchronní i asynchronní implementace prostřednictvím různých definic rozhraní.

Synchronní filtry se spouštějí před a po fázi kanálu. Volá se například OnActionExecuting před zavolání metody akce. OnActionExecuted je volána po vrácení metody akce:

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.
    }
}

Asynchronní filtry definují metodu On-Stage-ExecutionAsync . Příklad: 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.
    }
}

V předchozím kódu má SampleAsyncActionFilter znak ActionExecutionDelegate, nextkterý provede metodu akce.

Více fází filtru

Rozhraní pro více fází filtru lze implementovat v jedné třídě. Například ActionFilterAttribute třída implementuje:

• Synchronní: IActionFilter a IResultFilter
• Asynchronní: IAsyncActionFilter a IAsyncResultFilter
• IOrderedFilter

Implementujte synchronní nebo asynchronní verzi rozhraní filtru, nikoli obě. Modul runtime nejprve zkontroluje, jestli filtr implementuje asynchronní rozhraní, a pokud ano, zavolá to. Pokud ne, volá synchronní metody rozhraní. Pokud jsou asynchronní i synchronní rozhraní implementována v jedné třídě, volá se pouze asynchronní metoda. Při použití abstraktních tříd, jako ActionFilterAttributeje , přepsat pouze synchronní metody nebo asynchronní metody pro každý typ filtru.

Předdefinované atributy filtru

ASP.NET Core obsahuje integrované filtry založené na atributech, které je možné přizpůsobit a podtřídy. Například následující filtr výsledků přidá hlavičku do odpovědi:

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

Atributy umožňují filtrům přijímat argumenty, jak je znázorněno v předchozím příkladu. ResponseHeaderAttribute Použijte metodu kontroleru nebo akce a zadejte název a hodnotu hlavičky HTTP:

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

    // ...

K prozkoumání hlaviček použijte nástroj, například vývojářské nástroje prohlížeče. V části Hlavičkyfilter-header: Filter Value odpovědi se zobrazí.

Následující kód platí ResponseHeaderAttribute pro kontroler i akci:

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

Odpovědi z Multiple akce zahrnují následující hlavičky:

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

Několik rozhraní filtru má odpovídající atributy, které lze použít jako základní třídy pro vlastní implementace.

Atributy filtru:

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

Filtry nelze použít u Razor metod obslužné rutiny stránky. Dají se použít buď na Razor model stránky, nebo globálně.

Filtrování oborů a pořadí provádění

Do kanálu je možné přidat filtr v jednom ze tří oborů:

• Použití atributu na kontroleru nebo Razor stránce
• Použití atributu v akci kontroleru Atributy filtru nelze použít u Razor metod obslužné rutiny Pages.
• Globálně pro všechny kontrolery, akce a Razor stránky, jak je znázorněno v následujícím kódu:

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

Výchozí pořadí provádění

Pokud existuje více filtrů pro určitou fázi kanálu, rozsah určuje výchozí pořadí provádění filtru. Globální filtry obklopují filtry tříd, které následně obklopují filtry metod ohraničí.

V důsledku vnoření filtru se kód filtrů spustí v opačném pořadí před kódem. Posloupnost filtrů:

• Před kódem globálních filtrů.
  • Před kódem kontroleru se filtruje.
    • Před kódem metody akce filtruje.
    • Následující kód metody akce filtruje.
  • Kód po kontroleru filtruje.
• Kód po globálních filtrech

Následující příklad znázorňuje pořadí spuštění metod filtru pro synchronní filtry akcí:

Sequence	Obor filtru	Metoda filtru
1	Globální	OnActionExecuting
2	Ovladač	OnActionExecuting
3	Akce	OnActionExecuting
4	Akce	OnActionExecuted
5	Ovladač	OnActionExecuted
6	Globální	OnActionExecuted

Filtry na úrovni kontroleru

Každý kontroler, který dědí z Controller , zahrnuje OnActionExecuting, OnActionExecutionAsynca OnActionExecuted metody. Tyto metody zabalí filtry, které se spustí pro danou akci:

• OnActionExecuting spustí se před libovolným filtrem akce.
• OnActionExecuted spustí se po všech filtrech akce.
• OnActionExecutionAsync spustí se před libovolným filtrem akce. Kód po volání, který se next spustí po filtrech akce.

Následující ControllerFiltersController třída:

• SampleActionFilterAttribute Použije ([SampleActionFilter]) na kontroler.
• Přepsání OnActionExecuting a 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.");
    }
}

Navigace pro https://localhost:<port>/ControllerFilters spuštění následujícího kódu:

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

Filtry na úrovni kontroleru nastavily vlastnost Order na int.MinValuehodnotu . Filtry na úrovni kontroleru nelze nastavit tak, aby se spouštěly po použití filtrů na metody. Pořadí je vysvětleno v další části.

V případě Razor stránek naleznete v tématu Implementace Razor filtrů stránky přepsáním metod filtru.

Přepsání výchozího pořadí

Výchozí posloupnost provádění lze přepsat implementací IOrderedFilter. IOrderedFilterOrder zveřejňuje vlastnost, která má přednost před oborem k určení pořadí provádění. Filtr s nižší Order hodnotou:

• Spustí před kódem před filtrem s vyšší hodnotou Order.
• Spustí následující kód po filtru s vyšší Order hodnotou.

V příkladu filtrů na úrovni kontroleru má globální obor, GlobalSampleActionFilter aby se spustil před SampleActionFilterAttribute, který má obor kontroleru. Pokud chcete provést SampleActionFilterAttribute spuštění jako první, nastavte jeho pořadí na int.MinValue:

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

Pokud chcete, aby se globální filtr GlobalSampleActionFilter spustil jako první, nastavte jeho Order hodnotu na int.MinValue:

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

Zrušení a zkratování

Kanál filtru může být zkrácený nastavením Result vlastnosti parametru ResourceExecutingContext poskytnutého metodě filtru. Například následující filtr prostředků brání spuštění zbytku kanálu:

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

    public void OnResourceExecuted(ResourceExecutedContext context) { }
}

V následujícím kódu cílí metoda akce jak na [ShortCircuitingResourceFilter] filtr, tak i na metodu [ResponseHeader]Index akce. Filtr ShortCircuitingResourceFilterAttribute :

• Spustí se jako první, protože se jedná o filtr prostředků a ResponseHeaderAttribute je to filtr akcí.
• Zkratuje zbytek kanálu.

Proto se ResponseHeaderAttribute filtr pro Index akci nikdy nespustí. Toto chování by bylo stejné, pokud se oba filtry použily na úrovni metody akce za předpokladu, že první ShortCircuitingResourceFilterAttribute spuštění. První spuštění ShortCircuitingResourceFilterAttribute z důvodu typu filtru:

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

Injektáž závislostí

Filtry lze přidat podle typu nebo podle instance. Pokud se přidá instance, použije se tato instance pro každý požadavek. Pokud je typ přidaný, aktivuje se typ. Filtr aktivovaný typem znamená:

• Pro každý požadavek se vytvoří instance.
• Všechny závislosti konstruktoru jsou naplněny injektáží závislostí (DI).

Filtry implementované jako atributy a přidané přímo do tříd kontroleru nebo metod akcí nemohou mít závislosti konstruktoru poskytované injektáží závislostí (DI). Závislosti konstruktoru nelze pomocí direktoru poskytnout, protože atributy musí mít parametry konstruktoru zadané tam, kde jsou použity.

Následující filtry podporují závislosti konstruktoru poskytované z DI:

• ServiceFilterAttribute
• TypeFilterAttribute
• IFilterFactory implementovaný u atributu.

Předchozí filtry lze použít u kontroleru nebo akce.

Protokolovací nástroje jsou k dispozici v DI. Vyhněte se ale vytváření a používání filtrů čistě pro účely protokolování. Integrované protokolování architektury obvykle poskytuje to, co je potřeba k protokolování. Protokolování přidané do filtrů:

• Měli byste se zaměřit na obavy nebo chování obchodní domény specifické pro filtr.
• Neměly by protokolovat akce ani jiné události architektury. Integrované filtry už protokoluje akce a události rozhraní.

ServiceFilterAttribute

Typy implementace filtru služby jsou registrovány v Program.cs. A ServiceFilterAttribute načte instanci filtru z DI.

Následující kód ukazuje LoggingResponseHeaderFilterService třídu, která používá DI:

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

V následujícím kódu LoggingResponseHeaderFilterService se přidá do kontejneru DI:

builder.Services.AddScoped<LoggingResponseHeaderFilterService>();

V následujícím kódu ServiceFilter načte atribut instanci LoggingResponseHeaderFilterService filtru z DI:

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

Při použití ServiceFilterAttribute, nastavení ServiceFilterAttribute.IsReusable:

• Poskytuje nápovědu, že instance filtru může být znovu použita mimo obor požadavku, který byl vytvořen v rámci. Modul runtime ASP.NET Core nezaručuje:
  • Vytvoří se jedna instance filtru.
  • V pozdějším okamžiku se filtr z kontejneru DI znovu nepožaduje.
• Neměli byste se používat s filtrem, který závisí na službách s jinou životností než singleton.

ServiceFilterAttribute implementuje IFilterFactory. IFilterFactory zveřejňuje metodu CreateInstanceIFilterMetadata pro vytvoření instance. CreateInstance načte zadaný typ z DI.

TypeFilterAttribute

TypeFilterAttribute je podobný , ServiceFilterAttributeale jeho typ není vyřešen přímo z kontejneru DI. Vytvoří instanci typu pomocí .Microsoft.Extensions.DependencyInjection.ObjectFactory

Vzhledem k tomu, že TypeFilterAttribute typy nejsou vyřešeny přímo z kontejneru DI:

• Typy odkazované pomocí kontejneru TypeFilterAttribute DI nemusí být zaregistrované. Mají své závislosti splněné kontejnerem DI.
• TypeFilterAttribute lze volitelně přijmout argumenty konstruktoru pro typ.

Při použití TypeFilterAttribute, nastavení TypeFilterAttribute.IsReusable:

• Poskytuje nápovědu k opětovnému použití instance filtru mimo obor požadavku, který byl vytvořen v rámci. Modul runtime ASP.NET Core neposkytuje žádné záruky, že se vytvoří jedna instance filtru.

• Neměla by se používat s filtrem, který závisí na službách s jinou životností než singleton.

Následující příklad ukazuje, jak předat argumenty do typu pomocí TypeFilterAttribute:

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

Filtry autorizace

Filtry autorizace:

• Jsou první filtry spuštěné v kanálu filtru.
• Řízení přístupu k metodám akcí
• Mít před metodou, ale ne za metodou.

Vlastní autorizační filtry vyžadují vlastní autorizační architekturu. Preferujte konfiguraci zásad autorizace nebo psaní vlastních zásad autorizace před zápisem vlastního filtru. Předdefinovaný autorizační filtr:

• Volá systém autorizace.
• Neautorizuje žádosti.

Nevyvolávejte výjimky v rámci autorizačních filtrů:

• Výjimka nebude zpracována.
• Filtry výjimek nezpracují výjimku.

Zvažte vydání výzvy, pokud dojde k výjimce ve filtru autorizace.

Přečtěte si další informace o autorizaci.

Filtry prostředků

Filtry prostředků:

• Implementujte buď rozhraní IResourceFilter , nebo IAsyncResourceFilter rozhraní.
• Provádění zabalí většinu kanálu filtru.
• Před filtry prostředků se spouští pouze filtry autorizace.

Filtry prostředků jsou užitečné pro zkratovou část kanálu. Filtr ukládání do mezipaměti se například může vyhnout zbytku kanálu při dosažení mezipaměti.

Příklady filtru prostředků:

• Filtr prostředků zkratek zobrazený dříve.

• DisableFormValueModelBindingAttribute:

  • Zabraňuje vazbě modelu v přístupu k datům formuláře.
  • Slouží k nahrání velkých souborů, aby se zabránilo čtení dat formuláře do paměti.

Filtry akcí

Filtry akcí se nevztahují na Razor stránky. Razor Stránky podporují IPageFilter a IAsyncPageFilter. Další informace naleznete v tématu Metody filtrování pro Razor stránky.

Filtry akcí:

• Implementujte buď rozhraní IActionFilter , nebo IAsyncActionFilter rozhraní.
• Jejich spuštění obklopuje provádění metod akcí.

Následující kód ukazuje ukázkový filtr akcí:

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.
    }
}

Poskytuje ActionExecutingContext následující vlastnosti:

• ActionArguments - umožňuje čtení vstupů do metody akce.
• Controller – umožňuje manipulaci s instancí kontroleru.
• Result - nastavení Result provádění metody akce a následných filtrů akcí.

Vyvolání výjimky v metodě akce:

• Zabraňuje spuštění následných filtrů.
• Na rozdíl od nastavení Resultse místo úspěšného výsledku považuje za selhání.

Controller Poskytuje ActionExecutedContext a Result plus následující vlastnosti:

• Canceled – Hodnota True, pokud provádění akce bylo zkráceno jiným filtrem.
• Exception - Nenulová, pokud akce nebo dříve spuštěný filtr akce vyvolal výjimku. Nastavení této vlastnosti na hodnotu null:
  • Efektivně zpracovává výjimku.
  • Result se spustí, jako by byla vrácena z metody akce.

Pro volání IAsyncActionFilterActionExecutionDelegate:

• Provede všechny následné filtry akcí a metodu akce.
• Vrací objekt ActionExecutedContext.

Pokud chcete zkratovat, přiřaďte Microsoft.AspNetCore.Mvc.Filters.ActionExecutingContext.Result k instanci výsledku a nezavolejte next (the ActionExecutionDelegate).

Architektura poskytuje abstrakci ActionFilterAttribute , kterou lze podtřídět.

Filtr OnActionExecuting akcí lze použít k:

• Ověřte stav modelu.
• Pokud je stav neplatný, vraťte chybu.

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

Poznámka

Kontrolery anotované atributem [ApiController] automaticky ověří stav modelu a vrátí odpověď 400. Další informace naleznete v tématu Automatické odpovědi HTTP 400.

Metoda OnActionExecuted se spustí po metodě akce:

• A může zobrazit a manipulovat s výsledky akce prostřednictvím Result vlastnosti.
• Canceled je nastavena na hodnotu true, pokud provádění akce bylo zkráceno jiným filtrem.
• Exception je nastavena na hodnotu, která není null, pokud akce nebo následný filtr akcí vyvolal výjimku. Nastavení Exception na hodnotu null:
  • Efektivně zpracovává výjimku.
  • ActionExecutedContext.Result je spuštěna, jako by byla vrácena normálně z metody akce.

Filtry výjimek

Filtry výjimek:

• Implementace IExceptionFilter nebo IAsyncExceptionFilter.
• Dá se použít k implementaci běžných zásad zpracování chyb.

Následující ukázkový filtr výjimek zobrazí podrobnosti o výjimkách, ke kterým dochází při vývoji aplikace:

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

Následující kód testuje filtr výjimek:

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

Filtry výjimek:

• Nemáte před a po událostech.
• Implementace OnException nebo OnExceptionAsync.
• Zpracování neošetřených výjimek, ke kterým dochází při Razor vytváření stránky nebo kontroleru, vazbě modelu, filtrech akcí nebo metodách akcí
• Nezachycujte výjimky, ke kterým dochází v filtrech prostředků, filtrech výsledků nebo provádění výsledků MVC.

Pokud chcete zpracovat výjimku, nastavte ExceptionHandled vlastnost na true vlastnost nebo ji přiřaďte Result . Tím se zastaví šíření výjimky. Filtr výjimek nemůže změnit výjimku na "úspěch". To může udělat jenom filtr akcí.

Filtry výjimek:

• Jsou vhodné pro výjimky zachycení, ke kterým dochází v rámci akcí.
• Nejsou tak flexibilní jako middleware pro zpracování chyb.

Preferujte middleware pro zpracování výjimek. Filtry výjimek použijte pouze v případě, že se zpracování chyb liší podle toho, jakou metodu akce volá. Aplikace může mít například metody akcí pro koncové body rozhraní API i pro zobrazení/HTML. Koncové body rozhraní API můžou vracet informace o chybách jako JSZAPNUTO, zatímco akce založené na zobrazení můžou vrátit chybovou stránku jako HTML.

Filtry výsledků

Filtry výsledků:

• Implementace rozhraní:
  • IResultFilter nebo IAsyncResultFilter
  • IAlwaysRunResultFilter nebo IAsyncAlwaysRunResultFilter
• Jejich spuštění obklopuje provádění výsledků akce.

IResultFilter a IAsyncResultFilter

Následující kód ukazuje ukázkový filtr výsledků:

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.
    }
}

Druh spuštění výsledku závisí na akci. Akce vracející zobrazení zahrnuje veškeré zpracování razoru jako součást ViewResult provádění. Metoda rozhraní API může v rámci provádění výsledku provádět určité serializace. Přečtěte si další informace o výsledcích akcí.

Filtry výsledků se provádějí pouze v případech, kdy akce nebo filtr akcí vytvoří výsledek akce. Filtry výsledků se nespustí, když:

• Filtr autorizace nebo krátký okruh filtru prostředků kanálem.
• Filtr výjimek zpracovává výjimku tím, že vytvoří výsledek akce.

Metoda Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuting může zkratovat spuštění výsledku akce a následných filtrů výsledků nastavením Microsoft.AspNetCore.Mvc.Filters.ResultExecutingContext.Cancel na truehodnotu . Při zkratce zapište do objektu odpovědi, abyste se vyhnuli generování prázdné odpovědi. Vyvolání výjimky v IResultFilter.OnResultExecuting:

• Zabrání spuštění výsledku akce a následných filtrů.
• Místo úspěšného výsledku se považuje za selhání.

Když se Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuted metoda spustí, odpověď již pravděpodobně byla odeslána klientovi. Pokud už byla odpověď odeslána klientovi, nelze ji změnit.

ResultExecutedContext.Canceled je nastavena na true to, zda bylo provedení výsledku akce zkráceno jiným filtrem.

ResultExecutedContext.Exception je nastavena na hodnotu, která není null, pokud výsledek akce nebo následný filtr výsledků vyvolal výjimku. Nastavení Exception na hodnotu null efektivně zpracuje výjimku a zabrání opětovnému vyvolání výjimky později v kanálu. Neexistuje žádný spolehlivý způsob zápisu dat do odpovědi při zpracování výjimky ve filtru výsledků. Pokud se hlavičky vyprázdnily klientovi, když výsledek akce vyvolá výjimku, neexistuje žádný spolehlivý mechanismus pro odeslání kódu selhání.

V případě IAsyncResultFiltervolání na await next příkaz ResultExecutionDelegate provede všechny následné filtry výsledků a výsledek akce. Pokud chcete zkratovat, nastavte ResultExecutingContext.Canceltrue a nezavolejte 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;
        }
    }
}

Architektura poskytuje abstrakci ResultFilterAttribute , kterou lze podtřídět. Dříve zobrazená třída ResponseHeaderAttribute je příkladem atributu filtru výsledků.

IAlwaysRunResultFilter a IAsyncAlwaysRunResultFilter

IAsyncAlwaysRunResultFilter Rozhraní IAlwaysRunResultFilter deklarují implementaciIResultFilter, která se spouští pro všechny výsledky akce. To zahrnuje výsledky akcí vytvořené tímto:

• Filtry autorizace a filtry prostředků, které jsou zkrácené.
• Filtry výjimek.

Například následující filtr se vždy spustí a nastaví výsledek akce (ObjectResult) se stavovým kódem 422 Nezpracované entity , když selže vyjednávání obsahu:

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 implementuje IFilterMetadata. IFilterFactory Proto lze instanci použít jako IFilterMetadata instanci kdekoli v kanálu filtru. Když modul runtime připraví k vyvolání filtru, pokusí se ho přetypovat na .IFilterFactory Pokud je toto přetypování úspěšné, CreateInstance volá se metoda k vytvoření IFilterMetadata instance, která je vyvolána. To poskytuje flexibilní návrh, protože při spuštění aplikace není nutné explicitně nastavit přesný kanál filtru.

IFilterFactory.IsReusable:

• Je nápovědou objektu pro vytváření, že instance filtru vytvořená továrnou může být znovu použita mimo obor požadavku, ve které byla vytvořena.
• Neměla by se používat s filtrem, který závisí na službách s jinou životností než singleton.

Modul runtime ASP.NET Core nezaručuje:

• Vytvoří se jedna instance filtru.
• V pozdějším okamžiku se filtr z kontejneru DI znovu nepožaduje.

Upozorňující

Nakonfigurovat IFilterFactory.IsReusable , aby se vrátil true pouze v případě, že je zdroj filtrů jednoznačný, filtry jsou bezstavové a filtry jsou bezpečné pro použití napříč více požadavky HTTP. Například nevrací filtry z DI, které jsou registrovány jako vymezené nebo přechodné, pokud IFilterFactory.IsReusable vrátí true.

IFilterFactory lze implementovat pomocí implementací vlastních atributů jako další přístup k vytváření filtrů:

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) { }
    }

Filtr se použije v následujícím kódu:

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

IFilterFactory implementovaný u atributu

Filtry, které implementují IFilterFactory , jsou užitečné pro filtry, které:

• Nevyžadují předávání parametrů.
• Mají závislosti konstruktoru, které musí být vyplněny DI.

TypeFilterAttribute implementuje IFilterFactory. IFilterFactory zveřejňuje metodu CreateInstanceIFilterMetadata pro vytvoření instance. CreateInstance načte zadaný typ z kontejneru služeb (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)}");
        }
    }
}

Následující kód ukazuje tři přístupy k použití filtru:

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

V předchozím kódu je upřednostňovaný první přístup k použití filtru.

Použití middlewaru v kanálu filtru

Filtry prostředků fungují podobně jako middleware v tom, že obklopují provádění všeho, co se dodává později v kanálu. Filtry se ale liší od middlewaru v tom, že jsou součástí modulu runtime, což znamená, že mají přístup k kontextu a konstruktorům.

Pokud chcete použít middleware jako filtr, vytvořte typ s metodou Configure , která určuje middleware, který se má vložit do kanálu filtru. Následující příklad používá middleware k nastavení hlavičky odpovědi:

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

            await next();
        });
    }
}

MiddlewareFilterAttribute Použijte ke spuštění middlewaru:

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

Filtry middlewaru se spouštějí ve stejné fázi kanálu filtru jako filtry prostředků před vazbou modelu a po zbývající části kanálu.

Bezpečnost vlákna

Při předávání instance filtru do Addobjektu , místo jeho Type, je filtr singleton a neníbezpečný pro přístup z více vláken.

Další prostředky

• Zobrazení nebo stažení ukázky (postup stažení)
• Metody filtrování pro Razor stránky v ASP.NET Core