Friday, September 25, 2015

Filtering in ASP.NET MVC

In ASP.NET MVC, controllers define action methods that usually have a one-to-one relationship with possible user interactions, such as clicking a link or submitting a form. For example, when the user clicks a link, a request is routed to the designated controller, and the corresponding action method is called.
Sometimes you want to perform logic either before an action method is called or after an action method runs. To support this, ASP.NET MVC provides filters. Filters are custom classes that provide both a declarative and programmatic means to add pre-action and post-action behavior to controller action methods.
A Visual Studio project with source code is available to accompany this topic: Download.

ASP.NET MVC Filter Types

ASP.NET MVC supports the following types of action filters:
The Controller class implements each of the filter interfaces. You can implement any of the filters for a specific controller by overriding the controller's On method. For example, you can override the OnAuthorizationmethod. The simple controller included in the downloadable sample overrides each of the filters and writes out diagnostic information when each filter runs. You can implement the following On methods in a controller:

Filters Provided in ASP.NET MVC

ASP.NET MVC includes the following filters, which are implemented as attributes. The filters can be applied at the action method, controller, or application level.
  • AuthorizeAttribute. Restricts access by authentication and optionally authorization.
  • HandleErrorAttribute. Specifies how to handle an exception that is thrown by an action method.
    NoteNote:
    This filter does not catch exceptions unless the customErrors element is enabled in the Web.config file.
  • OutputCacheAttribute. Provides output caching.
  • RequireHttpsAttribute. Forces unsecured HTTP requests to be resent over HTTPS.

How To Create a Filter

You can create a filter in the following ways:
  • Override one or more of the controller's On methods.
  • Create an attribute class that derives from ActionFilterAttribute and apply the attribute to a controller or an action method.
  • Register a filter with the filter provider (the FilterProviders class).
  • Register a global filter using the GlobalFilterCollection class.
A filter can implement the abstract ActionFilterAttribute class. Some filters, such as AuthorizeAttribute, implement theFilterAttribute class directly. Authorization filters are always called before the action method runs and called before all other filter types. Other action filters, such as OutputCacheAttribute, implement the abstract ActionFilterAttributeclass, which enables the action filter to run either before or after the action method runs.
You can use the filter attribute declaratively with action methods or controllers. If the attribute marks a controller, the action filter applies to all action methods in that controller.
The following example shows the default implementation of the HomeController class. In the example, theHandleError attribute is used to mark the controller. Therefore, the filter applies to all action methods in the controller.
[HandleError]
public class HomeController : Controller
{
    public ActionResult Index()
    {
        ViewData["Message"] = "Welcome to ASP.NET MVC!";

        return View();
    }

    public ActionResult About()
    {
        return View();
    }
}


Filter Providers

Multiple filter providers can be registered. Filter providers are registered using the static Providers property. TheGetFilters(ControllerContext, ActionDescriptor) method aggregates the filters from all of the providers into a single list. Providers can be registered in any order; the order they are registered has no impact on the order in which the filter run.
NoteNote:
Filter providers are a new feature to ASP.NET MVC 3.
By default, ASP.NET MVC registers the following filter providers:
The GetFilters method returns all of the IFilterProvider instances in the service locator.

Filter Order

Filters run in the following order:
  1. Authorization filters
  2. Action filters
  3. Response filters
  4. Exception filters
For example, authorization filters run first and exception filters run last. Within each filter type, the Order value specifies the run order. Within each filter type and order, the Scope enumeration value specifies the order for filters. This enumeration defines the following filter scope values (in the order in which they run):
For example, an OnActionExecuting(ActionExecutingContext) filter that has the Order property set to zero and filter scope set to First runs before an action filter that has the Order property set to zero and filter scope set to Action. Because exception filters run in reverse order, an exception filter that has the Order property set to zero and filter scope set to First runs after an action filter that has the Order property set to zero and filter scope set to Action.
The execution order of filters that have the same type, order, and scope is undefined.
NoteNote:
In ASP.NET MVC version 3, the order of execution for exception filters has changed for exception filters that have the same Order value. In ASP.NET MVC 2 and earlier, exception filters on the controller with the same Order value as those on an action method were executed before the exception filters on the action method. This would typically be the case if exception filters are applied without a specified Order value. In ASP.NET MVC 3, this order has been reversed so that the most specific exception handler executes first. For more information, see the filter order section later in this document.

Canceling Filter Execution

You can cancel filter execution in the OnActionExecuting and OnResultExecuting methods by setting the Resultproperty to a non-null value. Any pending OnActionExecuted and OnActionExecuting filters will not be invoked and the invoker will not call the OnActionExecuted method for the canceled filter or for pending filters. TheOnActionExecuted filter for previously run filters will run. All of the OnResultExecutingand OnResultExecuted filters will run.
For example, imagine an ASP.NET MVC application that has a home controller and a simple controller. A global request timing filter is applied to the application. The request timing filter implements the four action and result filters (OnActionExecutingOnActionExecutedOnResultExecuting and OnResultExecuted). Each filter method in the application writes trace information with the name of the filter, the name of the controller, the name of the action and the type of the filter. In that case, the filter type is a request timing filter. A request to the Index action of the Homecontroller shows the following output in the trace listener (debug window).
Filter Method
Controller
Action
Filter type
OnActionExecuting
Home
Index
Request timing filter
OnActionExecuted
Home
Index
Request timing filter
OnResultExecuting
Home
Index
Request timing filter
OnResultExecuted
Home
Index
Request timing filter
Consider the same application where a trace action filter is applied to the simple controller. The simple controller also implements the four action and result filters. The simple controller has three filters, each of which implements the four action and result methods. A request to the Details action of the Simple controller shows the following output in the trace listener:
Filter Method
Controller
Action
Filter type
OnActionExecuting
Simple
Details
Simple Controller
OnActionExecuting
Simple
Details
Trace action
OnActionExecuting
Simple
Details
Request timing
OnActionExecuted
Simple
Details
Request timing
OnActionExecuted
Simple
Details
Trace action
OnActionExecuted
Simple
Details
Simple Controller
OnResultExecuting
Simple
Details
Simple Controller
OnResultExecuting
Simple
Details
Trace action
OnResultExecuting
Simple
Details
Request timing
OnResultExecuted
Simple
Details
Request timing
OnResultExecuted
Simple
Details
Trace action
OnResultExecuted
Simple
Details
Simple Controller
Now consider the same application where the trace action filter sets the result property to "Home/Index", as shown in the following example:
if (filterContext.RouteData.Values.ContainsValue("Cancel")) {
    filterContext.Result = new RedirectResult("~/Home/Index");
    Trace.WriteLine(" Redirecting from Simple filter to /Home/Index");
}
The request to the Details action of the Simple controller with the canceled result shows the following output in the trace listener:
Filter Method
Controller
Action
Filter type
OnActionExecuting
Simple
Details
Simple Controller
OnActionExecuting
Simple
Details
Trace action
OnActionExecuted
Simple
Details
Simple Controller
OnResultExecuting
Simple
Details
Simple Controller
OnResultExecuting
Simple
Details
Trace action
OnResultExecuting
Simple
Details
Request timing
OnResultExecuted
Simple
Details
Request timing
OnResultExecuted
Simple
Details
Trace action
OnResultExecuted
Simple
Details
Simple Controller
OnActionExecuting
Home
Index
Request timing filter
OnActionExecuted
Home
Index
Request timing filter
OnResultExecuting
Home
Index
Request timing filter
OnResultExecuted
Home
Index
Request timing filter
The downloadable sample for this topic implements the filtering described in these tables.

Filter State

Do not store filter state in a filter instance. Per-request state would typically be stored in the Items property. This collection is initialized to empty for every request and is disposed when the request completes. Transient per-user state is typically stored in the user's session. User-state information is often stored in a database. The downloadable sample for this topic includes a timing filter that uses per-request state. For information about how to create stateful filters, see the video Advanced MVC 3.

Related Topics

Title
Description
(Blog entry) Describes ASP.NET MVC filters in a service location context.
Describes how to use the Authorize attribute to control access to an action method.
Describes how to use the OutputCache attribute to provide output caching for an action method.
Describes how to use the HandleError attribute to handle exceptions that are thrown by an action method.
Describes how to implement custom action filters.
Explains how to add a custom action filter to an ASP.NET MVC application.

No comments: