Filters

Some behaviour belongs to many actions but to none of them in particular. Recording who changed what. Timing an operation. Adding a header to every response from one controller. Writing that code into twenty actions means maintaining twenty copies of it.

A filter is a piece of code the framework runs around an action. It sits inside MVC, which is the part of ASP.NET Core that maps a request to a controller method, so by the time a filter runs the framework already knows which action was selected, what its arguments are, and whether the model was valid.

That knowledge is the difference between a filter and middleware, and it decides which one you should reach for.

public sealed class AuditActionFilter(
    IAuditLog auditLog,
    ILogger<AuditActionFilter> logger) : IAsyncActionFilter
{
    public async Task OnActionExecutionAsync(
        ActionExecutingContext context,
        ActionExecutionDelegate next)
    {
        string action = context.ActionDescriptor.DisplayName ?? "unknown";
        string? user = context.HttpContext.User.Identity?.Name;

        // Bound arguments are available here. Middleware cannot see these.
        object? employeeId = context.ActionArguments.GetValueOrDefault("id");

        long startedAt = Stopwatch.GetTimestamp();

        ActionExecutedContext executed = await next();

        TimeSpan elapsed = Stopwatch.GetElapsedTime(startedAt);
        bool succeeded = executed.Exception is null;

        await auditLog.RecordAsync(new AuditEntry(action, user, employeeId, succeeded, elapsed));

        logger.LogInformation(
            "{Action} by {User} on employee {EmployeeId} finished in {ElapsedMs}ms",
            action, user, employeeId, elapsed.TotalMilliseconds);
    }
}

• IAsyncActionFilter gives you one method that surrounds the action. Everything before await next() runs first; everything after runs once the action has finished.
• ActionArguments is the dictionary of bound parameters. Reading the employee id here is what makes the audit entry meaningful, and it is the thing middleware cannot do because binding has not happened yet.
• await next() invokes the action, or the next filter in the chain. The ActionExecutedContext it returns carries the result and any exception.
• Checking executed.Exception lets the audit record a failed attempt. Do not swallow it: leave the exception alone and let your central handler deal with the response.
• Stopwatch.GetTimestamp with GetElapsedTime measures the action without allocating a Stopwatch object per request. On a hot path that difference is worth having.

// 1. Globally, to every action in the application
builder.Services.AddControllers(options =>
{
    options.Filters.Add<AuditActionFilter>();
});

// 2. To one controller or one action, when the filter needs services.
//    ServiceFilter resolves it from the container, so constructor
//    injection works. A plain attribute cannot do that.
builder.Services.AddScoped<AuditActionFilter>();

[ApiController]
[Route("api/employees")]
[ServiceFilter(typeof(AuditActionFilter))]
public sealed class EmployeesController(IEmployeeService employees) : ControllerBase
{
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
    {
        await employees.DeleteAsync(id, cancellationToken);
        return NoContent();
    }
}

// 3. An attribute filter with no dependencies, applied directly
public sealed class AddApiVersionHeaderAttribute : ActionFilterAttribute
{
    public override void OnResultExecuting(ResultExecutingContext context)
    {
        context.HttpContext.Response.Headers["X-Api-Version"] = "2";
    }
}

• Global registration is right for something that genuinely applies everywhere. If you find yourself adding exceptions to a global filter, it was not global.
• ServiceFilter exists because attributes take compile-time constant arguments, so a filter that needs an ILogger or a database context cannot be a plain attribute. ServiceFilter asks the container for the instance instead.
• Register the filter in the container when you use ServiceFilter. A scoped lifetime is usually right, since it lives for one request.
• The third form is the lightweight case: an attribute with no dependencies, inheriting ActionFilterAttribute so you override only the hook you need.
• Order matters when several filters apply. Global runs outermost, then controller, then action, unless you set the Order property to change it.