Support API version in URL generation. Resolves #663

Author: Chris Martinez

samples/aspnetcore/BasicSample/Controllers/HelloWorldController.cs

@@ -14,10 +14,10 @@ public class HelloWorldController : ControllerBase
 
         // GET api/v{version}/helloworld/{id}
         [HttpGet( "{id:int}" )]
-        public IActionResult Get( int id, ApiVersion apiVersion ) => Ok( new { Controller = GetType().Name, Id = id, Version = apiVersion.ToString() } );
+        public IActionResult Get( int id, ApiVersion apiVersion ) => Ok( new { Controller = GetType().Name, Id = id } );
 
         // POST api/v{version}/helloworld
         [HttpPost]
-        public IActionResult Post( ApiVersion apiVersion ) => CreatedAtAction( nameof( Get ), new { id = 42, version = apiVersion.ToString() }, null );
+        public IActionResult Post( ApiVersion apiVersion ) => CreatedAtAction( nameof( Get ), new { id = 42 }, null );
     }
 }

samples/aspnetcore/SwaggerSample/V3/Controllers/PeopleController.cs

@@ -91,7 +91,7 @@ public IActionResult Get( int id ) =>
         public IActionResult Post( [FromBody] Person person, ApiVersion apiVersion )
         {
             person.Id = 42;
-            return CreatedAtAction( nameof( Get ), new { id = person.Id, version = apiVersion.ToString() }, person );
+            return CreatedAtAction( nameof( Get ), new { id = person.Id }, person );
         }
     }
 }

src/Common/Versioning/IApiVersionReaderExtensions.cs

@@ -11,21 +11,38 @@ namespace Microsoft.AspNetCore.Mvc.Versioning
 
     internal static class IApiVersionReaderExtensions
     {
+        internal static bool VersionsByUrlSegment( this IApiVersionReader reader )
+        {
+            var context = new UrlSegmentDescriptionContext();
+            reader.AddParameters( context );
+            return context.HasPathApiVersion;
+        }
+
         internal static bool VersionsByMediaType( this IApiVersionReader reader )
         {
-            var context = new DescriptionContext();
+            var context = new MediaTypeDescriptionContext();
             reader.AddParameters( context );
             return context.HasMediaTypeApiVersion;
         }
 
         internal static string GetMediaTypeVersionParameter( this IApiVersionReader reader )
         {
-            var context = new DescriptionContext();
+            var context = new MediaTypeDescriptionContext();
             reader.AddParameters( context );
             return context.ParameterName;
         }
 
-        sealed class DescriptionContext : IApiVersionParameterDescriptionContext
+        sealed class UrlSegmentDescriptionContext : IApiVersionParameterDescriptionContext
+        {
+            internal bool HasPathApiVersion { get; private set; }
+
+            public void AddParameter( string name, ApiVersionParameterLocation location )
+            {
+                HasPathApiVersion |= location == Path;
+            }
+        }
+
+        sealed class MediaTypeDescriptionContext : IApiVersionParameterDescriptionContext
         {
             readonly StringComparer comparer = StringComparer.OrdinalIgnoreCase;
             readonly List<string> parameterNames = new List<string>();

src/Microsoft.AspNet.OData.Versioning/Routing/VersionedODataPathRouteConstraint.cs

@@ -82,13 +82,7 @@ public override bool Match( HttpRequestMessage request, IHttpRoute route, string
                 return false;
             }
 
-            if ( ApiVersion == requestedVersion )
-            {
-                DecorateUrlHelperWithApiVersionRouteValueIfNecessary( request, values );
-                return true;
-            }
-
-            return false;
+            return ApiVersion == requestedVersion;
         }
 
         static ApiVersion? GetRequestedApiVersionOrReturnBadRequest( HttpRequestMessage request )
@@ -105,33 +99,5 @@ public override bool Match( HttpRequestMessage request, IHttpRoute route, string
                 throw new HttpResponseException( request.CreateResponse( BadRequest, error ) );
             }
         }
-
-        static void DecorateUrlHelperWithApiVersionRouteValueIfNecessary( HttpRequestMessage request, IDictionary<string, object> values )
-        {
-            object apiVersion;
-            string routeConstraintName;
-            var configuration = request.GetConfiguration();
-
-            if ( configuration == null )
-            {
-                routeConstraintName = nameof( apiVersion );
-            }
-            else
-            {
-                routeConstraintName = configuration.GetApiVersioningOptions().RouteConstraintName;
-            }
-
-            if ( !values.TryGetValue( routeConstraintName, out apiVersion ) )
-            {
-                return;
-            }
-
-            var requestContext = request.GetRequestContext();
-
-            if ( !( requestContext.Url is VersionedUrlHelperDecorator ) )
-            {
-                requestContext.Url = new VersionedUrlHelperDecorator( requestContext.Url, routeConstraintName, apiVersion );
-            }
-        }
     }
 }

src/Microsoft.AspNet.OData.Versioning/Routing/VersionedUrlHelperDecorator.cs

@@ -79,6 +79,7 @@ public virtual IDictionary<string, HttpControllerDescriptor> GetControllerMappin
 
                 if ( conventionRouteResult.Succeeded )
                 {
+                    EnsureUrlHelper( request );
                     return request.ApiVersionProperties().SelectedController = conventionRouteResult.Controller;
                 }
 
@@ -90,13 +91,15 @@ public virtual IDictionary<string, HttpControllerDescriptor> GetControllerMappin
 
             if ( directRouteResult.Succeeded )
             {
+                EnsureUrlHelper( request );
                 return request.ApiVersionProperties().SelectedController = directRouteResult.Controller;
             }
 
             conventionRouteResult = conventionRouteSelector.SelectController( context );
 
             if ( conventionRouteResult.Succeeded )
             {
+                EnsureUrlHelper( request );
                 return request.ApiVersionProperties().SelectedController = conventionRouteResult.Controller;
             }
 
@@ -293,5 +296,22 @@ static void EnsureRequestHasValidApiVersion( HttpRequestMessage request )
                 throw new HttpResponseException( response.BadRequest( request, AmbiguousApiVersion, ex.Message ) );
             }
         }
+
+        static void EnsureUrlHelper( HttpRequestMessage request )
+        {
+            var context = request.GetRequestContext();
+
+            if ( context == null || context.Url is ApiVersionUrlHelper )
+            {
+                return;
+            }
+
+            var options = request.GetApiVersioningOptions();
+
+            if ( options.ApiVersionReader.VersionsByUrlSegment() )
+            {
+                context.Url = new ApiVersionUrlHelper( context.Url );
+            }
+        }
     }
 }

src/Microsoft.AspNet.WebApi.Versioning/Dispatcher/ApiVersionControllerSelector.cs

@@ -47,6 +47,7 @@ public bool Match( HttpRequestMessage request, IHttpRoute route, string paramete
 
             var properties = request.ApiVersionProperties();
 
+            properties.RouteParameter = parameterName;
             properties.RawRequestedApiVersion = value;
 
             if ( TryParse( value, out var requestedVersion ) )

src/Microsoft.AspNet.WebApi.Versioning/Routing/ApiVersionRouteConstraint.cs

@@ -1,5 +1,6 @@
 namespace Microsoft.Web.Http.Versioning
 {
+    using Microsoft.Web.Http.Routing;
     using System.ComponentModel;
     using System.Net.Http;
     using System.Web.Http;
@@ -21,6 +22,14 @@ public class ApiVersionRequestProperties
         /// <param name="request">The current <see cref="HttpRequestMessage">HTTP request</see>.</param>
         public ApiVersionRequestProperties( HttpRequestMessage request ) => this.request = request;
 
+        /// <summary>
+        /// Gets or sets the name of the route parameter containing the API Version value.
+        /// </summary>
+        /// <value>The name of the API version route parameter or <c>null</c>.</value>
+        /// <remarks>This property will be <c>null</c> unless versioning by URL segment and the incoming request
+        /// matches the <see cref="ApiVersionRouteConstraint">API version route constraint</see>.</remarks>
+        public string? RouteParameter { get; set; }
+
         /// <summary>
         /// Gets or sets the raw, unparsed API version for the current request.
         /// </summary>

src/Microsoft.AspNet.WebApi.Versioning/Versioning/ApiVersionRequestProperties.cs

@@ -0,0 +1,79 @@
+namespace Microsoft.Web.Http.Versioning
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Web.Http;
+    using System.Web.Http.Routing;
+
+    /// <summary>
+    /// Represents an API version aware <see cref="UrlHelper">URL helper</see>.
+    /// </summary>
+    public class ApiVersionUrlHelper : UrlHelper
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ApiVersionUrlHelper"/> class.
+        /// </summary>
+        /// <param name="url">The inner <see cref="UrlHelper">URL helper</see>.</param>
+        public ApiVersionUrlHelper( UrlHelper url )
+        {
+            Url = url ?? throw new ArgumentNullException( nameof( url ) );
+
+            if ( url.Request != null )
+            {
+                Request = url.Request;
+            }
+        }
+
+        /// <summary>
+        /// Gets the inner URL helper.
+        /// </summary>
+        /// <value>The inner <see cref="UrlHelper">URL helper</see>.</value>
+        protected UrlHelper Url { get; }
+
+        /// <inheritdoc />
+        public override string Content( string path ) => Url.Content( path );
+
+        /// <inheritdoc />
+        public override string Link( string routeName, IDictionary<string, object> routeValues ) =>
+            Url.Link( routeName, AddApiVersionRouteValueIfNecessary( routeValues ) );
+
+        /// <inheritdoc />
+        public override string Route( string routeName, IDictionary<string, object> routeValues ) =>
+            Url.Route( routeName, AddApiVersionRouteValueIfNecessary( routeValues ) );
+
+        IDictionary<string, object>? AddApiVersionRouteValueIfNecessary( IDictionary<string, object>? routeValues )
+        {
+            if ( Request == null )
+            {
+                return routeValues;
+            }
+
+            var properties = Request.ApiVersionProperties();
+            var key = properties.RouteParameter;
+
+            if ( string.IsNullOrEmpty( key ) )
+            {
+                return routeValues;
+            }
+
+            var value = properties.RawRequestedApiVersion;
+
+            if ( string.IsNullOrEmpty( value ) )
+            {
+                return routeValues;
+            }
+
+            if ( routeValues == null )
+            {
+                return new HttpRouteValueDictionary() { [key!] = value! };
+            }
+
+            if ( !routeValues.ContainsKey( key! ) )
+            {
+                routeValues.Add( key!, value! );
+            }
+
+            return routeValues;
+        }
+    }
+}

src/Microsoft.AspNet.WebApi.Versioning/Versioning/ApiVersionUrlHelper.cs

@@ -11,6 +11,7 @@
     using Microsoft.Extensions.DependencyInjection.Extensions;
     using Microsoft.Extensions.Options;
     using System;
+    using System.Linq;
     using static ServiceDescriptor;
 
     /// <summary>
@@ -66,6 +67,7 @@ static void AddApiVersioningServices( IServiceCollection services )
             services.TryAddEnumerable( Transient<IApiControllerSpecification, ApiBehaviorSpecification>() );
             services.TryAddEnumerable( Singleton<MatcherPolicy, ApiVersionMatcherPolicy>() );
             services.AddTransient<IStartupFilter, AutoRegisterMiddleware>();
+            services.Replace( WithUrlHelperFactoryDecorator( services ) );
         }
 
         static IReportApiVersions OnRequestIReportApiVersions( IServiceProvider serviceProvider )
@@ -79,5 +81,39 @@ static IReportApiVersions OnRequestIReportApiVersions( IServiceProvider serviceP
 
             return new DoNotReportApiVersions();
         }
+
+        static object CreateInstance( this IServiceProvider services, ServiceDescriptor descriptor )
+        {
+            if ( descriptor.ImplementationInstance != null )
+            {
+                return descriptor.ImplementationInstance;
+            }
+
+            if ( descriptor.ImplementationFactory != null )
+            {
+                return descriptor.ImplementationFactory( services );
+            }
+
+            return ActivatorUtilities.GetServiceOrCreateInstance( services, descriptor.ImplementationType );
+        }
+
+        static ServiceDescriptor WithUrlHelperFactoryDecorator( IServiceCollection services )
+        {
+            var descriptor = services.First( sd => sd.ServiceType == typeof( IUrlHelperFactory ) );
+            var factory = ActivatorUtilities.CreateFactory( typeof( ApiVersionUrlHelperFactory ), new[] { typeof( IUrlHelperFactory ) } );
+
+            IUrlHelperFactory NewFactory( IServiceProvider serviceProvider )
+            {
+                var decorated = serviceProvider.CreateInstance( descriptor! );
+                var options = serviceProvider.GetRequiredService<IOptions<ApiVersioningOptions>>().Value;
+                var instance = options.ApiVersionReader.VersionsByUrlSegment() ?
+                    factory( serviceProvider, new[] { decorated } ) :
+                    decorated;
+
+                return (IUrlHelperFactory) instance;
+            }
+
+            return Describe( typeof( IUrlHelperFactory ), NewFactory, descriptor.Lifetime );
+        }
     }
 }

src/Microsoft.AspNetCore.Mvc.Versioning/Microsoft.Extensions.DependencyInjection/IServiceCollectionExtensions.cs

@@ -52,6 +52,7 @@ public bool Match( HttpContext httpContext, IRouter route, string routeKey, Rout
 
             var feature = httpContext.Features.Get<IApiVersioningFeature>();
 
+            feature.RouteParameter = routeKey;
             feature.RawRequestedApiVersion = value;
 
             if ( TryParse( value, out var requestedVersion ) )