Filters provide a simple and elegant way to implement cross-cutting concerns in your ASP.NET MVC application. Filter achieve this by injecting code into the request processing. Examples of cross-cutting concerns are logging and authorization.
Five Types of Filter
ASP.NET MVC has five types of filter built-in which allow you to implement additional logic during the request processing.
|Filter Type||Interface||Default Implementation||Description|
|Action||IActionFilter||ActionFilterAttribute||Runs before and after the action method|
|Authentication||IAuthenticationFilter||None||Runs first, before any other filters or the|
action method and can run again after
the authorization filters
|Authorization||IAuthorizationFilter||AuthorizeAttribute||Runs second, after authentication, but|
before any other filters or the action method
|Exception||IExceptionFilter||HandleErrorAttribute||Runs only if another filter, the action method,|
or the action result throws an exception
|Result||IResultFilter||ActionFilterAttribute||Runs before and after the action method|
Before the framework invokes an action, it inspects the method definition to see if it has attributes. If the framework finds one, the methods of this attribute are invoked. As you can see, the ActionFilterAttribute is implemented by IActionFilter and IResultFilter. This class is abstract and enforces you to implement it. The AuthorizeAttribute and HandleErrorAttribute classes already contain useful features therefore you don’t have to derive from them.
Applying a Filter to an Action or Controller
It is possible to apply one or more filters to an action or controller. A filter which is often used is the Authorize attribute. If the Authorize attribute is applied to an action, only users which are logged in can invoke this action. If the attribute is applied to the controller, it applies to all actions.
On the example above, I applied the Authorize attribute to the controller which means that every action of this controller can be invoked only by logged in users. Additionally, I applied the attribute to the DoAdminStuff and set the Roles to Admin which means that only users which have the admin role are allowed to invoke this action. This example also shows that some attributes can have a parameter to specify the action.
Applying Authorization Filters
In the last section, I already used one of the two attributes of the Authorize attribute. The available properties are:
|Users||Comma-separated usernames which are allowed|
|Roles||Comma-separated role names|
If several roles are declared, then the user must have at least one of these roles.
Applying Authentication Filters
Authentication filters run before any other filter and can also run after an action has been executed but before the ActionResult is processed.
The IAuthenticationFilter Interface
The Authentication filter implements IAuthenticationFilter which implements two methods:
- void OnAuthentication(AuthenticationContext context);
- void OnAuthenticationChallenge(AuthenticationChallengeContext context);
The OnAuthenticationChallenge method is invoked whenever a request fails the authentication or authorization process. The parameter is an AuthenticationChallengeContext object which is derived from ControllerContext. The AuthenticationChallengeContext class has two useful properties:
|ActionDescriptor||Returns an ActionDescriptor that describes the action method to which the filter has been applied|
|Result||Sets an ActionResult that expresses the result of the authentication challenge|
Applying Exception Filters
Exception filters are only executed if an unhandled exception has been thrown when invoking an action. An exception can be thrown by:
- Another filter
- The action itself
- During the action result execution
Microsoft provides the HandleErrorAttribute for exception handling. This class implements the IExceptionFilter interface. The HandleErrorAttribute class has three properties:
|ExceptionType||Type||The exception type handled by this filter. It will also handle exception types that inherit from the specified value but will ignore all others. The default value is System.Exception, which means that, by default, it will handle all standard exceptions.|
|View||string||The name of the view template that this filter renders. If you do not specify a value, it takes a default value of Error, so by default, it renders /Views/<currentControllerName>/ Error.cshtml or /Views/Shared/Error.cshtml.|
|Master||string||The name of the layout used when rendering this filter’s view. If you do not specify a value, the view uses its default layout page.|
As summary: When an unhandled exception of the type specified by ExceptionType is encountered, this filter will render the view specified by the View property
If an exception occurs in your development environment, you will get the famous yellow screen of death. To prevent this from happening, you have to set the customsError attribute to the web.config file.
The customError attribute redirects the request to the location specified at the defaultRedirect attribute. The default value for the mode attribute is RemoteOnly, which means that all local requests see the yellow screen of death.
Applying the HandleError attribute
Applying the HandleError attribute to an action enables you to prevent the application from crashing and also enables you to provide some useful error message and help to the user. You can specify an ExceptionType and then send the request to a specific view and provide some information about what went wrong.
On the screenshot above, you can see two different versions of how to use the HandleError attribute. The first line with the attribute only would redirect to /Error/ErrorMessage because I defined this destination in the defaultRedirect attribute in the web.config. This page can only show a generic error message which might not help the user at all.
Therefore you can also specify which exception might happen and then redirect the request to a specific view. In the example above, I redirect all ArgumentOutOfRangeException to the ErrorMessage view. This view can be either in the view folder of the controller or in the shared view folder.
Displaying information with the HandleErrorInfo view model
The HandleError attribute passes the HandleErrorInfo view model to your view. The properties of the HandleErrorInfo view model are:
|ActionName||string||Returns the name of the action method that generated the exception|
|ControllerName||string||Returns the name of the controller that generated the exception|
|Exception||Exception||Returns the exception|
In the ErrorMessage view, I can use this view model to give the user a proper error description and provide some help to solve the problem.
I know that my error message is not the best and I bet that you can come up with a better one. I also provided a link, so the user can easily return to the page where he came from.
Applying Action Filters
Action filters can be used for anything. I use them for performance checks to find problems with the execution of actions.
Using the IActionFilter interface
The IActionFilter interface has two methods:
- void OnActionExecuting(ActionExecutingContext filterContext)
- void OnActionExecuted(ActionExecutedContext filterContext)
The OnActionExecuting method is called before an action method is invoked. The parameter, ActionExecutingContext has two properties:
|ActionDescriptor||ActionDescriptor||Provides details of the action method|
|Result||ActionResult||The result for the action method. A filter can cancel the request by setting this property to a non-null value|
The OnActionExecuted method is called after the action is completed and has 5 properties:
|ActionDescriptor||ActionDescriptor||Provides details of the action method|
|Canceled||bool||Returns true if the action has been canceled by another filter|
|Exception||Exception||Returns an exception thrown by another filter or by the action method|
|ExceptionHandled||bool||Returns true if the exception has been handled|
|Result||ActionResult||The result for the action method; a filter can cancel the request by setting this property to a non-null value|
Implementing an Action Filter
I created a new class called MyActionAttribute which derives from FilterAttribute and IActionFilter. In the OnActionExecuting method, I check if the browser is Chrome. If the request comes from Chrome, I return an HttpUnauthorizedResult. Again, this is not the most useful implementation but I think you get what you can do with this method. For now, I don’t implement anything in the OnActionExecuted method. This is no problem. Just be careful because Visual Studio throws a NotImplementedException if you let Visual Studio create the method.
To use my new filter, I apply it to the CheckFilter action. Note that you don’t have to write MyActionAttribute when applying it as attribute. MyAction is enough.
When you call this action from Chrome, you can see that the access is denied for the user.
Implementing the OnActionExecutedMethod
As I already mentioned, I often use action filter to measure the execution time of an action. To do that, I start a Stopwatch in the OnActionExecuting method and stop it in the OnActionExecuted method. Afterwards, I print the execution time.
To see different results, I added Thread.Sleep with a random number, so that the execution will take somewhere between some milliseconds and two seconds.
The print of the execution time is printed before the content of the action because the action filter is executed before the result of the action is processed.
Applying Result Filters
The IResultFilter which is implemented by result filters has two methods:
- void OnResultExecuting(ResultExecutingContext filterContext)
- void OnResultExecuted(ResultExecutedContext filterContext)
The OnResultExecuting method is called after an action has returned an action result but before this result is executed. The OnResultExecuted method is called after the action result is executed. The ResultExecutingContext and ResultExecutedContext parameter has the same properties as the action filter parameter and also have the same effects.
Implementing a Result Filter
To demonstrate how the result filter works, I repeat the performance test but this time I measure the time between the start and the end of the execution of the ActionResult. To do that, I implement the IResultFilter and work with the OnResultExecuting and OnResultExecuted method.
The next step is applying the filter to an action and call the action to see the result.
When you look at the output, you see a difference in the result of the action filter output. The print of the measured time is beneath the output of the action. This behavior is caused by the fact that the result filter is processed after the ActionResult. Therefore the result is printed and then afterward the measured time is added.
Filtering without Filter
In the previous examples, I showed how to create implementations of filters by implementing the desired interface. The Controller class already implements the IAuthenticationFilter, IAuthorizationFilter, IActionFilter, IResultFilter, and IExceptionFilter interfaces. It also provides empty virtual implementations for each of the methods. Knowing this, you can override the desired methods directly in the controller and achieve the same outcome as the filter classes did.
If you call the Index action of the FilteringWithoutFilter controller, you will see the same result as previously with the attributes.
I have to admit that I am not a big fan of this approach. The big advantage of ASP.NET MVC is Separation of Concerns. When using filtering within a controller, you lose this advantage. The only time when it might make sense to use filtering directly in a controller is when this class is a base class for other controllers.
I recommend using the attribute approach.
Simply combining Action and Result Filter
If you look closely, you can see that I combine the action filter method OnActionExecuting and the result filter method OnResultExecuted. You can do this yourself by implementing the IActionFilter and IResultFilter interface or by deriving from ActionFilterAttribute which implements both interfaces. The advantage of deriving from ActionFilterAttribute is that you don’t have empty methods which are not implemented.
Applying Global Filters
If you want to apply filter to all your actions, you can use global filters. If you are using the MVC template, the framework already creates the FilterConfig.cs file under the App_Start folder. Since I didn’t use the template, I create the file myself. This class has one static method, RegisterGlobalFilters. The FilterConfig.cs is pretty similar to the RouteConfig.cs. To add a new filter, add it to the filters collection with add.
Note that the namespace is Filter, not Filter.App_Start.
The HandleErrorAttribute will always be defined as global filter in ASP.NET MVC. It is not mandatory to define the HandleErrorAttribute as global filter but it is the default exception handling and will render the /Views/Shared/Error.cshtml view if an exception happens.
To register a filter a, you have to pass an instance of the filter class. The name contains the Attribute prefix. If you use the class as attribute, you can omit the Attribute prefix. Additionally, you have to add the RegisterGlobalFilters call in the Global.asx file.
In this post, I showed all five types of built-in filters in the ASP.NET MVC framework and discussed how to use them to address cross-cutting concerns effectively. These filters help you to extend the logic of your controller and actions while a request is processed.
You can find the source code on GitHub.