Middleware and pipeline - Neuron Agent API

Why middleware matters

Middleware lets you run logic before or after an endpoint without putting that logic inside every controller action. Typical uses:

CORS
Request logging
Route-aware auditing
Short-circuiting blocked requests
Adding data to Context.Items

Prefix middleware

Use RegisterMiddleware(...) to attach middleware to a route path or path prefix.

Router.RegisterMiddleware("/projects/*", async (HttpContext Context, Action<HttpContext> Next) =>
{
    RouteFeature? Route = Context.GetFeature<RouteFeature>();

    Context.Items["matchedRoute"] = Route?.Route.ToString() ?? string.Empty;

    if (Context.Request.QueryParameters.Optional("blocked") == "true")
    {
        await Context.Response.Return(new RestApiErrorResponse("Blocked by middleware.", "blocked"));
        return;
    }

    Next(Context);
});

If the middleware writes the response and returns early, the endpoint is never called. Do not call Next(Context) after short-circuiting.

A practical CORS pattern

ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());
CorsMiddleware Middleware = new CorsMiddleware(
[
    "https://app.example.com",
    "https://admin.example.com"
],
true);

Router.RegisterMiddleware("/users", async (HttpContext Context, Action<HttpContext> Next) =>
{
    await Middleware.Process(Context.Request, Context.Response);
    Next(Context);
});

Router.RegisterControllers(typeof(UsersController).Assembly);

Pipeline stages

Use the overload with MiddlewareStage when a middleware depends on data only available later:

Infrastructure
Routing
PreAuthorization
Authorization
PostAuthorization
PreHandler
Handler
PostHandler

Route parameters are available from Routing and later
Authorization state is available from Authorization and later
Handler is reserved for the endpoint itself

You cannot register middleware in the Handler stage. That stage is reserved for the endpoint implementation.

Attribute-based middleware

Attach middleware directly to controllers and methods with [Middleware].

[Controller]
[Route("/projects")]
[Middleware(typeof(ProjectAuditMiddleware), MiddlewareStage.Infrastructure)]
public sealed class ProjectsController : ControllerBase
{
    [HttpGet("/[projectId]")]
    [Middleware(typeof(ProjectRouteLoggingMiddleware), MiddlewareStage.Routing)]
    public Task<ProjectResponse> Get(string ProjectId)
    {
        return Task.FromResult(new ProjectResponse { ProjectId = ProjectId });
    }
}

public sealed class ProjectAuditMiddleware : MiddlewareBase
{
    public override Task Invoke(HttpContext Context, Action<HttpContext> Next)
    {
        Next(Context);
        return Task.CompletedTask;
    }
}

Middleware types declared through [Middleware] are constructed through Router.ServiceProvider, so constructor injection works for middleware classes too.

Default middleware behavior

RegisterMiddleware("/path", Middleware) defaults to PreHandler for all supported verbs
RegisterMiddleware(HttpMethodType.Get, "/path", Middleware) defaults to PreHandler for the exact method and path
Controller-level [Middleware] defaults to PreHandler
Method-level [Middleware] defaults to PreHandler
Controller-level middleware runs before method-level middleware

If you need middleware to run before routing, before authorization, or after the handler, choose an explicit MiddlewareStage instead of relying on the default.

Middleware types declared in [Middleware] must inherit MiddlewareBase.

What to read next

Authorization builds directly on the middleware model and shows how protected endpoints are declared.

​Why middleware matters

​Prefix middleware

​A practical CORS pattern

​Pipeline stages

​Attribute-based middleware

​Default middleware behavior

​What to read next

Why middleware matters

Prefix middleware

A practical CORS pattern

Pipeline stages

Attribute-based middleware

Default middleware behavior

What to read next