Filtri in core di ASP.NET

Di Kirk Larkin, Rick Anderson, Tom Dykstra e Steve Smith

I filtri in ASP.NET Core consentono l'esecuzione del codice prima o dopo fasi specifiche nella pipeline di elaborazione delle richieste.

I filtri predefiniti gestiscono attività, ad esempio:

• Autorizzazione, che impedisce l'accesso alle risorse per cui un utente non è autorizzato.
• Memorizzazione nella cache delle risposte, interrompendo il flusso delle richieste per restituire una risposta memorizzata nella cache.

I filtri personalizzati possono essere creati per gestire problemi relativi a più settori. Esempi di problematiche trasversali includono la gestione degli errori, la memorizzazione nella cache, la configurazione, l'autorizzazione e la registrazione. I filtri evitano la duplicazione del codice. Ad esempio, un filtro eccezioni per la gestione degli errori potrebbe consolidare la gestione degli errori.

Questo documento si applica a Razor Pagine, controller API e controller con visualizzazioni. I filtri non funzionano direttamente con i Razor componenti. Un filtro può influire indirettamente su un componente quando:

• Il componente è incorporato in una pagina o in una visualizzazione.
• La pagina o il controller e la visualizzazione usano il filtro.

Funzionamento dei filtri

I filtri vengono eseguiti all'interno della pipeline di chiamata di azioni ASP.NET Core, talvolta definita pipeline di filtro. La pipeline di filtro viene eseguita dopo ASP.NET Core seleziona l'azione da eseguire:

Tipi di filtri

Ogni tipo di filtro viene eseguito in una fase diversa della pipeline di filtro:

• Filtri autorizzazione:

  • Corri prima.
  • Determinare se l'utente è autorizzato per la richiesta.
  • Interrompi il flusso della pipeline se la richiesta non è autorizzata.

• Filtri di risorse:

  • Esegui dopo l'autorizzazione.
  • OnResourceExecuting esegue il codice prima del resto della pipeline di filtraggio. Ad esempio, OnResourceExecuting esegue il codice prima dell'associazione di modelli.
  • OnResourceExecuted esegue il codice software dopo che il resto della pipeline è stato completato.

• Filtri azione:

  • Eseguito immediatamente prima e dopo l'invocazione di un metodo di azione.
  • Può modificare gli argomenti passati in un'azione.
  • Può modificare il risultato restituito dall'azione.
  • Non sono supportati in Razor Pages.

• Filtri degli endpoint:

  • Eseguito immediatamente prima e dopo che viene chiamato un metodo d'azione.
  • Può modificare gli argomenti passati in un'azione.
  • Può modificare il risultato restituito dall'azione.
  • Non sono supportati in Razor Pages.
  • Può essere richiamato su entrambe le azioni e sugli endpoint basati sul gestore di route.

• I filtri delle eccezioni applicano criteri globali alle eccezioni non gestite che si verificano prima che il corpo della risposta sia stato scritto.

• Filtri dei risultati:

  • Eseguire immediatamente prima e dopo l'esecuzione dei risultati dell'azione.
  • Eseguire solo quando il metodo di azione viene eseguito correttamente.
  • Sono utili per la logica che deve racchiudere l'esecuzione della visualizzazione o del formattatore.

Il diagramma seguente mostra come interagiscono i tipi di filtro nella pipeline di filtro:

Razor Le pagine supportano Razor anche i filtri pagina, che vengono eseguiti prima e dopo un Razor gestore di pagine.

Implementazione

I filtri supportano sia implementazioni sincrone che asincrone tramite definizioni di interfaccia diverse.

I filtri sincroni vengono eseguiti sia prima che dopo la loro fase nella pipeline. La chiamata di OnActionExecuting, ad esempio, avviene prima della chiamata del metodo di azione. OnActionExecuted viene chiamato dopo che il metodo di azione restituisce:

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

I filtri asincroni definiscono un On-Stage-ExecutionAsync metodo. Ad esempio, 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.
    }
}

Nel codice precedente, l'oggetto SampleAsyncActionFilter ha un ActionExecutionDelegate, next, che esegue il metodo dell'azione.

Fasi di filtro multiple

È possibile implementare interfacce per più fasi di filtro in una singola classe. Ad esempio, la ActionFilterAttribute classe implementa:

• Sincrono: IActionFilter e IResultFilter
• Asincrono: IAsyncActionFilter e IAsyncResultFilter
• IOrderedFilter

Implementare la versione sincrona oppure la versione asincrona di un'interfaccia di filtro, non entrambe. Il runtime controlla per prima cosa se il filtro implementa l'interfaccia asincrona e, in tal caso, la chiama. In caso contrario, chiama i metodi dell'interfaccia sincrona. Se in una classe sono implementate entrambe le interfacce, sincrona e asincrona, viene chiamato solo il metodo asincrono. Quando si usano classi astratte come ActionFilterAttribute, eseguire l'override solo dei metodi sincroni o dei metodi asincroni per ogni tipo di filtro.

Attributi filtro predefiniti

ASP.NET Core include filtri predefiniti basati su attributi che è possibile impostare come sottoclasse e personalizzare. Il filtro dei risultati seguente, ad esempio, aggiunge un'intestazione alla risposta:

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

Gli attributi consentono ai filtri di accettare argomenti, come illustrato nell'esempio precedente. Applicare ResponseHeaderAttribute a un controller o a un metodo di azione e specificare il nome e il valore dell'intestazione HTTP:

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

    // ...

Usare uno strumento come gli strumenti di sviluppo del browser per esaminare le intestazioni. Nelle Intestazioni di risposta, filter-header: Filter Value viene visualizzato.

Il codice seguente si applica ResponseHeaderAttribute sia a un controller che a un'azione:

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

Le risposte dell'azione Multiple includono le intestazioni seguenti:

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

Molte delle interfacce del filtro presentano attributi corrispondenti che possono essere usati come classi di base per implementazioni personalizzate.

Attributi dei filtri:

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

I filtri non possono essere applicati ai Razor metodi del gestore Page. Possono essere applicati al Razor modello Page o a livello globale.

Ambiti dei filtri e ordine di esecuzione

È possibile aggiungere un filtro alla pipeline in uno dei tre ambiti:

• Uso di un attributo in un controller o Razor in una pagina.
• Uso di un attributo in un'azione del controller. Gli attributi di filtro non possono essere applicati ai Razor metodi del gestore Pages.
• A livello globale per tutti i controller, le azioni e le Razor pagine, come mostrato nel codice seguente:

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

Ordine di esecuzione predefinito

Quando sono presenti più filtri per una particolare fase della pipeline, l'ambito determina l'ordine di esecuzione predefinito dei filtri. I filtri globali racchiudono i filtri di classe, che a loro volta racchiudono i filtri dei metodi.

Come risultato dell'annidamento dei filtri, il codice after dei filtri viene eseguito in ordine inverso rispetto al codice before. Sequenza di filtro:

• Codice before dei filtri globali.
  • Codice before dei filtri del controller.
    • Codice before dei filtri del metodo di azione.
    • Codice after dei filtri del metodo di azione.
  • Codice after dei filtri del controller.
• Codice after dei filtri globali.

Nell'esempio seguente viene illustrato l'ordine in cui vengono eseguiti i metodi di filtro per i filtri di azione sincroni:

Sequenza	Ambito del filtro	Metodo di filtraggio
1	Generale	OnActionExecuting
2	Controller	OnActionExecuting
3	Azione	OnActionExecuting
4	Azione	OnActionExecuted
5	Controller	OnActionExecuted
6	Generale	OnActionExecuted

Filtri a livello di controller

Ogni controller che eredita da Controller include i metodi OnActionExecuting, OnActionExecutionAsync e OnActionExecuted. Questi metodi incapsulano i filtri eseguiti per una determinata azione.

• OnActionExecuting viene eseguito prima di tutti i filtri dell'azione.
• OnActionExecuted viene eseguito dopo tutti i filtri dell'azione.
• OnActionExecutionAsync viene eseguito prima di qualsiasi filtro dell'azione. Il codice dopo una chiamata a next viene eseguito dopo i filtri dell'azione.

La classe seguente ControllerFiltersController :

• Applica l'oggetto SampleActionFilterAttribute ([SampleActionFilter]) al controller.
• Esegue l'override di OnActionExecuting e 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.");
    }
}

Passando a https://localhost:<port>/ControllerFilters, viene eseguito il codice seguente:

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

I filtri a livello di controller impostano la proprietà Order su int.MinValue. Non è possibile impostare filtri a livello di controller per l'esecuzione dopo l'applicazione dei filtri ai metodi. L'ordine è illustrato nella sezione successiva.

Per Razor le pagine, vedere Implementare Razor filtri di pagina eseguendo l'override dei metodi di filtro.

Eseguire l'override dell'ordine predefinito

È possibile eseguire l'override della sequenza di esecuzione predefinita implementando IOrderedFilter. IOrderedFilter espone la proprietà Order, che ha la precedenza sull'ambito per determinare l'ordine di esecuzione. Un filtro con un valore di Order inferiore:

• Esegue il codice before prima di quello di un filtro con un valore di Order più alto.
• Esegue il codice after successivamente a quello di un filtro con un valore Order più alto.

Nell'esempio di filtri a livello di controller, GlobalSampleActionFilter ha un ambito globale, quindi viene eseguito prima di SampleActionFilterAttribute, che ha ambito controller. Per eseguire SampleActionFilterAttribute come primo, imposta il suo ordine a int.MinValue:

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

Per fare in modo che il filtro GlobalSampleActionFilter globale sia eseguito per primo, impostarlo Order su int.MinValue:

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

Annullamento e cortocircuito

È possibile causare il corto circuito della pipeline di filtro impostando la proprietà Result sul parametro ResourceExecutingContext fornito al metodo di filtro. Ad esempio, il filtro risorsa seguente impedisce l'esecuzione del resto della pipeline:

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

    public void OnResourceExecuted(ResourceExecutedContext context) { }
}

Nel codice seguente sia il filtro [ShortCircuitingResourceFilter] che il filtro [ResponseHeader] hanno come destinazione il metodo di azione Index. Filtro ShortCircuitingResourceFilterAttribute :

• Viene eseguito per primo perché è un filtro risorsa e ResponseHeaderAttribute è un filtro azione.
• Cortocircuita il resto della pipeline.

Pertanto il filtro ResponseHeaderAttribute non viene mai eseguito per l'azione Index. Questo comportamento sarebbe lo stesso se entrambi i filtri venissero applicati a livello di metodo di azione, a condizione che il filtro ShortCircuitingResourceFilterAttribute venga eseguito prima. ShortCircuitingResourceFilterAttribute viene eseguito per primo a causa del suo tipo di filtro.

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

Iniezione delle dipendenze

È possibile aggiungere filtri per tipo o per istanza. Se viene aggiunta un'istanza, tale istanza viene usata per ogni richiesta. Se viene aggiunto un tipo, esso viene attivato. Un filtro attivato in base al tipo significa:

• Viene creata un'istanza per ogni richiesta.
• Le dipendenze del costruttore sono popolate tramite iniezione delle dipendenze (DI).

I filtri implementati come attributi e aggiunti direttamente alle classi controller o ai metodi di azione non possono avere dipendenze del costruttore specificate dall'inserimento di dipendenze. Le dipendenze del costruttore non possono essere fornite dall'inserimento delle dipendenze dal costruttore perché gli attributi devono avere i parametri del costruttore specificati dove vengono applicati.

I seguenti filtri supportano le dipendenze del costruttore fornite dal dependency injection:

• ServiceFilterAttribute
• TypeFilterAttribute
• IFilterFactory implementato nell'attributo.

I filtri precedenti possono essere applicati a un controller o a un'azione.

I logger sono disponibili tramite l'Iniezione di Dipendenze. Evitare tuttavia di creare e usare filtri esclusivamente per scopi di registrazione. La funzionalità di registrazione del framework predefinita in genere fornisce il necessario per la registrazione. È stato aggiunto il registro ai filtri:

• Deve concentrarsi su aspetti del dominio aziendale o comportamenti specifici del filtro.
• Non dovrebbe registrare azioni o altri eventi del framework. I filtri predefiniti registrano già azioni ed eventi del framework.

ServiceFilterAttribute

I tipi di implementazione del filtro di servizi sono registrati in Program.cs. ServiceFilterAttribute recupera un'istanza del filtro dall'inserimento di dipendenze.

Il codice seguente mostra la classe LoggingResponseHeaderFilterService, che utilizza l'iniezione delle dipendenze.

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

Nel codice seguente l'oggetto LoggingResponseHeaderFilterService viene aggiunto al contenitore di inserimento delle dipendenze:

builder.Services.AddScoped<LoggingResponseHeaderFilterService>();

Nel codice seguente l'attributo ServiceFilter recupera un'istanza del filtro LoggingResponseHeaderFilterService dall'inserimento delle dipendenze:

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

Quando si usa ServiceFilterAttribute e si imposta ServiceFilterAttribute.IsReusable:

• Indica che l'istanza del filtro può essere riutilizzata all'esterno dell'ambito della richiesta in cui è stata creata. Il runtime di ASP.NET Core non garantisce:
  • Che venga creata una singola istanza del filtro.
  • Il filtro non verrà richiesto di nuovo dal contenitore DI in un momento successivo.
• Non dovrebbe essere utilizzato con un filtro che si basa su servizi con un ciclo di vita diverso da singleton.

ServiceFilterAttribute implementa IFilterFactory. IFilterFactory espone il metodo CreateInstance per creare un'istanza IFilterMetadata. CreateInstance carica il tipo specificato dall'inserimento delle dipendenze.

TypeFilterAttribute

TypeFilterAttribute è simile a ServiceFilterAttribute, ma il relativo tipo non viene risolto direttamente dal contenitore dell'inserimento di dipendenze. Viene creata un'istanza del tipo tramite Microsoft.Extensions.DependencyInjection.ObjectFactory.

Poiché i tipi TypeFilterAttribute non vengono risolti direttamente dal contenitore DI:

• Non è necessario registrare nel contenitore DI i tipi a cui viene fatto riferimento tramite TypeFilterAttribute. Le loro dipendenze vengono soddisfatte dal contenitore di inserimento delle dipendenze.
• In via facoltativa, TypeFilterAttribute può anche accettare gli argomenti del costruttore per il tipo.

Quando si usa TypeFilterAttribute, impostando TypeFilterAttribute.IsReusable:

• Indica che l'istanza del filtro può essere riutilizzata all'esterno dell'ambito della richiesta in cui è stata creata. Il runtime di ASP.NET Core non fornisce alcuna garanzia che venga creata una singola istanza del filtro.

• Non si deve usare con un filtro che dipende da servizi con una durata diversa da singleton.

L'esempio seguente illustra come passare argomenti a un tipo usando TypeFilterAttribute:

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

Filtri autorizzazione

I filtri di autorizzazione:

• Sono i primi filtri a essere eseguiti nella pipeline di filtro.
• Controlla l'accesso ai metodi di azione.
• Dispongono di un metodo precedente, ma non di un metodo successivo.

I filtri di autorizzazione personalizzati richiedono un framework di autorizzazione personalizzato. È preferibile configurare criteri di autorizzazione o scrivere criteri di autorizzazione personalizzati piuttosto che scrivere un filtro personalizzato. Il filtro di autorizzazione predefinito:

• Chiama il sistema di autorizzazione.
• Non autorizza le richieste.

Non generare eccezioni nei filtri di autorizzazione:

• L'eccezione non verrà gestita.
• I filtri di eccezione non gestiranno l'eccezione.

È consigliabile emettere una richiesta di verifica in caso di eccezione in un filtro di autorizzazione.

Altre informazioni sull'autorizzazione.

Filtri risorse

I filtri di risorse:

• Implementano l'interfaccia IResourceFilter o IAsyncResourceFilter.
• L'esecuzione avvolge la maggior parte della pipeline di filtro.
• Solo i filtri di autorizzazione vengono eseguiti prima dei filtri di risorse.

I filtri di risorse sono utili per aggirare gran parte della pipeline. Ad esempio, un filtro di memorizzazione nella cache può evitare il resto della pipeline nel caso di un hit della cache.

Esempi di filtri di risorse:

• Il filtro di risorse di corto circuito illustrato in precedenza.

• DisableFormValueModelBindingAttribute:

  • Impedisce all'associazione di modelli di accedere ai dati del modulo.
  • Viene usato quando si caricano file di grandi dimensioni per impedire la lettura dei dati del modulo in memoria.

Filtri di azione

I filtri di azione non si applicano alle Razor Pagine. Razor Pages supporta IPageFilter e IAsyncPageFilter. Per altre informazioni, vedere Metodi di filtro per Razor Pagine.

I filtri di azione:

• Implementano l'interfaccia IActionFilter o IAsyncActionFilter.
• La loro esecuzione accompagna l'esecuzione dei metodi di azione.

Il codice seguente mostra un filtro di azione di esempio:

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

La classe ActionExecutingContext specifica le proprietà seguenti:

• ActionArguments : consente di leggere gli input in un metodo di azione.
• Controller: consente di modificare l'istanza del controller.
• Result: l'impostazione di Result causa il corto circuito del metodo di azione e dei filtri di azione successivi.

Generare un'eccezione in un metodo di azione:

• Impedisce l'esecuzione dei filtri successivi.
• A differenza dell'impostazione di Result, è considerata un errore anziché un risultato positivo.

La classe ActionExecutedContext specifica Controller e Result oltre alle proprietà seguenti:

• Canceled: True se l'esecuzione dell'azione è stata interrotta da un altro filtro.
• Exception - Non nullo se l'azione o un filtro di azione eseguito in precedenza ha generato un'eccezione. Impostazione di questa proprietà su null:
  • L'eccezione viene gestita in modo efficace.
  • L'oggetto Result viene eseguito come se fosse stato restituito dal metodo di azione.

Per un oggetto IAsyncActionFilter, una chiamata a ActionExecutionDelegate:

• Esegue qualsiasi filtro d'azione successivo e il metodo d'azione.
• Restituisce ActionExecutedContext.

Per eseguire un cortocircuito, assegnare Microsoft.AspNetCore.Mvc.Filters.ActionExecutingContext.Result a un'istanza di risultato e non chiamare next (ActionExecutionDelegate).

Il framework fornisce un oggetto ActionFilterAttribute astratto che è possibile impostare come sottoclasse.

Il filtro di azione OnActionExecuting può essere usato per:

• Convalidare lo stato del modello.
• Restituire un errore se lo stato non è valido.

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

Nota

I controller annotati con l'attributo convalidano automaticamente lo stato del [ApiController] modello e restituiscono una risposta 400. Per altre informazioni, vedere Risposte HTTP 400 automatiche.

Il metodo OnActionExecuted viene eseguito dopo il metodo di azione:

• È possibile visualizzare e modificare i risultati dell'azione tramite la proprietà Result.
• L'impostazione di Canceled è true se un altro filtro ha causato l'interruzione dell'esecuzione dell'azione.
• L'impostazione di Exception è un valore diverso da nullo se l'azione o un filtro azione successivo ha generato un'eccezione. Impostazione di Exception su null:
  • Gestisce un'eccezione in modo efficace.
  • L'oggetto ActionExecutedContext.Result viene eseguito come se fosse stato restituito normalmente dal metodo di azione.

Filtri eccezioni

I filtri delle eccezioni:

• Implementa IExceptionFilter o IAsyncExceptionFilter.
• Possono essere usati per implementare criteri di gestione degli errori comuni.

Il filtro eccezioni di esempio seguente mostra i dettagli sulle eccezioni che si verificano quando l'app è in fase di sviluppo:

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

Il codice seguente verifica il filtro delle eccezioni:

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

Filtri per eccezioni

• Non ci sono eventi prima o dopo.
• Implementa OnException o OnExceptionAsync.
• Gestire le eccezioni non gestite che si verificano nella creazione di pagine o controller,Razor nell'associazione di modelli, nei filtri di azione o nei metodi di azione.
• Non intercettare le eccezioni che si verificano nei filtri di risorse, nei filtri dei risultati o nell'esecuzione dei risultati MVC.

Per gestire un'eccezione, impostare la ExceptionHandled proprietà su true o assegnare la Result proprietà . In questo modo si arresta la propagazione dell'eccezione. Un filtro di eccezione non può modificare un'eccezione in una "operazione riuscita". Questa operazione può essere eseguita solo tramite un filtro di azione.

Filtri per eccezioni:

• Sono ideali per intercettare le eccezioni che si verificano nelle azioni.
• Non sono flessibili quanto il middleware di gestione degli errori.

Scegliere il middleware per la gestione delle eccezioni. Usare i filtri di eccezione solo quando la gestione degli errori varia in base al metodo di azione chiamato. Un'app può ad esempio avere metodi di azione sia per gli endpoint API che per le visualizzazioni/HTML. Gli endpoint dell'API possono restituire informazioni sull'errore come JSON, mentre le azioni basate sulla visualizzazione possono restituire una pagina di errore in formato HTML.

I filtri del risultato

I filtri dei risultati:

• Implementare un'interfaccia:
  • IResultFilter oppure IAsyncResultFilter
  • IAlwaysRunResultFilter oppure IAsyncAlwaysRunResultFilter
• La loro esecuzione riguarda l'attuazione dei risultati delle azioni.

IResultFilter e IAsyncResultFilter

Il codice seguente mostra un filtro dei risultati di esempio:

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

Il tipo di risultato eseguito dipende dall'azione. Un'azione che restituisce una visualizzazione include tutta l'elaborazione Razor come parte dell'esecuzione di ViewResult. Un metodo API può eseguire la serializzazione in quanto parte dell'esecuzione del risultato. Altre informazioni sui risultati delle azioni.

I filtri dei risultati vengono eseguiti solo quando un'azione o un filtro azione produce un risultato dell'azione. I filtri dei risultati non vengono eseguiti quando:

• Un filtro di autorizzazione o un filtro di risorse cortocircuita la pipeline.
• Un filtro di eccezione gestisce un'eccezione producendo un risultato di un'azione.

Il metodo Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuting può causare il corto circuito dell'esecuzione del risultato dell'azione e dei filtri dei risultati successivi se si imposta Microsoft.AspNetCore.Mvc.Filters.ResultExecutingContext.Cancel su true. In caso di corto circuito, scrivere nell'oggetto risposta per evitare di generare una risposta vuota. Lancio di un'eccezione in IResultFilter.OnResultExecuting:

• Impedisce l'esecuzione del risultato dell'azione e dei filtri successivi.
• Viene considerato come un errore anziché come risultato positivo.

Quando il Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuted metodo viene eseguito, è probabile che la risposta sia già stata inviata al client. Se la risposta è già stata inviata al client, non può essere modificata.

ResultExecutedContext.Canceled è impostato su true se l'esecuzione del risultato dell'azione è stata interrotta da un altro filtro.

ResultExecutedContext.Exception è impostato su un valore non nullo se il risultato dell'azione o un filtro dei risultati successivo ha generato un'eccezione. L'impostazione su Exception Null gestisce in modo efficace un'eccezione e impedisce che l'eccezione venga generata nuovamente più avanti nella pipeline. Non c'è alcun modo affidabile per scrivere i dati in una risposta quando si gestisce un'eccezione in un filtro dei risultati. Se le intestazioni sono state scaricate nel client quando il risultato di un'azione genera un'eccezione, non c'è alcun meccanismo affidabile per inviare un codice di errore.

Per un oggetto IAsyncResultFilter, una chiamata a await next in ResultExecutionDelegate esegue tutti i filtri dei risultati successivi e il risultato dell'azione. Per creare un corto circuito, impostare ResultExecutingContext.Cancel su true e non chiamare 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;
        }
    }
}

Il framework fornisce un oggetto ResultFilterAttribute astratto che è possibile impostare come sottoclasse. La classe ResponseHeaderAttribute illustrata in precedenza è un esempio di attributo di filtro dei risultati.

IAlwaysRunResultFilter e IAsyncAlwaysRunResultFilter

Le interfacce IAlwaysRunResultFilter e IAsyncAlwaysRunResultFilter dichiarano un'implementazione di IResultFilter eseguita per tutti i risultati dell'azione. Sono inclusi i risultati dell'azione prodotti da:

• Filtri di autorizzazione e filtri delle risorse che causano un corto circuito.
• Filtri delle eccezioni.

Ad esempio, il filtro seguente viene eseguito sempre e imposta un risultato dell'azione (ObjectResult) con un codice di stato 422 Entità non elaborabile quando la negoziazione del contenuto ha esito negativo:

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 implementa IFilterMetadata. Pertanto, un'istanza di IFilterFactory può essere usata come un'istanza di IFilterMetadata in un punto qualsiasi della pipeline filtro. Quando il runtime si prepara per richiamare il filtro, cerca di eseguirne il cast a un oggetto IFilterFactory. Se l'esecuzione del cast ha esito positivo, viene chiamato il metodo CreateInstance per creare l'istanza di IFilterMetadata richiamata. Questo fornisce un design flessibile, poiché non è necessario impostare in modo esplicito la pipeline di filtro all'avvio dell'app.

IFilterFactory.IsReusable:

• È un suggerimento dal factory che l'istanza del filtro creata dal factory può essere riutilizzata al di fuori dell'ambito di richiesta in cui è stata creata.
• Non dovrebbe essere utilizzato con un filtro che dipende da servizi con una durata diversa da singleton.

Il runtime di ASP.NET Core non garantisce:

• Che venga creata una singola istanza del filtro.
• Il filtro non verrà richiesto nuovamente dal contenitore delle dipendenze in un momento successivo.

Avviso

Configurare IFilterFactory.IsReusable per restituire true solo se l'origine dei filtri è chiara, i filtri sono senza stato e sono sicuri da usare in diverse richieste HTTP. Ad esempio, non restituire filtri dall'inserimento di dipendenze registrati come ambito o temporanei se IFilterFactory.IsReusable restituisce true.

Un altro approccio alla creazione di filtri consiste nell'implementare IFilterFactory usando implementazioni dell'attributo personalizzate:

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

Il filtro viene applicato nel codice seguente:

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

Implementazione di IFilterFactory in un attributo

I filtri che implementano IFilterFactory sono utili per i filtri che:

• Non richiedono il passaggio di parametri.
• Le dipendenze del costruttore devono essere soddisfatte dal DI.

TypeFilterAttribute implementa IFilterFactory. IFilterFactory espone il metodo CreateInstance per creare un'istanza IFilterMetadata. CreateInstance carica il tipo specificato dal contenitore 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)}");
        }
    }
}

Il codice seguente illustra tre approcci per l'applicazione del filtro:

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

Nel codice precedente è preferibile il primo approccio all'applicazione del filtro.

Usare il middleware nella pipeline di filtro

I filtri risorse funzionano come middleware in quanto racchiudono l'esecuzione di tutto ciò che viene dopo nella pipeline. Tuttavia, i filtri differiscono dal middleware in quanto fanno parte del runtime, il che significa che hanno accesso al contesto e ai costrutti.

Per usare il middleware come filtro, creare un tipo con un metodo Configure che specifica il middleware da inserire nella pipeline di filtro. Nell'esempio seguente viene usato il middleware per impostare un'intestazione di risposta:

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

            await next();
        });
    }
}

Usare MiddlewareFilterAttribute per eseguire il middleware:

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

I filtri middleware vengono eseguiti nella stessa fase della pipeline dei filtri delle risorse, prima dell'associazione al modello e dopo il resto della pipeline.

Sicurezza dei thread

Quando si passa un'istanza di un filtro in Add, anziché il relativo Type, il filtro è un singleton e non è thread-safe.

Risorse aggiuntive

• Visualizzare o scaricare un esempio (procedura per il download).
• Metodi di filtro per Razor Pages in ASP.NET Core