Class NanoRouteJsonExtensions

Adds JSON-focused helpers for request body binding, structured error responses, and JSON responses.

Inheritance

object

NanoRouteJsonExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: NanoRoute

Assembly: NanoRoute.dll

Syntax

public static class NanoRouteJsonExtensions

Remarks

These helpers are optional conveniences on top of the core routing pipeline. They are implemented as extension methods on RouteScopeBuilder and HttpResponseMessage.

Examples

builder
    .AddJsonErrorDetails()
    .AddJsonBody(typeof(CreateUserRequest), "body")
    .AddHandler("POST", "/users/", (context, _) => Results.Ok(context.Parameters["body"]));

Methods

AddJsonBody<TBuilder>(TBuilder, IEnumerable<string>, string, JsonTypeInfo, string)

Deserializes JSON request bodies into a route parameter for the selected HTTP methods.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should require a JSON body.
string	pattern	The route pattern where the JSON-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope body binding to selected routes.
JsonTypeInfo	typeInfo	The metadata used to deserialize the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

Requests without content, requests with a non-JSON content type, and requests with invalid JSON throw HttpRequestException. Add AddJsonErrorDetails to translate those into structured HTTP error responses. The deserialized body is written into Parameters, and an existing value with the same key is overwritten.

Examples

routerBuilder
    .AddJsonErrorDetails()
    .AddJsonBody("POST", "/users/", MyJsonContext.Default.CreateUserRequest, "body")
    .AddHandler("POST", "/users/", (context, _) =>
    {
        CreateUserRequest body = (CreateUserRequest) context.Parameters["body"]!;
        return Task.FromResult(HttpResponseMessage.Json(HttpStatusCode.Created, body));
    });

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, typeInfo, or paramName is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, IEnumerable<string>, string, Type, string)

Deserializes JSON request bodies into a route parameter using runtime type metadata.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern, Type type, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should require a JSON body.
string	pattern	The route pattern where the JSON-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope body binding to selected routes.
Type	type	The CLR type expected in the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddJsonBody(["POST", "PUT"], "/users/", typeof(CreateUserRequest), "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, type, or paramName is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.
NotSupportedException	Thrown when JSON metadata cannot be resolved for type.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, IEnumerable<string>, JsonTypeInfo, string)

Deserializes JSON request bodies into a route parameter for the selected HTTP methods.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should require a JSON body.
JsonTypeInfo	typeInfo	The metadata used to deserialize the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

This overload uses CurrentPrefix as the route pattern, so the JSON-binding middleware is bound to the whole current builder scope for the selected HTTP methods.

Examples

builder.AddJsonBody(["POST", "PUT"], MyJsonContext.Default.CreateUserRequest, "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, typeInfo, or paramName is null.
ArgumentException	Thrown when an entry in verbs is not a supported HTTP method.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, IEnumerable<string>, Type, string)

Deserializes JSON request bodies into a route parameter using runtime type metadata.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, Type type, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should require a JSON body.
Type	type	The CLR type expected in the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

This overload uses CurrentPrefix as the route pattern, so the JSON-binding middleware is bound to the whole current builder scope for the selected HTTP methods.

Examples

builder.AddJsonBody(["POST", "PUT"], typeof(CreateUserRequest), "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, type, or paramName is null.
ArgumentException	Thrown when an entry in verbs is not a supported HTTP method.
NotSupportedException	Thrown when JSON metadata cannot be resolved for type.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, string, string, JsonTypeInfo, string)

Deserializes JSON request bodies into a route parameter for a single HTTP method.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, string verb, string pattern, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP method that should require a JSON body.
string	pattern	The route pattern where the JSON-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope body binding to selected routes.
JsonTypeInfo	typeInfo	The metadata used to deserialize the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddJsonBody("POST", "/users/", MyJsonContext.Default.CreateUserRequest, "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verb, pattern, typeInfo, or paramName is null.
ArgumentException	Thrown when verb is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, string, string, Type, string)

Deserializes JSON request bodies into a route parameter using runtime type metadata.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, string verb, string pattern, Type type, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP method that should require a JSON body.
string	pattern	The route pattern where the JSON-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope body binding to selected routes.
Type	type	The CLR type expected in the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddJsonBody("POST", "/users/", typeof(CreateUserRequest), "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verb, pattern, type, or paramName is null.
ArgumentException	Thrown when verb is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.
NotSupportedException	Thrown when JSON metadata cannot be resolved for type.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, string, JsonTypeInfo, string)

Deserializes JSON request bodies into a route parameter for POST, PUT, and PATCH.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, string pattern, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern where the JSON-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope body binding to selected routes.
JsonTypeInfo	typeInfo	The metadata used to deserialize the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddJsonBody("/users/", MyJsonContext.Default.CreateUserRequest, "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, pattern, typeInfo, or paramName is null.
ArgumentException	Thrown when pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, string, Type, string)

Deserializes JSON request bodies into a route parameter using runtime type metadata for POST, PUT, and PATCH.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, string pattern, Type type, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern where the JSON-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope body binding to selected routes.
Type	type	The CLR type expected in the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddJsonBody("/users/", typeof(CreateUserRequest), "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, pattern, type, or paramName is null.
ArgumentException	Thrown when pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.
NotSupportedException	Thrown when JSON metadata cannot be resolved for type.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, JsonTypeInfo, string)

Deserializes JSON request bodies into a route parameter for POST, PUT, and PATCH.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
JsonTypeInfo	typeInfo	The metadata used to deserialize the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

This overload uses CurrentPrefix as the route pattern, so the JSON-binding middleware is bound to the whole current builder scope for POST, PUT, and PATCH.

Examples

builder.AddJsonBody(MyJsonContext.Default.CreateUserRequest, "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, typeInfo, or paramName is null.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonBody<TBuilder>(TBuilder, Type, string)

Deserializes JSON request bodies into a route parameter using runtime type metadata for POST, PUT, and PATCH.

Declaration

public static TBuilder AddJsonBody<TBuilder>(this TBuilder routeScopeBuilder, Type type, string paramName) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
Type	type	The CLR type expected in the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

This overload uses CurrentPrefix as the route pattern, so the JSON-binding middleware is bound to the whole current builder scope for POST, PUT, and PATCH.

Examples

builder.AddJsonBody(typeof(CreateUserRequest), "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, type, or paramName is null.
NotSupportedException	Thrown when JSON metadata cannot be resolved for type.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

AddJsonErrorDetails<TBuilder>(TBuilder)

Adds middleware that converts router exceptions into JSON ErrorDetails responses for all supported HTTP methods.

Declaration

public static TBuilder AddJsonErrorDetails<TBuilder>(this TBuilder routeScopeBuilder) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

This overload uses CurrentPrefix as the route pattern, so the error-detail middleware is bound to the whole current builder scope for all supported HTTP methods.

Examples

builder.AddJsonErrorDetails();

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder is null.

AddJsonErrorDetails<TBuilder>(TBuilder, IEnumerable<string>)

Adds middleware that converts router exceptions into JSON ErrorDetails responses for the selected HTTP methods.

Declaration

public static TBuilder AddJsonErrorDetails<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the error-detail middleware.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

This overload uses CurrentPrefix as the route pattern, so the error-detail middleware is bound to the whole current builder scope for the selected HTTP methods.

Examples

builder.AddJsonErrorDetails(["GET", "POST"]);

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder or verbs is null.
ArgumentException	Thrown when an entry in verbs is not a supported HTTP method.

AddJsonErrorDetails<TBuilder>(TBuilder, IEnumerable<string>, string)

Adds middleware that converts router exceptions into JSON ErrorDetails responses.

Declaration

public static TBuilder AddJsonErrorDetails<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the error-detail middleware.
string	pattern	The route pattern where the error-detail middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope JSON error responses to selected routes.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

This helper wraps HttpRequestException values into JSON responses and also installs AddExceptionHandler<TBuilder>(TBuilder) so unexpected exceptions are normalized before they reach the client. OperationCanceledException is not translated into JSON and continues to propagate to the caller unchanged. Use ConfigureJsonErrorDetails<TBuilder>(TBuilder, ConfigureBuilderDelegate<JsonErrorDetailsConfig>) before calling this method to include developer diagnostics or replace the ErrorDetails serialization metadata.

Examples

routerBuilder
    .AddJsonErrorDetails()
    .AddHandler("GET", "/items/{id:int}/", (context, _) =>
        throw new InvalidOperationException("Unexpected state"));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, or pattern is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddJsonErrorDetails<TBuilder>(TBuilder, string)

Adds middleware that converts router exceptions into JSON ErrorDetails responses for all supported HTTP methods.

Declaration

public static TBuilder AddJsonErrorDetails<TBuilder>(this TBuilder routeScopeBuilder, string pattern) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern where the error-detail middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope JSON error responses to selected routes.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddJsonErrorDetails("/api/*");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder or pattern is null.
ArgumentException	Thrown when pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddJsonErrorDetails<TBuilder>(TBuilder, string, string)

Adds middleware that converts router exceptions into JSON ErrorDetails responses for a single HTTP method.

Declaration

public static TBuilder AddJsonErrorDetails<TBuilder>(this TBuilder routeScopeBuilder, string verb, string pattern) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP method that should use the error-detail middleware.
string	pattern	The route pattern where the error-detail middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope JSON error responses to selected routes.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddJsonErrorDetails("GET", "/api/*");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verb, or pattern is null.
ArgumentException	Thrown when verb is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

ConfigureJsonErrorDetails<TBuilder>(TBuilder, ConfigureBuilderDelegate<JsonErrorDetailsConfig>)

Updates the JSON error-detail configuration visible from the current builder scope.

Declaration

public static TBuilder ConfigureJsonErrorDetails<TBuilder>(this TBuilder routeScopeBuilder, ConfigureBuilderDelegate<JsonErrorDetailsConfig> configure) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
ConfigureBuilderDelegate<JsonErrorDetailsConfig>	configure	A callback that receives the current configuration and returns the replacement configuration.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The configuration is stored in Metadata. Child builders created after this method is called inherit the updated configuration; existing child builders keep their own scoped copy. Registered JSON error-detail middleware snapshots the configuration that is current at registration time.

Examples

builder.ConfigureJsonErrorDetails(config => config with
{
    PopulateErrorInfo = true
});

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, configure, or the value returned by configure is null.

Json(HttpStatusCode, object?, JsonTypeInfo)

Creates a JSON response using the supplied type metadata.

Declaration

public static HttpResponseMessage Json(HttpStatusCode statusCode, object? body, JsonTypeInfo typeInfo)

Parameters

Type	Name	Description
HttpStatusCode	statusCode	The HTTP status code to assign to the response.
object	body	The value to serialize.
JsonTypeInfo	typeInfo	The metadata used to serialize body.

Returns

Type	Description
HttpResponseMessage	A new HttpResponseMessage with JSON content.

Examples

return HttpResponseMessage.Json(HttpStatusCode.Created, body, MyJsonContext.Default.CreateUserResponse);

Exceptions

Type	Condition
ArgumentNullException	Thrown when typeInfo is null.
InvalidOperationException	Thrown when the supplied JSON metadata is not compatible with body.
NotSupportedException	Thrown when the value cannot be serialized with the supplied JSON metadata.

Json<T>(HttpStatusCode, T?)

Creates a JSON response using Web.

Declaration

public static HttpResponseMessage Json<T>(HttpStatusCode statusCode, T? body)

Parameters

Type	Name	Description
HttpStatusCode	statusCode	The HTTP status code to assign to the response.
T	body	The value to serialize.

Returns

Type	Description
HttpResponseMessage	A new HttpResponseMessage with JSON content.

Type Parameters

Name	Description
T	The type of the response body.

Examples

return HttpResponseMessage.Json(HttpStatusCode.Created, body);

Exceptions

Type	Condition
InvalidOperationException	Thrown when JSON metadata cannot be resolved or is not compatible with body.
NotSupportedException	Thrown when the value cannot be serialized with the resolved JSON metadata.

Json<T>(HttpStatusCode, T?, JsonSerializerOptions)

Creates a JSON response using serializer options to resolve metadata for T.

Declaration

public static HttpResponseMessage Json<T>(HttpStatusCode statusCode, T? body, JsonSerializerOptions options) where T : notnull

Parameters

Type	Name	Description
HttpStatusCode	statusCode	The HTTP status code to assign to the response.
T	body	The value to serialize.
JsonSerializerOptions	options	The serializer options used to resolve metadata and serialization behavior.

Returns

Type	Description
HttpResponseMessage	A new HttpResponseMessage with JSON content.

Type Parameters

Name	Description
T	The type of the response body.

Examples

return HttpResponseMessage.Json(HttpStatusCode.OK, body, JsonSerializerOptions.Web);

Exceptions

Type	Condition
ArgumentNullException	Thrown when options is null.
InvalidOperationException	Thrown when JSON metadata cannot be resolved or is not compatible with body.
NotSupportedException	Thrown when the value cannot be serialized with the resolved JSON metadata.

Json<T>(HttpStatusCode, T?, JsonTypeInfo<T>)

Creates a JSON response using the supplied type metadata.

Declaration

public static HttpResponseMessage Json<T>(HttpStatusCode statusCode, T? body, JsonTypeInfo<T> typeInfo)

Parameters

Type	Name	Description
HttpStatusCode	statusCode	The HTTP status code to assign to the response.
T	body	The value to serialize.
JsonTypeInfo<T>	typeInfo	The metadata used to serialize body.

Returns

Type	Description
HttpResponseMessage	A new HttpResponseMessage with JSON content.

Type Parameters

Name	Description
T

Examples

return HttpResponseMessage.Json(HttpStatusCode.OK, body, MyJsonContext.Default.CreateUserResponse);

Exceptions

Type	Condition
ArgumentNullException	Thrown when typeInfo is null.
InvalidOperationException	Thrown when the supplied JSON metadata is not compatible with body.
NotSupportedException	Thrown when the value cannot be serialized with the supplied JSON metadata.

Json<T>(T?)

Creates a JSON response with OK. This method uses Web when creating the response.

Declaration

public static HttpResponseMessage Json<T>(T? body)

Parameters

Type	Name	Description
T	body	The value to serialize.

Returns

Type	Description
HttpResponseMessage	A new HttpResponseMessage with JSON content.

Type Parameters

Name	Description
T	The type of the response body.

Examples

return HttpResponseMessage.Json(body);

Exceptions

Type	Condition
InvalidOperationException	Thrown when JSON metadata cannot be resolved or is not compatible with body.
NotSupportedException	Thrown when the value cannot be serialized with the resolved JSON metadata.

WithJsonBody(EndpointBuilder, JsonTypeInfo, string)

Deserializes JSON request bodies into an endpoint parameter using source-generated or custom JSON metadata.

Declaration

public static EndpointBuilder WithJsonBody(this EndpointBuilder endpointBuilder, JsonTypeInfo typeInfo, string paramName)

Parameters

Type	Name	Description
EndpointBuilder	endpointBuilder
JsonTypeInfo	typeInfo	The metadata used to deserialize the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
EndpointBuilder	The current endpointBuilder instance.

Remarks

The JSON-binding middleware is registered for the endpoint's captured HTTP methods and route match kind. The deserialized body is written into Parameters, and an existing value with the same key is overwritten.

Examples

endpoint.WithJsonBody(MyJsonContext.Default.CreateUserRequest, "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when endpointBuilder, typeInfo, or paramName is null.
ArgumentException	Thrown when the endpoint's captured HTTP method is not supported.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

WithJsonBody(EndpointBuilder, Type, string)

Deserializes JSON request bodies into an endpoint parameter using runtime type metadata.

Declaration

public static EndpointBuilder WithJsonBody(this EndpointBuilder endpointBuilder, Type type, string paramName)

Parameters

Type	Name	Description
EndpointBuilder	endpointBuilder
Type	type	The CLR type expected in the request body.
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
EndpointBuilder	The current endpointBuilder instance.

Examples

endpoint.WithJsonBody(typeof(CreateUserRequest), "body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when endpointBuilder, type, or paramName is null.
ArgumentException	Thrown when the endpoint's captured HTTP method is not supported.
NotSupportedException	Thrown when JSON metadata cannot be resolved for type.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

WithJsonBody<T>(EndpointBuilder, string)

Deserializes JSON request bodies into an endpoint parameter using runtime type metadata.

Declaration

public static EndpointBuilder WithJsonBody<T>(this EndpointBuilder endpointBuilder, string paramName) where T : notnull

Parameters

Type	Name	Description
EndpointBuilder	endpointBuilder
string	paramName	The parameter name under which the deserialized body will be stored.

Returns

Type	Description
EndpointBuilder	The current endpointBuilder instance.

Type Parameters

Name	Description
T	The CLR type expected in the request body.

Examples

endpoint.WithJsonBody<CreateUserRequest>("body");

Exceptions

Type	Condition
ArgumentNullException	Thrown when endpointBuilder or paramName is null.
ArgumentException	Thrown when the endpoint's captured HTTP method is not supported.
NotSupportedException	Thrown when JSON metadata cannot be resolved for T.
HttpRequestException	Thrown during request processing when the body is missing, the content type is not JSON, or the JSON payload is invalid.
OperationCanceledException	Thrown during request processing when the request cancellation token is canceled.

get_JsonTypeInfo()

Provides the default JSON serialization meta-data.

Declaration

public static JsonTypeInfo<ErrorDetails> get_JsonTypeInfo()

Returns

Type	Description
JsonTypeInfo<ErrorDetails>

Examples

JsonTypeInfo<ErrorDetails> typeInfo = ErrorDetails.JsonTypeInfo;