ASP.NET Core filter pipelines

om filter must implement IAsyncActionFilter. The await next() pattern is non-negotiable for production stability. The memory allocation difference alone justifies the refactoring effort in high-traffic systems.

Core Solution

Implementing robust filter pipelines requires strict adherence to asynchronous patterns, correct DI integration, and strategic placement within the pipeline hierarchy.

1. Pipeline Execution Hierarchy

Understanding the execution order is prerequisite to correct implementation. The pipeline executes in concentric layers:

1. Authorization Filters: Run first. Short-circuit if unauthorized.
2. Resource Filters: Run next. Can short-circuit before model binding. Ideal for caching.
3. Action Filters: Run before and after the action method. Access to model state and arguments.
4. Result Filters: Run before and after the action result execution.
5. Exception Filters: Run only if an unhandled exception occurs.

2. Asynchronous Filter Implementation

Always use IAsyncActionFilter. The implementation must await the next delegate to ensure downstream execution and proper timing.

using Microsoft.AspNetCore.Mvc.Filters;

public class AuditLogFilter : IAsyncActionFilter
{
    private readonly ILogger<AuditLogFilter> _logger;

    public AuditLogFilter(ILogger<AuditLogFilter> logger)
    {
        _logger = logger;
    }

    public async Task OnActionExecutionAsync(
        ActionExecutingContext context,
        ActionExecutionDelegate next)
    {
        // Pre-action logic
        var startTime = DateTime.UtcNow;
        
        // CRITICAL: Await the delegate. 
        // Calling next() without await breaks the pipeline flow.
        var resultContext = await next();

        // Post-action logic
        var duration = DateTime.UtcNow - startTime;
        
        // Only log if the action was not short-circuited by a previous filter
        if (resultContext.Result != null)
        {
            _logger.LogInformation(
                "Action {Action} short-circuited. Result: {ResultType}",
                context.ActionDescriptor.DisplayName,
                resultContext.Result.GetType().Name);
        }
        else
        {
            _logger.LogInformation(
                "Action {Action} completed in {Duration}ms",
                context.ActionDescriptor.DisplayName,
                duration.TotalMilliseconds);
        }
    }
}

3. Dependency Injection via IFilterFactory

Filters are not resolved by DI by default. Using [ServiceFilter] requires registering every filter type. The recommended pattern for production is IFilterFactory, which allows filters to be resolved from the service provider while keeping the attribute lightweight.

public class AuditLogAttribute : Attribute, IFilterFactory
{
    public bool IsReusable => false;

    public IFilterMetadata CreateInstance(IServiceProvider serviceProvider)
    {
        // Resolve the filter from DI
        return serviceProvider.GetRequiredService<AuditLogFilter>();
    }
}

Usage:

[AuditLog]
public async Task<IActionResult> UpdateUser([FromBody] UserDto dto)
{
    // Action logic
}

4. Global vs. Attribute Registration

• Global Registration: Use for concerns that apply to all controllers (e.g., global exception handling, global validation).
• Attribute Registration: Use for specific business logic or when filters require parameters.
• Optimization: When registering globally, use options.Filters.AddService<T>() to leverage DI resolution, or options.Filters.Add<T>() for stateless singletons.

builder.Services.AddControllers(options =>
{
    // Stateful filter resolved per request via DI
    options.Filters.AddService<AuditLogFilter>();
    
    // Stateless singleton filter
    options.Filters.Add<GlobalExceptionFilter>();
});

5. Resource Filters for Caching

Resource filters execute before model binding. This is the optimal location for response caching to avoid deserialization overhead.

public class ResponseCacheFilter : Attribute, IResourceFilter
{
    private readonly int _durationSeconds;

    public ResponseCacheFilter(int durationSeconds)
    {
        _durationSeconds = durationSeconds;
    }

    public void OnResourceExecuting(ResourceExecutingContext context)
    {
        // Check cache before model binding
        // If hit, set context.Result and short-circuit
        var cached = Cache.Get(context.HttpContext.Request.Path);
        if (cached != null)
        {
            context.Result = new OkObjectResult(cached);
            context.HttpContext.Response.Headers.CacheControl = 
                $"public, max-age={_durationSeconds}";
        }
    }

    public void OnResourceExecuted(ResourceExecutedContext context)
    {
        // Store successful results in cache
        if (context.Result is OkObjectResult okResult)
        {
            Cache.Set(context.HttpContext.Request.Path, okResult.Value, _durationSeconds);
        }
    }
}

Pitfall Guide

1. Synchronous Blocking in Async Contexts

Mistake: Implementing IActionFilter and performing I/O operations (database calls, HTTP requests) synchronously. Impact: Thread pool starvation. Under load, all threads are blocked waiting for I/O, causing request timeouts and 503 errors. Fix: Always implement IAsyncActionFilter and use await for all I/O operations.

2. Stateful Global Filters

Mistake: Registering a filter globally that contains instance fields storing request-specific data. Impact: Race conditions. Global filters are singletons. Concurrent requests will overwrite each other's state, leading to data corruption. Fix: Filters must be stateless. Pass data via HttpContext.Items or resolve scoped services via IFilterFactory.

3. Overusing Filters for Middleware Logic

Mistake: Implementing IP blocking, CORS, or generic logging in filters. Impact: Unnecessary overhead. Filters require action descriptor resolution. Middleware executes earlier and faster. Fix: Move infrastructure concerns to middleware. Reserve filters for logic requiring ActionArguments, ModelState, or ActionDescriptor.

4. Ignoring Short-Circuiting

Mistake: Executing post-action logic in a filter even when an upstream filter has short-circuited the pipeline. Impact: Redundant processing and incorrect telemetry. Fix: Check context.Result in the post-action phase. If Result is not null, the pipeline was short-circuited.

public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
{
    var resultContext = await next();
    
    // Guard against short-circuited pipelines
    if (resultContext.Result == null)
    {
        // Safe to run post-action logic
        PerformAudit(resultContext);
    }
}

5. Misplaced Exception Handling

Mistake: Using exception filters to swallow exceptions and return generic errors, masking root causes. Impact: Debugging becomes impossible. Operations lose visibility into failure modes. Fix: Exception filters should transform exceptions for the client but must log the full exception details. Never use exception filters for control flow.

6. IAlwaysRun Misuse

Mistake: Applying [AlwaysRun] to filters that should not execute after short-circuiting. Impact: Unintended side effects. [AlwaysRun] forces execution even if an earlier filter set a result. Fix: Use [AlwaysRun] only for critical cleanup or logging that must occur regardless of pipeline state.

7. DI Resolution Failures

Mistake: Using [ServiceFilter] without registering the filter type in IServiceCollection. Impact: Runtime InvalidOperationException when the action is invoked. Fix: Prefer IFilterFactory pattern or ensure all filter types are registered. Use AddService<T> for global filters to enforce DI validation at startup.

Production Bundle

Action Checklist

• Audit Filter Interfaces: Scan codebase for IActionFilter and refactor to IAsyncActionFilter where I/O is present.
• Validate Async Patterns: Ensure all filter implementations use await next() and do not call .Result or .Wait().
• Check Filter State: Verify global filters are stateless. Move scoped state to HttpContext.Items or resolved services.
• Review Placement: Move IP blocking, CORS, and generic logging to middleware. Keep filters for model binding, authorization, and action-specific concerns.
• Implement Short-Circuit Guards: Add if (context.Result != null) checks in post-action logic to prevent redundant execution.
• Adopt IFilterFactory: Replace [ServiceFilter] usage with IFilterFactory attributes for cleaner DI management.
• Benchmark Critical Paths: Run BenchmarkDotNet on high-traffic endpoints with and without filters to quantify overhead.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Access Control	Authorization Filter	Integrates with security pipeline; runs first.	Low
Request Logging	Middleware	Lower overhead; no action context needed.	Low
Model Validation	Action Filter	Access to ModelState and ActionArguments.	Medium
Rate Limiting	Middleware	Terminates request before expensive pipeline stages.	Low
Response Caching	Resource Filter	Caches before model binding; saves deserialization cost.	Medium
Audit Trail	Action Filter	Captures input arguments and output result.	Medium
Global Error Handling	Middleware	Handles exceptions outside of MVC context.	Low
Tenant Resolution	Resource Filter	Resolves tenant before action execution.	Low

Configuration Template

Use this template in Program.cs for a robust filter configuration.

var builder = WebApplication.CreateBuilder(args);

// Register scoped filters
builder.Services.AddScoped<AuditLogFilter>();
builder.Services.AddScoped<ValidationFilter>();

builder.Services.AddControllers(options =>
{
    // Global exception handling via middleware is preferred, 
    // but filter can be used for MVC-specific errors
    options.Filters.Add<GlobalExceptionFilter>();
    
    // Scoped filter resolved via DI
    options.Filters.AddService<AuditLogFilter>();
    
    // Stateless filter
    options.Filters.Add<RequireHttpsFilter>();
})
.AddJsonOptions(options =>
{
    // JSON options configuration
});

// Middleware pipeline setup
var app = builder.Build();

app.UseMiddleware<RequestLoggingMiddleware>();
app.UseMiddleware<RateLimitingMiddleware>();

app.MapControllers();
app.Run();

Quick Start Guide

1. Create Async Filter: Implement IAsyncActionFilter and structure OnActionExecutionAsync with await next().
2. Add DI Support: Implement IFilterFactory on a custom attribute to resolve the filter from the service provider.
3. Register Service: Add the filter class to IServiceCollection with the appropriate lifetime (AddScoped for stateful, AddSingleton for stateless).
4. Apply Filter: Decorate controllers/actions with the attribute or add globally via AddControllers options.
5. Verify: Run the application and check logs to ensure pre/post logic executes correctly and no synchronous blocks occur.