Filtry w ASP.NET Core

Przez Kirk Larkin, Rick Anderson, Tom Dykstra i Steve Smith

Filtry w ASP.NET Core umożliwiają uruchamianie kodu przed lub po określonych etapach w potoku przetwarzania żądań.

Wbudowane filtry obsługują zadania, takie jak:

• Autoryzacja, uniemożliwiająca dostęp do zasobów, dla których użytkownik nie jest autoryzowany.
• Buforowanie odpowiedzi, zwarcie potoku żądania w celu zwrócenia buforowanej odpowiedzi.

Filtry niestandardowe można tworzyć w celu obsługi problemów związanych z wycinaniami krzyżowymi. Przykłady problemów obejmujących krzyżowe obejmują obsługę błędów, buforowanie, konfigurację, autoryzację i rejestrowanie. Filtry unikają duplikowania kodu. Na przykład filtr wyjątków obsługi błędów może skonsolidować obsługę błędów.

Ten dokument dotyczy Razor stron, kontrolerów interfejsu API i kontrolerów z widokami. Filtry nie działają bezpośrednio ze składnikamiRazor. Filtr może mieć wpływ tylko pośrednio na składnik, gdy:

• Składnik jest osadzony na stronie lub w widoku.
• Strona lub kontroler i widok używają filtru.

Jak działają filtry

Filtry są uruchamiane w potoku wywołania akcji ASP.NET Core, czasami nazywane potokiem filtru. Potok filtru jest uruchamiany po wybraniu akcji do wykonania przez ASP.NET Core:

Typy filtrów

Każdy typ filtru jest wykonywany na innym etapie w potoku filtru:

• Filtry autoryzacji:

  • Uruchom najpierw polecenie .
  • Ustal, czy użytkownik ma autoryzację do żądania.
  • Zwarcie potoku, jeśli żądanie nie jest autoryzowane.

• Filtry zasobów:

  • Uruchom polecenie po autoryzacji.
  • OnResourceExecuting uruchamia kod przed resztą potoku filtru. Na przykład OnResourceExecuting uruchamia kod przed powiązaniem modelu.
  • OnResourceExecuted uruchamia kod po zakończeniu pozostałej części potoku.

• Filtry akcji:

  • Uruchom bezpośrednio przed wywołaną metodą akcji i po jej wywołaniu.
  • Może zmienić argumenty przekazane do akcji.
  • Może zmienić wynik zwrócony z akcji.
  • Nie są obsługiwane na Razor stronach.

• Filtry punktów końcowych:

  • Uruchom bezpośrednio przed wywołaną metodą akcji i po jej wywołaniu.
  • Może zmienić argumenty przekazane do akcji.
  • Może zmienić wynik zwrócony z akcji.
  • Nie są obsługiwane na Razor stronach.
  • Można wywołać zarówno na akcjach, jak i na punktach końcowych opartych na programie obsługi tras.

• Filtry wyjątków stosują zasady globalne do nieobsługiwanych wyjątków występujących przed zapisaniem treści odpowiedzi.

• Filtry wyników:

  • Uruchom polecenie bezpośrednio przed i po wykonaniu wyników akcji.
  • Uruchom polecenie tylko wtedy, gdy metoda akcji zostanie wykonana pomyślnie.
  • Są przydatne w przypadku logiki, która musi otaczać wykonywanie widoku lub formatera.

Na poniższym diagramie przedstawiono sposób interakcji typów filtrów w potoku filtru:

Razor Strony obsługują Razor również filtry strony, które są uruchamiane przed i po procedurze Razor obsługi strony.

Implementacja

Filtry obsługują zarówno implementacje synchroniczne, jak i asynchroniczne za pomocą różnych definicji interfejsu.

Filtry synchroniczne są uruchamiane przed i po etapie potoku. Na przykład OnActionExecuting jest wywoływana przed wywołaniem metody akcji. OnActionExecuted jest wywoływana po zwracaniu metody akcji:

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

Filtry asynchroniczne definiują metodę On-Stage-ExecutionAsync . Na przykład : 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.
    }
}

W poprzednim kodzie element SampleAsyncActionFilter ma ActionExecutionDelegatewartość , nextktóra wykonuje metodę akcji .

Wiele etapów filtrowania

Interfejsy dla wielu etapów filtrowania można zaimplementować w jednej klasie. Na przykład ActionFilterAttribute klasa implementuje:

• Synchroniczne: IActionFilter i IResultFilter
• Asynchroniczne: IAsyncActionFilter i IAsyncResultFilter
• IOrderedFilter

Zaimplementuj synchroniczną lub asynchroniczną wersję interfejsu filtru, a nie obie. Środowisko uruchomieniowe najpierw sprawdza, czy filtr implementuje interfejs asynchroniczny, a jeśli tak, wywołuje to. Jeśli nie, wywołuje metody interfejsu synchronicznego. Jeśli oba interfejsy asynchroniczne i synchroniczne są implementowane w jednej klasie, wywoływana jest tylko metoda asynchroniczna. W przypadku używania klas abstrakcyjnych, takich jak ActionFilterAttribute, przesłaniaj tylko metody synchroniczne lub metody asynchroniczne dla każdego typu filtru.

Wbudowane atrybuty filtru

ASP.NET Core zawiera wbudowane filtry oparte na atrybutach, które mogą być podklasowane i dostosowane. Na przykład następujący filtr wyników dodaje nagłówek do odpowiedzi:

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

Atrybuty umożliwiają filtrowanie akceptowania argumentów, jak pokazano w poprzednim przykładzie. Zastosuj element ResponseHeaderAttribute do kontrolera lub metody akcji i określ nazwę i wartość nagłówka HTTP:

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

    // ...

Użyj narzędzia, takiego jak narzędzia deweloperskie przeglądarki, aby zbadać nagłówki. W obszarze Nagłówkifilter-header: Filter Value odpowiedzi zostanie wyświetlona wartość .

Następujący kod dotyczy ResponseHeaderAttribute zarówno kontrolera, jak i akcji:

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

Odpowiedzi z Multiple akcji obejmują następujące nagłówki:

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

Kilka interfejsów filtru ma odpowiednie atrybuty, których można używać jako klas bazowych na potrzeby implementacji niestandardowych.

Atrybuty filtru:

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

Nie można zastosować filtrów do Razor metod obsługi strony. Można je zastosować do Razor modelu strony lub globalnie.

Filtrowanie zakresów i kolejności wykonywania

Filtr można dodać do potoku w jednym z trzech zakresów:

• Używanie atrybutu na kontrolerze lub Razor stronie.
• Używanie atrybutu w akcji kontrolera. Nie można zastosować atrybutów filtru do Razor metod obsługi stron.
• Globalnie dla wszystkich kontrolerów, akcji i Razor stron, jak pokazano w poniższym kodzie:

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

Domyślna kolejność wykonywania

Jeśli istnieje wiele filtrów dla określonego etapu potoku, zakres określa domyślną kolejność wykonywania filtru. Filtry globalne otaczają filtry klas, które z kolei otaczają filtry metod.

W wyniku zagnieżdżania filtrów kod po filtrach jest uruchamiany w odwrotnej kolejności przed kodem. Sekwencja filtru:

• Przed kodem filtrów globalnych.
  • Przed kodem filtrów kontrolera.
    • Przed kodem metody akcji filtruje.
    • Po kodzie metody akcji filtruje.
  • Po kodzie kontrolera filtrów.
• Po kodzie filtrów globalnych.

Poniższy przykład ilustruje kolejność uruchamiania metod filtrowania dla filtrów akcji synchronicznych:

Sequence	Zakres filtru	Metoda filter
1	Globalnie	OnActionExecuting
2	Kontroler	OnActionExecuting
3	Akcja	OnActionExecuting
4	Akcja	OnActionExecuted
5	Kontroler	OnActionExecuted
6	Globalnie	OnActionExecuted

Filtry na poziomie kontrolera

Każdy kontroler dziedziczony z Controller zawiera OnActionExecutingmetody , OnActionExecutionAsynci OnActionExecuted . Te metody opakowuje filtry uruchamiane dla danej akcji:

• OnActionExecuting uruchamia się przed dowolnym filtrem akcji.
• OnActionExecuted uruchamia się po wszystkich filtrach akcji.
• OnActionExecutionAsync uruchamia się przed dowolnym filtrem akcji. Kod po wywołaniu do next uruchomienia po filtrach akcji.

Następująca ControllerFiltersController klasa:

• Stosuje element SampleActionFilterAttribute ([SampleActionFilter]) do kontrolera.
• Przesłonięcia OnActionExecuting i 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.");
    }
}

Przechodzenie do https://localhost:<port>/ControllerFilters uruchomi następującego kodu:

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

Filtry na poziomie kontrolera ustawiają właściwość Order na int.MinValue. Filtry na poziomie kontrolera nie można ustawić tak, aby były uruchamiane po zastosowaniu filtrów do metod. Kolejność jest wyjaśniona w następnej sekcji.

Aby uzyskać informacje na temat Razor stron, zobacz Implementowanie Razor filtrów stron przez zastępowanie metod filtrowania.

Zastąpij kolejność domyślną

Domyślną sekwencję wykonywania można zastąpić przez zaimplementowanie metody IOrderedFilter. IOrderedFilter Uwidacznia Order właściwość, która ma pierwszeństwo przed zakresem, aby określić kolejność wykonywania. Filtr o niższej Order wartości:

• Uruchamia przed kodem przed filtrem o wyższej wartości Order.
• Uruchamia po kodzie po filtrze z wyższą Order wartością.

W przykładzie filtry na poziomie kontrolera ma zakres globalny, GlobalSampleActionFilter więc działa przed SampleActionFilterAttribute, który ma zakres kontrolera. Aby najpierw wykonać SampleActionFilterAttribute przebieg, ustaw jego kolejność na int.MinValue:

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

Aby najpierw ustawić przebieg filtru GlobalSampleActionFilter globalnego, ustaw wartość Orderint.MinValue:

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

Anulowanie i zwarcie

Potok filtru można zwarcić, ustawiając Result właściwość parametru ResourceExecutingContext podanego w metodzie filtru. Na przykład następujący filtr zasobu uniemożliwia wykonywanie pozostałej części potoku:

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

    public void OnResourceExecuted(ResourceExecutedContext context) { }
}

W poniższym kodzie, zarówno filtr, jak [ShortCircuitingResourceFilter] i docelowy [ResponseHeader]Index filtr metody akcji. Filtr ShortCircuitingResourceFilterAttribute :

• Uruchamia najpierw, ponieważ jest to filtr zasobów i ResponseHeaderAttribute jest filtrem akcji.
• Zwarcie pozostałej części potoku.

W związku z tym ResponseHeaderAttribute filtr nigdy nie jest uruchamiany dla Index akcji. To zachowanie byłoby takie samo, jeśli oba filtry zostały zastosowane na poziomie metody akcji, pod warunkiem, że uruchomiono ShortCircuitingResourceFilterAttribute najpierw. Przebiegi ShortCircuitingResourceFilterAttribute najpierw ze względu na jego typ filtru:

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

Wstrzykiwanie zależności

Filtry można dodawać według typu lub wystąpienia. Jeśli wystąpienie zostanie dodane, to wystąpienie jest używane dla każdego żądania. Jeśli typ zostanie dodany, zostanie aktywowany typ. Filtr aktywowany przez typ oznacza:

• Wystąpienie jest tworzone dla każdego żądania.
• Wszystkie zależności konstruktora są wypełniane przez wstrzykiwanie zależności (DI).

Filtry implementowane jako atrybuty i dodawane bezpośrednio do klas kontrolerów lub metod akcji nie mogą mieć zależności konstruktora zapewniane przez wstrzykiwanie zależności (DI). Zależności konstruktora nie mogą być udostępniane przez di, ponieważ atrybuty muszą mieć parametry konstruktora podane tam, gdzie są stosowane.

Następujące filtry obsługują zależności konstruktora dostarczone z di:

• ServiceFilterAttribute
• TypeFilterAttribute
• IFilterFactory zaimplementowany w atrybucie .

Powyższe filtry można zastosować do kontrolera lub akcji.

Rejestratory są dostępne w witrynie DI. Należy jednak unikać tworzenia i używania filtrów wyłącznie do celów rejestrowania. Wbudowane rejestrowanie struktury zwykle zapewnia, co jest potrzebne do rejestrowania. Rejestrowanie dodane do filtrów:

• Należy skoncentrować się na problemach dotyczących domeny biznesowej lub zachowaniu specyficznym dla filtru.
• Nie należy rejestrować akcji ani innych zdarzeń struktury. Wbudowane filtry rejestrują już akcje i zdarzenia struktury.

ServiceFilterAttribute

Typy implementacji filtru usługi są rejestrowane w programie Program.cs. Element ServiceFilterAttribute pobiera wystąpienie filtru z di.

Poniższy kod przedstawia klasę LoggingResponseHeaderFilterService , która używa 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)}");
    }
}

W poniższym kodzie LoggingResponseHeaderFilterService zostanie dodany do kontenera DI:

builder.Services.AddScoped<LoggingResponseHeaderFilterService>();

W poniższym kodzie ServiceFilter atrybut pobiera wystąpienie filtru LoggingResponseHeaderFilterService z di:

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

W przypadku używania polecenia ServiceFilterAttribute, ustawienie ServiceFilterAttribute.IsReusable:

• Zawiera wskazówkę, że wystąpienie filtru może być ponownie używane poza zakresem żądania, w ramach którego został utworzony. Środowisko uruchomieniowe ASP.NET Core nie gwarantuje:
  • Zostanie utworzone pojedyncze wystąpienie filtru.
  • Filtr nie zostanie ponownie zażądany z kontenera DI w późniejszym czasie.
• Nie należy używać z filtrem, który zależy od usług z okresem istnienia innym niż pojedynczy.

ServiceFilterAttribute implementuje IFilterFactory. IFilterFactory Uwidacznia metodę CreateInstanceIFilterMetadata tworzenia wystąpienia. CreateInstance ładuje określony typ z DI.

TypeFilterAttribute

TypeFilterAttribute jest podobny do ServiceFilterAttribute, ale jego typ nie jest rozpoznawany bezpośrednio z kontenera DI. Tworzy wystąpienie typu przy użyciu polecenia Microsoft.Extensions.DependencyInjection.ObjectFactory.

Ponieważ TypeFilterAttribute typy nie są rozpoznawane bezpośrednio z kontenera DI:

• Typy, do których odwołuje się odwołanie przy użyciu TypeFilterAttribute kontenera di, nie muszą być zarejestrowane. Mają one swoje zależności spełnione przez kontener DI.
• TypeFilterAttribute opcjonalnie może akceptować argumenty konstruktora dla typu.

W przypadku używania polecenia TypeFilterAttribute, ustawienie TypeFilterAttribute.IsReusable:

• Zawiera wskazówkę, że wystąpienie filtru może być ponownie używane poza zakresem żądania, w ramach którego został utworzony. Środowisko uruchomieniowe ASP.NET Core nie gwarantuje utworzenia pojedynczego wystąpienia filtru.

• Nie należy używać z filtrem, który zależy od usług z okresem istnienia innym niż pojedynczy.

W poniższym przykładzie pokazano, jak przekazać argumenty do typu przy użyciu polecenia TypeFilterAttribute:

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

Filtry autoryzacji

Filtry autoryzacji:

• Czy pierwsze filtry są uruchamiane w potoku filtru.
• Kontrolowanie dostępu do metod akcji.
• Przed metodą, ale nie po metodzie.

Niestandardowe filtry autoryzacji wymagają niestandardowej struktury autoryzacji. Preferuj konfigurowanie zasad autoryzacji lub pisanie niestandardowych zasad autoryzacji w celu zapisania filtru niestandardowego. Wbudowany filtr autoryzacji:

• Wywołuje system autoryzacji.
• Nie autoryzuje żądań.

Nie zgłaszaj wyjątków w filtrach autoryzacji:

• Wyjątek nie zostanie obsłużony.
• Filtry wyjątków nie będą obsługiwać wyjątku.

Rozważ wystawienie wyzwania w przypadku wystąpienia wyjątku w filtrze autoryzacji.

Dowiedz się więcej o autoryzacji.

Filtry zasobów

Filtry zasobów:

• Zaimplementuj IResourceFilter interfejs lub IAsyncResourceFilter .
• Wykonanie opakowuje większość potoku filtru.
• Filtry autoryzacji są uruchamiane przed filtrami zasobów.

Filtry zasobów są przydatne w przypadku zwarć większość potoku. Na przykład filtr buforowania może uniknąć reszty potoku po trafieniu pamięci podręcznej.

Przykłady filtrów zasobów:

• Wcześniej pokazano filtr zasobów zwarciowych.

• DisableFormValueModelBindingAttribute:

  • Zapobiega uzyskiwaniu dostępu do danych formularza przez powiązanie modelu.
  • Służy do przekazywania dużych plików, aby zapobiec odczytywaniu danych formularza do pamięci.

Filtry akcji

Filtry akcji nie mają zastosowania do Razor stron. Razor Obsługa stron i IPageFilterIAsyncPageFilter. Aby uzyskać więcej informacji, zobacz Metody filtrowania dla Razor stron.

Filtry akcji:

• Zaimplementuj IActionFilter interfejs lub IAsyncActionFilter .
• Ich wykonywanie otacza wykonywanie metod akcji.

Poniższy kod przedstawia przykładowy filtr akcji:

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

Element ActionExecutingContext zawiera następujące właściwości:

• ActionArguments — umożliwia odczytywanie danych wejściowych do metody akcji.
• Controller — umożliwia manipulowanie wystąpieniem kontrolera.
• Result - ustawianie Result zwarć wykonywania metody akcji i kolejnych filtrów akcji.

Zgłaszanie wyjątku w metodzie akcji:

• Zapobiega uruchamianiu kolejnych filtrów.
• W przeciwieństwie do ustawienia Result, jest traktowany jako błąd zamiast pomyślnego wyniku.

Controller Zapewnia ActionExecutedContext i Result oraz następujące właściwości:

• Canceled — prawda, jeśli wykonanie akcji zostało zwarcie przez inny filtr.
• Exception — Wartość inna niż null, jeśli akcja lub wcześniej uruchomiony filtr akcji zwrócił wyjątek. Ustawienie tej właściwości na null:
  • Skutecznie obsługuje wyjątek.
  • Result jest wykonywany tak, jakby został zwrócony z metody akcji.

W przypadku metody IAsyncActionFilterwywołanie metody ActionExecutionDelegate:

• Wykonuje wszystkie kolejne filtry akcji i metodę akcji.
• Zwraca wartość ActionExecutedContext.

Aby zwarć, przypisz Microsoft.AspNetCore.Mvc.Filters.ActionExecutingContext.Result do wystąpienia wyników i nie wywołuje next metody ().ActionExecutionDelegate

Struktura zapewnia abstrakcję ActionFilterAttribute , która może być podklasowana.

Filtr OnActionExecuting akcji może służyć do:

• Weryfikowanie stanu modelu.
• Zwróć błąd, jeśli stan jest nieprawidłowy.

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

Uwaga

Kontrolery z adnotacjami z atrybutem [ApiController] automatycznie weryfikują stan modelu i zwracają odpowiedź 400. Aby uzyskać więcej informacji, zobacz Automatyczne odpowiedzi HTTP 400.

Metoda OnActionExecuted jest uruchamiana po metodzie akcji:

• I może wyświetlać i manipulować wynikami akcji za pośrednictwem Result właściwości .
• Canceled parametr ma wartość true, jeśli wykonanie akcji zostało zwarcie przez inny filtr.
• Exception parametr jest ustawiony na wartość inną niż null, jeśli akcja lub kolejny filtr akcji zwrócił wyjątek. Ustawienie Exception wartości null:
  • Skutecznie obsługuje wyjątek.
  • ActionExecutedContext.Result jest wykonywany tak, jakby został zwrócony normalnie z metody akcji.

Filtry wyjątków

Filtry wyjątków:

• Zaimplementuj IExceptionFilter lub IAsyncExceptionFilter.
• Może służyć do implementowania typowych zasad obsługi błędów.

Poniższy przykładowy filtr wyjątku wyświetla szczegółowe informacje o wyjątkach występujących podczas opracowywania aplikacji:

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

Poniższy kod testuje filtr wyjątku:

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

Filtry wyjątków:

• Nie mają wcześniej i po zdarzeniach.
• Zaimplementuj OnException lub OnExceptionAsync.
• Obsługa nieobsługiwanych wyjątków występujących w Razor procesie tworzenia strony lub kontrolera, powiązania modelu, filtrów akcji lub metod akcji.
• Nie przechwytuj wyjątków występujących w filtrach zasobów, filtrach wyników lub wykonywaniu wyników MVC.

Aby obsłużyć wyjątek, ustaw ExceptionHandled właściwość na true lub przypisz Result właściwość . Spowoduje to zatrzymanie propagacji wyjątku. Filtr wyjątku nie może przekształcić wyjątku w "powodzenie". Tylko filtr akcji może to zrobić.

Filtry wyjątków:

• Są dobre w przypadku podlewek wyjątków występujących w ramach akcji.
• Nie są tak elastyczne, jak oprogramowanie pośredniczące obsługujące błędy.

Preferuj oprogramowanie pośredniczące do obsługi wyjątków. Używaj filtrów wyjątków tylko wtedy, gdy obsługa błędów różni się w zależności od wywoływanej metody akcji. Na przykład aplikacja może mieć metody akcji zarówno dla punktów końcowych interfejsu API, jak i dla widoków/HTML. Punkty końcowe interfejsu API mogą zwracać informacje o błędach jako JSWŁĄCZONE, podczas gdy akcje oparte na widoku mogą zwracać stronę błędu jako kod HTML.

Filtry wyników

Filtry wyników:

• Implementowanie interfejsu:
  • IResultFilter lub IAsyncResultFilter
  • IAlwaysRunResultFilter lub IAsyncAlwaysRunResultFilter
• Ich wykonanie otacza wykonywanie wyników akcji.

IResultFilter i IAsyncResultFilter

Poniższy kod przedstawia przykładowy filtr wyników:

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

Rodzaj wykonywanego wyniku zależy od akcji. Akcja zwracająca widok obejmuje wszystkie przetwarzanie razor w ramach wykonywanego ViewResult elementu. Metoda interfejsu API może wykonać serializacji w ramach wykonywania wyniku. Dowiedz się więcej o wynikach akcji.

Filtry wyników są wykonywane tylko wtedy, gdy akcja lub filtr akcji generuje wynik akcji. Filtry wyników nie są wykonywane, gdy:

• Filtr autoryzacji lub filtr zasobów zwarcie potoku.
• Filtr wyjątku obsługuje wyjątek, generując wynik akcji.

Metoda Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuting może zwarć wykonywanie wyniku akcji i kolejnych filtrów wyników, ustawiając wartość Microsoft.AspNetCore.Mvc.Filters.ResultExecutingContext.Canceltrue. Zapisz w obiekcie odpowiedzi podczas zwarć, aby uniknąć generowania pustej odpowiedzi. Zgłaszanie wyjątku w pliku IResultFilter.OnResultExecuting:

• Zapobiega wykonywaniu wyniku akcji i kolejnych filtrów.
• Jest traktowany jako błąd zamiast pomyślnego wyniku.

Po uruchomieniu Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuted metody odpowiedź prawdopodobnie została już wysłana do klienta. Jeśli odpowiedź została już wysłana do klienta, nie można jej zmienić.

ResultExecutedContext.Canceled parametr jest ustawiony na true wartość , jeśli wykonanie wyniku akcji zostało zwarcie przez inny filtr.

ResultExecutedContext.Exception parametr jest ustawiony na wartość inną niż null, jeśli wynik akcji lub kolejny filtr wyników zwrócił wyjątek. Ustawienie Exception wartości null skutecznie obsługuje wyjątek i uniemożliwia ponowne zgłoszenie wyjątku w dalszej części potoku. Nie ma niezawodnego sposobu zapisywania danych w odpowiedzi podczas obsługi wyjątku w filtrze wyników. Jeśli nagłówki zostały opróżnione do klienta, gdy wynik akcji zgłasza wyjątek, nie ma niezawodnego mechanizmu wysyłania kodu błędu.

W przypadku elementu IAsyncResultFilterwywołanie metody await next na obiekcie ResultExecutionDelegate wykonuje wszystkie kolejne filtry wyników i wynik akcji. Aby zwarć, ustaw wartość ResultExecutingContext.Canceltrue i nie wywołaj metody 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;
        }
    }
}

Struktura zapewnia abstrakcję ResultFilterAttribute , która może być podklasowana. Pokazana wcześniej klasa ResponseHeaderAttribute jest przykładem atrybutu filtru wyników.

IAlwaysRunResultFilter i IAsyncAlwaysRunResultFilter

Interfejsy IAlwaysRunResultFilter i IAsyncAlwaysRunResultFilter deklarują implementację uruchamianą IResultFilter dla wszystkich wyników akcji. Obejmuje to wyniki akcji wygenerowane przez:

• Filtry autoryzacji i filtry zasobów, które są zwarcie.
• Filtry wyjątków.

Na przykład następujący filtr zawsze jest uruchamiany i ustawia wynik akcji (ObjectResult) z kodem stanu jednostki nieprzetworzonej 422, gdy negocjowanie zawartości kończy się niepowodzeniem:

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 W związku z tym wystąpienie może być używane jako IFilterMetadata wystąpienie w dowolnym miejscu w potoku filtru. Gdy środowisko uruchomieniowe przygotowuje się do wywołania filtru, próbuje rzutować go do elementu IFilterFactory. Jeśli rzutowanie powiedzie się, metoda jest wywoływana w CreateInstance celu utworzenia wywoływanego IFilterMetadata wystąpienia. Zapewnia to elastyczny projekt, ponieważ dokładny potok filtru nie musi być jawnie ustawiany podczas uruchamiania aplikacji.

IFilterFactory.IsReusable:

• Jest wskazówką fabryki, że wystąpienie filtru utworzone przez fabrykę może być ponownie używane poza zakresem żądania, w ramach którego został utworzony.
• Nie należy używać z filtrem, który zależy od usług z okresem istnienia innym niż pojedynczy.

Środowisko uruchomieniowe ASP.NET Core nie gwarantuje:

• Zostanie utworzone pojedyncze wystąpienie filtru.
• Filtr nie zostanie ponownie zażądany z kontenera DI w późniejszym czasie.

Ostrzeżenie

Skonfiguruj wartość tak, aby zwracać IFilterFactory.IsReusabletrue tylko wtedy, gdy źródło filtrów jest jednoznaczne, filtry są bezstanowe, a filtry są bezpieczne do użycia w wielu żądaniach HTTP. Na przykład nie zwracaj filtrów z di, które są zarejestrowane jako zakres lub przejściowe, jeśli IFilterFactory.IsReusable zwraca wartość true.

IFilterFactory można zaimplementować przy użyciu implementacji atrybutów niestandardowych jako innego podejścia do tworzenia filtrów:

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 jest stosowany w następującym kodzie:

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

IFilterFactory zaimplementowany w atrybucie

Filtry implementujące IFilterFactory są przydatne w przypadku filtrów, które:

• Nie wymagaj przekazywania parametrów.
• Mieć zależności konstruktora, które muszą być wypełnione przez di.

TypeFilterAttribute implementuje IFilterFactory. IFilterFactory Uwidacznia metodę CreateInstanceIFilterMetadata tworzenia wystąpienia. CreateInstance ładuje określony typ z kontenera usług (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)}");
        }
    }
}

Poniższy kod przedstawia trzy podejścia do zastosowania 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)}");

W poprzednim kodzie preferowane jest pierwsze podejście do zastosowania filtru.

Używanie oprogramowania pośredniczącego w potoku filtru

Filtry zasobów działają jak oprogramowanie pośredniczące, które otaczają wykonywanie wszystkich elementów, które są dostępne później w potoku. Jednak filtry różnią się od oprogramowania pośredniczącego, ponieważ są one częścią środowiska uruchomieniowego, co oznacza, że mają dostęp do kontekstu i konstrukcji.

Aby użyć oprogramowania pośredniczącego jako filtru, utwórz typ z metodą określającą Configure oprogramowanie pośredniczące do wstrzykiwania do potoku filtru. W poniższym przykładzie użyto oprogramowania pośredniczącego do ustawienia nagłówka odpowiedzi:

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

            await next();
        });
    }
}

Użyj polecenia , MiddlewareFilterAttribute aby uruchomić oprogramowanie pośredniczące:

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

Filtry oprogramowania pośredniczącego są uruchamiane na tym samym etapie potoku filtru co filtry zasobów, przed powiązaniem modelu i po pozostałej części potoku.

Bezpieczeństwo wątkowe

Podczas przekazywania wystąpienia filtru do Addelementu , a nie do Typeelementu , filtr jest pojedynczym elementem i nie jest bezpieczny wątkowo.

Dodatkowe zasoby

• Wyświetl lub pobierz przykład (jak pobrać).
• Metody filtrowania stron Razor w ASP.NET Core