AspNetCore Request Binding

Request binding

Partie builds your request object from the incoming HTTP request before running Providers, Parties, or the handler. Each public data property declares where its value comes from.

Use a concrete class with an empty constructor accessible to the project that declares the routes. A class with no declared constructor has an implicit empty constructor. Request models must be classes rather than records. Properties need a public getter and an accessible setter or init accessor; inherited properties follow the same rules.

Paths and query parameters

Use [FromPath] for a route placeholder and [FromParams] for a query string value:

// CourseSearchQuery.cs
public sealed class CourseSearchQuery
{
    [FromPath]
    public required int CourseId { get; init; }

    [FromParams]
    public string? AcademicYear { get; init; }
}

[CourseSearchHandlerRoute.Get("/courses/{courseId}")]
public static partial void Search();

GET /courses/42?academicYear=2026-2027 supplies CourseId and AcademicYear. Set Name when the external name differs from the property name:

[FromParams(Name = "year")]
public string? AcademicYear { get; init; }

An invalid path or query value, such as text where an integer is required, stops the request before the pipeline. Use nullable properties for optional values. Binding conversions and optional values otherwise follow ASP.NET Core's binding rules.

Headers and metadata

For ASP.NET Core, [FromMetadata] reads a request header. Its Name is required:

[FromMetadata(Name = "X-Campus")]
public string? Campus { get; init; }

The property holds input supplied by the client. Apply your application's access checks when that input affects access to data.

JSON payloads

Use [FromPayload] on one property to read a JSON body. The payload can be a record even though the outer request must be a class:

// CourseCreateCmd.cs
public sealed record CourseCreatePayload(string Title, int Capacity);

public sealed class CourseCreateCmd
{
    [FromPayload]
    public required CourseCreatePayload Body { get; init; }
}

For a POST with this body, the handler reads command.Body.Title and command.Body.Capacity:

{
  "title": "Introduction to Biology",
  "capacity": 30
}

A request can combine path, query, and header properties with its payload. It can have at most one JSON payload property. GET requests cannot bind a payload, and a request cannot mix JSON and form payload binding. Malformed bodies and unsupported content types stop before the pipeline.

Form payloads

Choose form binding with PayloadFormat.Form:

// CourseRegistrationCmd.cs
public sealed class CourseRegistrationCmd
{
    [FromPath]
    public required int CourseId { get; init; }

    [FromPayload(Format = PayloadFormat.Form)]
    public required string StudentEmail { get; init; }
}

On a command route such as /courses/{courseId}/registrations, StudentEmail comes from the form field with that name. ASP.NET Core handles form conversion and related framework requirements.

Validation and documentation

Put JSON, OpenAPI, and XML documentation attributes on the request model and its properties. They describe the API input where consumers can find it.

Binding turns input into your C# types. Expo validation checks rules such as minimum lengths and valid email addresses after binding. A value can bind successfully and still fail validation.

Use Unit as the request type when the operation takes no input. See Handlers for the handler contract and Routes and groups for registering it.