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.Json

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 RouteBuilder and HttpResponseMessage.

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 routeBuilder, IEnumerable<string> verbs, string pattern, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteBuilder

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder 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<TBuilder>(TBuilder, bool) 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));
    });

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 routeBuilder, IEnumerable<string> verbs, string pattern, Type type, string paramName) where TBuilder : notnull, RouteBuilder

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

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 routeBuilder, IEnumerable<string> verbs, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteBuilder

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

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 routeBuilder, IEnumerable<string> verbs, Type type, string paramName) where TBuilder : notnull, RouteBuilder

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

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 routeBuilder, string verb, string pattern, JsonTypeInfo typeInfo, string paramName) where TBuilder : notnull, RouteBuilder

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

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 routeBuilder, string verb, string pattern, Type type, string paramName) where TBuilder : notnull, RouteBuilder

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

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

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

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

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

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

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

AddJsonBody<TBuilder>(TBuilder, JsonTypeInfo, string)

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

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

AddJsonBody<TBuilder>(TBuilder, Type, string)

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

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeBuilder
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 routeBuilder instance.

Type Parameters

Name	Description
TBuilder

AddJsonErrorDetails<TBuilder>(TBuilder, bool)

Adds middleware that converts router exceptions into JSON ErrorDetails responses.

Declaration

public static TBuilder AddJsonErrorDetails<TBuilder>(this TBuilder routeBuilder, bool populateErrorInfo = false) where TBuilder : notnull, RouteBuilder

Parameters

Type	Name	Description
TBuilder	routeBuilder
bool	populateErrorInfo	true to include developer-facing diagnostic details when they are attached to the underlying exception; otherwise false.

Returns

Type	Description
TBuilder	The current routeBuilder 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.

Examples

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

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.

Json<T>(HttpStatusCode, T?)

Creates a JSON response using Web.

Declaration

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

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.

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.

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) where T : notnull

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

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) where T : notnull

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.

get_JsonTypeInfo()

Provides the JSON serialization meta-data.

Declaration

public static JsonTypeInfo<ErrorDetails> get_JsonTypeInfo()

Returns

Type	Description
JsonTypeInfo<ErrorDetails>