Фильтры в ASP.NET Core

Авторы: Кирк Ларкин (Kirk Larkin) Рик Андерсон (Rick Anderson), Том Дайкстра (Tom Dykstra) и Стив Смит (Steve Smith)

Фильтры в ASP.NET Core позволяют выполнять код до или после определенных этапов в конвейере обработки запросов.

Встроенные фильтры обрабатывают следующие задачи:

• Авторизация, предотвращение доступа к ресурсам пользователю не разрешено.
• Кэширование ответов, короткое замыкание конвейера запроса для возврата кэшированного ответа.

Для обработки сквозной функциональности можно создавать настраиваемые фильтры. Примеры сквозной функциональности включают обработку ошибок, кэширование, конфигурирование, авторизацию и ведение журнала. Фильтры предотвращают дублирование кода. Например, можно объединить обработку ошибок с помощью фильтра исключений обработки ошибок.

Этот документ применяется к Razor страницам, контроллерам 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который выполняет метод действия.

Несколько этапов фильтра

Реализовать интерфейсы для нескольких этапов фильтра можно в одном классе. Например, класс ActionFilterAttribute реализует следующие интерфейсы:

• синхронные: IActionFilter и IResultFilter;
• асинхронные: IAsyncActionFilter и IAsyncResultFilter.
• IOrderedFilter

Реализуйте синхронный или асинхронный интерфейс фильтра, но не оба варианта. Среда выполнения сначала проверяет, реализует ли фильтр асинхронный интерфейс. Если да, вызывается именно он. В противном случае вызываются методы синхронного интерфейса. Если асинхронный и синхронный интерфейсы реализованы в одном классе, вызывается только асинхронный метод. При использовании абстрактных классов, например ActionFilterAttribute, переопределение только синхронных методов или асинхронных методов для каждого типа фильтра.

Встроенные атрибуты фильтров

ASP.NET Core включает встроенные фильтры на основе атрибутов, с помощью которых можно создавать подклассы и которые можно настраивать. Например, следующий фильтр результатов добавляет заголовок к ответу:

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

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

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

        base.OnResultExecuting(context);
    }
}

Атрибуты позволяют фильтрам принимать аргументы, как показано в примере выше. Примените ResponseHeaderAttribute к методу контроллера или действия, а затем укажите имя и значение заголовка HTTP:

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

    // ...

Проверьте заголовки с помощью инструментов разработчика для браузера. В заголовке ответа отображается filter-header: Filter Value.

Следующий код применяется ResponseHeaderAttribute как к контроллеру, так и к действию:

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

    // ...

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

Ответы из Multiple действия включают следующие заголовки:

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

Некоторые интерфейсы фильтров имеют соответствующие атрибуты, которые можно использовать как базовые классы для пользовательских реализаций.

Атрибуты фильтров:

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

Фильтры нельзя применить к Razor методам обработчика страницы. Их можно применять либо к Razor модели страницы, либо глобально.

Области и порядок выполнения фильтров

Фильтр можно добавить в конвейер в одной из трех областей:

• Использование атрибута на контроллере или Razor странице.
• С помощью атрибута в действии контроллера. Атрибуты фильтра нельзя применять к Razor методам обработчика Pages.
• Глобально для всех контроллеров, действий и Razor страниц, как показано в следующем коде:

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

Порядок выполнения по умолчанию

Если для определенного этапа конвейера имеется несколько фильтров, область определяет порядок их выполнения по умолчанию. Глобальные фильтры заключают в себя фильтры классов, которые, в свою очередь, заключают в себя фильтры методов.

В результате такого вложения последующий код фильтров выполняется в порядке, обратном выполнению предшествующего кода. Последовательность фильтров:

• Предшествующий код глобальных фильтров.
  • Предшествующий код фильтров контроллера.
    • Предшествующий код фильтров методов действий.
    • Последующий код фильтров методов действий.
  • Последующий код фильтров контроллера.
• Последующий код глобальных фильтров.

В следующем примере показано порядок выполнения методов фильтрации для синхронных фильтров действий:

Sequence	Область фильтра	Метод фильтра
1	Глобальный	OnActionExecuting
2	Контроллер	OnActionExecuting
3	Действие	OnActionExecuting
4	Действие	OnActionExecuted
5	Контроллер	OnActionExecuted
6	Глобальный	OnActionExecuted

Фильтры на уровне контроллера

Каждый контроллер, наследующий от Controller включает OnActionExecutionAsyncOnActionExecutingметоды и 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. Их нельзя настроить, чтобы они запускались после применения фильтров к методам. Свойство Order рассматривается в следующем разделе.

Сведения о Razor страницах см. в разделе "Реализация Razor фильтров страницы", переопределяя методы фильтрации.

Переопределение порядка по умолчанию

Чтобы переопределить порядок выполнения по умолчанию, можно реализовать IOrderedFilter. IOrderedFilter предоставляет свойство Order, которое имеет приоритет над областью и определяет порядок выполнения. Фильтр со значением меньше Order:

• Выполняется перед кодом, выполняемым до фильтра с более высоким значением Order.
• Выполняется после кода, выполняемого после фильтра с более высоким значением Order.

В примере фильтров уровня контроллера есть глобальные область, поэтому он выполняется до SampleActionFilterAttributeтого, GlobalSampleActionFilter как он область контроллера. Чтобы выполнить SampleActionFilterAttribute первую команду, задайте для нее значение int.MinValue:

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

Чтобы выполнить первый запуск глобального фильтра GlobalSampleActionFilter , задайте для нее значение Orderint.MinValue:

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

Отмена и сокращенное выполнение

Вы можете настроить сокращенное выполнение конвейера фильтров, задав свойство Result для параметра ResourceExecutingContext, передаваемого в метод фильтра. Например, следующий фильтр ресурсов предотвращает выполнение остальной части конвейера:

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 — фильтр действий.
• Замыкает оставшуюся часть конвейера.

Поэтому фильтр ResponseHeaderAttribute никогда не выполняется для действия Index. Поведение будет аналогичным при применении обоих фильтров на уровне метода действия при условии, что фильтр ShortCircuitingResourceFilterAttribute выполняется первым. Сначала ShortCircuitingResourceFilterAttribute выполняется из-за типа фильтра:

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

Внедрение зависимостей

Фильтры можно добавлять по типу или экземпляру. Добавляемый экземпляр используется для каждого запроса. Если добавляется тип, он является активированным. Активация фильтра означает, что:

• Экземпляр создается для каждого запроса.
• Зависимости конструктора заполняются путем внедрения зависимостей.

Фильтры, которые реализуются как атрибуты и добавляются непосредственно в классы контроллеров или методы действий, не могут иметь зависимости конструктора, предоставленные посредством внедрения зависимостей. Зависимости конструктора не могут быть предоставлены di, так как атрибуты должны иметь свои параметры конструктора, предоставленные им, где они применяются.

Следующие фильтры поддерживают зависимости конструктора, предоставленные путем внедрения зависимостей:

• ServiceFilterAttribute
• TypeFilterAttribute
• IFilterFactory реализуется в атрибуте.

Предыдущие фильтры можно применить к контроллеру или действию.

Средства ведения журнала доступны путем внедрения зависимостей. Но следует избегать создания и использования фильтров исключительно для целей ведения журнала. Встроенное средство ведения журнала обычно предоставляет все необходимое для ведения журнала. При добавлении ведения журналов в фильтры следует учитывать следующее:

• Следует сосредоточиться на бизнес-среде или поведении в привязке к фильтру.
• Не следует регистрировать действия или другие события платформы, Встроенные фильтры уже регистрируют действия и события платформы.

ServiceFilterAttribute

Типы реализации фильтра службы регистрируются в Program.cs. Атрибут ServiceFilterAttribute извлекает экземпляр фильтра из внедрения зависимостей.

В следующем коде LoggingResponseHeaderFilterService показан класс, который использует 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)}");
    }
}

В следующем коде в контейнер внедрения зависимостей добавляется LoggingResponseHeaderFilterService:

builder.Services.AddScoped<LoggingResponseHeaderFilterService>();

В следующем коде атрибут ServiceFilter извлекает экземпляр фильтра LoggingResponseHeaderFilterService из внедрения зависимостей:

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

При использовании ServiceFilterAttribute, параметр ServiceFilterAttribute.IsReusable:

• Указывает, что экземпляр фильтра можно многократно использовать за пределами области запроса, в которой он был создан. Среда выполнения ASP.NET Core не гарантирует:
  • что будет создан хотя бы один экземпляр фильтра;
  • что фильтр не будет повторно запрошен из контейнера внедрения зависимостей на более позднем этапе.
• Не следует использовать с фильтром, который зависит от служб с временем существования, отличного от одноэлементного.

ServiceFilterAttribute реализует IFilterFactory. IFilterFactory предоставляет метод CreateInstance для создания экземпляра IFilterMetadata. CreateInstance загружает указанный тип из внедрения зависимостей.

TypeFilterAttribute

Атрибут TypeFilterAttribute похож на ServiceFilterAttribute, но его тип не разрешается напрямую из контейнера внедрения зависимостей. Он создает экземпляр типа с помощью Microsoft.Extensions.DependencyInjection.ObjectFactory.

Так как типы TypeFilterAttribute не разрешаются напрямую из контейнера внедрения зависимостей:

• Типы, на которые ссылаются с помощью TypeFilterAttribute, не нужно регистрировать в контейнере внедрения зависимостей. Их зависимости выполняются самим контейнером.
• Атрибут TypeFilterAttribute может также принимать аргументы конструктора для типа.

При использовании TypeFilterAttribute, параметр TypeFilterAttribute.IsReusable:

• Указывает, что экземпляр фильтра можно многократно использовать за пределами области запроса, в которой он был создан. Среда выполнения ASP.NET Core не предоставляет никаких гарантий, что будет создан хотя бы один экземпляр фильтра.

• Не следует использовать с фильтром, который зависит от служб со временем существования, кроме элементов singleton.

В следующем примере показано, как передавать аргументы в тип с помощью TypeFilterAttribute:

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

Фильтры авторизации

Фильтры авторизации:

• Выполняются в первую очередь в конвейере фильтров.
• Контролируют доступ к методам действий.
• Имеют предшествующий, но не последующий метод.

Для работы пользовательских фильтров авторизации требуется настраиваемая платформа авторизации. Настройка политик авторизации или определение пользовательской политики авторизации предпочтительнее создания пользовательского фильтра. Встроенный фильтр авторизации:

• Вызывает систему авторизации.
• Не выполняет авторизацию запросов.

Не вызывайте исключения в фильтрах авторизации:

• Исключение не будет обработано.
• Фильтры исключений не будут обрабатывать исключение.

При возникновении исключения в фильтре авторизации попробуйте создать запрос.

Дополнительные сведения об авторизации.

Фильтры ресурсов

Фильтры ресурсов:

• Реализуют либо интерфейс IResourceFilter, либо интерфейс IAsyncResourceFilter.
• Выполнение охватывает большую часть конвейера фильтров.
• До фильтров ресурсов применяются только фильтры авторизации.

Фильтры ресурсов полезны для сокращенного выполнения большей части конвейера. Например, фильтр кэширования предотвращает выполнение остальной части конвейера при попадании в кэше.

Примеры фильтров ресурсов:

• Сокращенное выполнение фильтра ресурсов показано ранее.

• DisableFormValueModelBindingAttribute:

  • Предотвращает доступ привязки модели к данным формы.
  • Используется для загрузки больших файлов, если необходимо предотвратить считывание данных формы в память.

Фильтры действий

Фильтры действий не применяются к Razor Страницам. Razor Страницы поддерживают 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:
  • Будет эффективно обрабатываться исключение.
  • Result будет выполняться так, как при возвращении методом действия.

Для IAsyncActionFilter вызов ActionExecutionDelegate:

• Приводит к выполнению последующих фильтров действий и метода действия.
• Возвращает ActionExecutedContext.

Для сокращенного выполнения присвойте Microsoft.AspNetCore.Mvc.Filters.ActionExecutingContext.Result экземпляру результата и не вызывайте next (ActionExecutionDelegate).

Платформа предоставляет абстрактный класс ActionFilterAttribute, для которого можно создавать подклассы.

Фильтр действий OnActionExecuting можно использовать:

• Для проверки состояния модели.
• Для получения ошибки, если состояние является недопустимым.

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

Примечание.

Контроллеры, помеченные [ApiController] атрибутом, автоматически проверяют состояние модели и возвращают ответ 400. Дополнительные сведения см. в разделе Автоматические отклики HTTP 400.

Метод OnActionExecuted выполняется после метода действия:

• Он имеет доступ к результатам действия и может управлять ими с помощью свойства Result.
• Canceled будет иметь значение true, если выполнение действия было сокращено другим фильтром.
• Exception будет иметь ненулевое значение, если действие или последующий фильтр действий вызвали исключение. Значение Exception NULL:
  • Будет эффективно обрабатываться исключение.
  • ActionExecutedContext.Result будет выполняться так, как если бы метод действия вернул его обычным образом.

Фильтры исключений

Фильтры исключений:

• Реализуют IExceptionFilter или IAsyncExceptionFilter.
• Можно использовать для реализации политик обработки стандартных ошибок.

В следующем примере фильтра исключений отображаются сведения об исключениях, возникающих при разработке приложения:

public class SampleExceptionFilter : IExceptionFilter
{
    private readonly IHostEnvironment _hostEnvironment;

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

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

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

В следующем коде проверяется фильтр исключений:

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

Фильтры исключений:

• Не имеют предшествующих и последующих событий.
• Реализуют OnException или OnExceptionAsync.
• Обработка необработанных исключений, возникающих при Razor создании страницы или контроллера, привязке модели, фильтрах действий или методах действий.
• Не перехватывают исключения, которые возникают в фильтрах ресурсов, фильтрах результатов или при выполнении результата 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.
    }
}

Тип выполняемого результата зависит от соответствующего действия. Действие, возвращающее представление, включает всю обработку Razor в рамках выполняемого объекта ViewResult. В процессе выполнения результата метод 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 будет иметь ненулевое значение, если результат действия или последующий фильтр результатов вызвали исключение. Присвоение Exception значения NULL приводит к обработке исключения и предотвращает его последующий вызов на дальнейших этапах конвейера. Надежный способ записи данных в ответ при обработке исключения в фильтре результатов отсутствует. Если результат действия вызывает исключение в процессе выполнения и заголовки уже были переданы в клиент, надежного механизма отправки кода сбоя не существует.

Для IAsyncResultFilter вызов к await next для ResultExecutionDelegate приводит к выполнению последующих фильтров результатов и результата действия. Чтобы получить короткий канал, установите ResultExecutingContext.Cancel значение true и не вызывайте следующую ResultExecutionDelegateкоманду:

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

Платформа предоставляет абстрактный класс ResultFilterAttribute, для которого можно создавать подклассы. Класс ResponseHeaderAttribute , показанный ранее, является примером атрибута фильтра результатов.

IAlwaysRunResultFilter и IAsyncAlwaysRunResultFilter

Интерфейсы IAlwaysRunResultFilter и IAsyncAlwaysRunResultFilter объявляют реализацию IResultFilter, которая выполняется для всех результатов действий. Сюда включены результаты действий, созданные:

• фильтрами авторизации и фильтрами ресурсов, которые сокращают ответ;
• фильтрами исключений.

Например, следующий фильтр всегда выполняется, задавая результат действия (ObjectResult) с кодом состояния 422 Unprocessable Entity при сбое согласования содержимого:

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

    public void OnResultExecuted(ResultExecutedContext context) { }
}

IFilterFactory

IFilterFactory реализует IFilterMetadata. Поэтому экземпляр IFilterFactory можно использовать в качестве экземпляра IFilterMetadata в любом месте конвейера фильтров. Когда среда выполнения готовится вызвать фильтр, она пытается привести его к IFilterFactory. Если приведение проходит успешно, вызывается метод CreateInstance для создания вызываемого экземпляра IFilterMetadata. Это обеспечивает высокую степень гибкости, так как при запуске приложения нет необходимости в явном и точном определении конвейера фильтров.

IFilterFactory.IsReusable:

• Указание фабрики о том, что экземпляр фильтра, созданный фабрикой, может повторно использоваться за пределами запроса, область он был создан внутри.
• Не следует использовать с фильтром, который зависит от служб с временем существования, отличного от одноэлементного.

Среда выполнения ASP.NET Core не гарантирует:

• что будет создан хотя бы один экземпляр фильтра;
• что фильтр не будет повторно запрошен из контейнера внедрения зависимостей на более позднем этапе.

Предупреждение

Только настроить IFilterFactory.IsReusable возврат, true если источник фильтров является однозначной, фильтры без отслеживания состояния, а фильтры безопасны для нескольких HTTP-запросов. Например, не возвращайте фильтры из di, зарегистрированные как область или временные, если IFilterFactory.IsReusable возвращаетсяtrue.

Еще один подход к созданию фильтров заключается в реализации 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, используются для фильтров, которые:

• Не требуют передачи параметров.
• Содержат зависимости конструктора, которые должны заполняться путем внедрения зависимостей.

TypeFilterAttribute реализует IFilterFactory. IFilterFactory предоставляет метод CreateInstance для создания экземпляра IFilterMetadata. CreateInstance загружает указанный тип из контейнера служб (внедрение зависимостей).

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

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

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

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

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

В следующем коде показаны три подхода к применению фильтра:

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

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

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

В приведенном выше коде первый подход к применению фильтра предпочтителен.

Использование ПО промежуточного слоя в конвейере фильтра

Фильтры ресурсов по принципу работы похожи на ПО промежуточного слоя тем, что они заключают в себя выполнение всех объектов, находящихся далее в конвейере. Однако фильтры отличаются от ПО промежуточного слоя тем, что они являются частью среды выполнения, а значит имеют доступ к контексту и конструкциям.

Чтобы использовать ПО промежуточного слоя в качестве фильтра, создайте тип с методом Configure, определяющим ПО промежуточного слоя, которое нужно внедрить в конвейер фильтров. В следующем примере используется ПО промежуточного слоя для задания заголовка ответа:

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

            await next();
        });
    }
}

Используйте MiddlewareFilterAttribute для выполнения ПО промежуточного слоя:

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

Фильтры ПО промежуточного слоя выполняются на том же этапе конвейера фильтров, что и фильтры ресурсов, перед привязкой модели и после остальной части конвейера.

Потокобезопасность

При передаче экземпляра фильтра Addв , а не его Type, фильтр является одним и не является потокобезопасным.

Дополнительные ресурсы

• Просмотреть или скачать пример (как скачивать).
• Методы фильтрации для Razor Pages в ASP.NET Core