Class HttpResponseOptionsBuilderApiVersioningExtensions

Namespace

Trellis.Asp.ApiVersioning

Assembly

Trellis.Asp.ApiVersioning.dll

API-versioning extensions on HttpResponseOptionsBuilder<TDomain> that auto-inject a target-supported version into Location headers. Chain after any builder method that generates a Location header — CreatedAtRoute(...), CreatedAtAction(...), WithLocation(...), etc.

public static class HttpResponseOptionsBuilderApiVersioningExtensions

Inheritance

object

HttpResponseOptionsBuilderApiVersioningExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Resolution order (per request, inside the LinkGenerator callback):

1. HttpContext.RequestedApiVersion, if mapped to the destination endpoint.
2. Exactly one version mapped to the destination, respecting action-level mappings.
3. ApiVersioningOptions.DefaultApiVersion, only if mapped to the destination; otherwise throw InvalidOperationException.

Query-style injection uses "api-version", matching the default for QueryStringApiVersionReader and the conventional header name. Hosts using a non-default reader parameter name should register a custom resolver via WithRouteValueResolver(string, Func<HttpContext, string?>) directly.

Both overloads resolve the final named-route or MVC-action destination using endpoint routing. Missing or ambiguous destinations throw. Explicit pins must be mapped to the destination. URL-segment destinations receive the version in their actual :apiVersion parameter, not a duplicate query parameter. Neutral targets and targets without Asp.Versioning.ApiVersionMetadata omit version injection and remove a supplied api-version. The missing-metadata diagnostic identifies the destination endpoint.

Also applies to builder-generated fallbacks for WriteOutcome.Created with no nonblank Location. Explicit outcome locations and Accepted monitor URIs are not rewritten.

Methods

WithVersionedRoute<TDomain>(HttpResponseOptionsBuilder<TDomain>)

Injects a destination-supported version into the Location header emitted by a preceding CreatedAtRoute(string, Func<TDomain, RouteValueDictionary>), CreatedAtAction(string, Func<TDomain, RouteValueDictionary>, string?) or WithLocation(string, Func<TDomain, RouteValueDictionary>) call. The version is resolved per-request from HttpContext.

public static HttpResponseOptionsBuilder<TDomain> WithVersionedRoute<TDomain>(this HttpResponseOptionsBuilder<TDomain> builder)

Parameters

builder HttpResponseOptionsBuilder<TDomain>

The builder to configure.

Returns

HttpResponseOptionsBuilder<TDomain>

Type Parameters

TDomain

The domain value type from Result<TDomain> or a Created WriteOutcome<TDomain>.

Remarks

See the type-level remarks on HttpResponseOptionsBuilderApiVersioningExtensions for resolution and skip rules. Uses the target's URL-segment parameter when present, otherwise "api-version". Repeated calls replace the previous Location-route resolver.

WithVersionedRoute<TDomain>(HttpResponseOptionsBuilder<TDomain>, ApiVersion)

Escape hatch: pin the Location header to a specific Asp.Versioning.ApiVersion regardless of what the client requested. Use for cross-version Location redirects on deprecated endpoints.

public static HttpResponseOptionsBuilder<TDomain> WithVersionedRoute<TDomain>(this HttpResponseOptionsBuilder<TDomain> builder, ApiVersion explicitVersion)

Parameters

builder HttpResponseOptionsBuilder<TDomain>

The builder to configure.

explicitVersion ApiVersion

The destination-supported version to inject regardless of the requested version.

Returns

HttpResponseOptionsBuilder<TDomain>

Type Parameters

TDomain

The domain value type from Result<TDomain> or a Created WriteOutcome<TDomain>.

Remarks

Pins the query version or actual URL-segment parameter. Unsupported pins throw InvalidOperationException. Neutral and unversioned destinations omit the pin. Repeated calls replace the previous Location-route resolver.