Updated description of always-run vs standard Result Filters. (#14690)

pull/14901/head
Kirk Larkin 2019-10-07 21:50:17 +01:00 committed by Rick Anderson
parent 2cc15a9667
commit 6b06ec7acb
1 changed files with 9 additions and 8 deletions

View File

@ -4,7 +4,7 @@ author: ardalis
description: Learn how filters work and how to use them in ASP.NET Core.
ms.author: riande
ms.custom: mvc
ms.date: 05/08/2019
ms.date: 09/28/2019
uid: mvc/controllers/filters
---
# Filters in ASP.NET Core
@ -431,9 +431,12 @@ The following code shows a result filter that adds an HTTP header:
[!code-csharp[](./filters/sample/FiltersSample/Filters/LoggingAddHeaderFilter.cs?name=snippet_ResultFilter)]
The kind of result being executed depends on the action. An action returning a view would include all razor processing as part of the <xref:Microsoft.AspNetCore.Mvc.ViewResult> being executed. An API method might perform some serialization as part of the execution of the result. Learn more about [action results](xref:mvc/controllers/actions)
The kind of result being executed depends on the action. An action returning a view would include all razor processing as part of the <xref:Microsoft.AspNetCore.Mvc.ViewResult> being executed. An API method might perform some serialization as part of the execution of the result. Learn more about [action results](xref:mvc/controllers/actions).
Result filters are only executed for successful results - when the action or action filters produce an action result. Result filters are not executed when exception filters handle an exception.
Result filters are only executed when an action or action filter produces an action result. Result filters are not executed when:
* An authorization filter or resource filter short-circuits the pipeline.
* An exception filter handles an exception by producing an action result.
The <xref:Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuting*?displayProperty=fullName> method can short-circuit execution of the action result and subsequent result filters by setting <xref:Microsoft.AspNetCore.Mvc.Filters.ResultExecutingContext.Cancel?displayProperty=fullName> to `true`. Write to the response object when short-circuiting to avoid generating an empty response. Throwing an exception in `IResultFilter.OnResultExecuting` will:
@ -465,12 +468,10 @@ The framework provides an abstract `ResultFilterAttribute` that can be subclasse
### IAlwaysRunResultFilter and IAsyncAlwaysRunResultFilter
The <xref:Microsoft.AspNetCore.Mvc.Filters.IAlwaysRunResultFilter> and <xref:Microsoft.AspNetCore.Mvc.Filters.IAsyncAlwaysRunResultFilter> interfaces declare an <xref:Microsoft.AspNetCore.Mvc.Filters.IResultFilter> implementation that runs for all action results. The filter is applied to all action results unless:
The <xref:Microsoft.AspNetCore.Mvc.Filters.IAlwaysRunResultFilter> and <xref:Microsoft.AspNetCore.Mvc.Filters.IAsyncAlwaysRunResultFilter> interfaces declare an <xref:Microsoft.AspNetCore.Mvc.Filters.IResultFilter> implementation that runs for all action results. This includes action results produced by:
* An <xref:Microsoft.AspNetCore.Mvc.Filters.IExceptionFilter> or <xref:Microsoft.AspNetCore.Mvc.Filters.IAuthorizationFilter> applies and short-circuits the response.
* An exception filter handles an exception by producing an action result.
Filters other than `IExceptionFilter` and `IAuthorizationFilter` don't short-circuit `IAlwaysRunResultFilter` and `IAsyncAlwaysRunResultFilter`.
* Authorization filters and resource filters that short-circuit.
* Exception filters.
For example, the following filter always runs and sets an action result (<xref:Microsoft.AspNetCore.Mvc.ObjectResult>) with a *422 Unprocessable Entity* status code when content negotiation fails: