endpoint-filters.md

Endpoint filters

Available starting with v3.0.0

Endpoint filters allow intercepting all incoming HTTP requests prior to invoking the composition pipeline.

Defining endpoint filters

Defining an endpoint filter requires defining a class that implements the IEndpointFilter interface, like in the following snippet:

class SampleEndpointFilter : IEndpointFilter
{
    public async ValueTask<object> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        // Do something meaningful prior to invoking the rest of the pipeline
        
        var response = await next(context);

        // Do something meaningful with the response

        return response;
    }
}

^{snippet source | anchor}

Registering endpoint filters

For an endpoint filter to be included in the invocation pipeline, it must be registered at application configuration time:

app.MapCompositionHandlers()
    .AddEndpointFilter(new SampleEndpointFilter());

^{snippet source | anchor}

Accessing arguments

The endpoint filters API exposes through the EndpointFilterInvocationContext the list of arguments that the ASP.NET model binding engine determined as needed by the later invoked controller action. When using regular composition handlers, e.g. by implementing the ICompositionRequestsHandler interface, ServiceComposer cannot determine which arguments are later needed by the user composition code. To overcome this limitation and allow the arguments list to be populated and accessible by filters, it's required to use a declarative model binding approach.

For details on the arguments search API, see Named arguments experimental API.