Support suppressing API version in generated URLs

Author: commonsensesoftware

Diff for: src/AspNet/WebApi/src/Asp.Versioning.WebApi/Routing/ApiVersionUrlHelper.cs

@@ -1,6 +1,6 @@
 // Copyright (c) .NET Foundation and contributors. All rights reserved.
 
-namespace Asp.Versioning;
+namespace Asp.Versioning.Routing;
 
 using System.Web.Http.Routing;
 
@@ -32,10 +32,18 @@ public ApiVersionUrlHelper( UrlHelper url )
     /// <inheritdoc />
     public override string Content( string path ) => Url.Content( path );
 
+    /// <inheritdoc />
+    public override string Link( string routeName, object routeValues ) =>
+        Url.Link( routeName, AddApiVersionRouteValueIfNecessary( new HttpRouteValueDictionary( routeValues ) ) );
+
     /// <inheritdoc />
     public override string Link( string routeName, IDictionary<string, object> routeValues ) =>
         Url.Link( routeName, AddApiVersionRouteValueIfNecessary( routeValues ) );
 
+    /// <inheritdoc />
+    public override string Route( string routeName, object routeValues ) =>
+        Url.Route( routeName, AddApiVersionRouteValueIfNecessary( new HttpRouteValueDictionary( routeValues ) ) );
+
     /// <inheritdoc />
     public override string Route( string routeName, IDictionary<string, object> routeValues ) =>
         Url.Route( routeName, AddApiVersionRouteValueIfNecessary( routeValues ) );

Diff for: src/AspNet/WebApi/src/Asp.Versioning.WebApi/Routing/UrlHelperExtensions.cs

@@ -0,0 +1,37 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace System.Web.Http.Routing;
+
+using Asp.Versioning.Routing;
+
+/// <summary>
+/// Provides extension methods for <see cref="UrlHelper"/>.
+/// </summary>
+public static class UrlHelperExtensions
+{
+    /// <summary>
+    /// Returns a new URL helper that includes the requested API version.
+    /// </summary>
+    /// <param name="urlHelper">The extended <see cref="UrlHelper">URL helper</see>.</param>
+    /// <returns>A new <see cref="UrlHelper">URL helper</see> that excludes the requested
+    /// API version or the original <paramref name="urlHelper">URL helper</paramref> if
+    /// unnecessary.</returns>
+    /// <remarks>Excluding the requested API version is useful in a limited set of scenarios
+    /// such as building a URL from an API that versions by URL segment to an API that is
+    /// version-neutral. A version-neutral API would not use the specified route value and
+    /// it would be erroneously added as a query string parameter.</remarks>
+    public static UrlHelper WithoutApiVersion( this UrlHelper urlHelper )
+    {
+        if ( urlHelper == null )
+        {
+            throw new ArgumentNullException( nameof( urlHelper ) );
+        }
+
+        if ( urlHelper is WithoutApiVersionUrlHelper )
+        {
+            return urlHelper;
+        }
+
+        return new WithoutApiVersionUrlHelper( urlHelper );
+    }
+}

Diff for: src/AspNet/WebApi/src/Asp.Versioning.WebApi/Routing/WithoutApiVersionUrlHelper.cs

@@ -0,0 +1,85 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning.Routing;
+
+using System;
+using System.Collections.Generic;
+using System.Web.Http.Routing;
+
+internal sealed class WithoutApiVersionUrlHelper : UrlHelper
+{
+    private readonly UrlHelper decorated;
+
+    public WithoutApiVersionUrlHelper( UrlHelper decorated ) => this.decorated = decorated;
+
+    private ApiVersionRequestProperties Properties => decorated.Request.ApiVersionProperties();
+
+    public override string Content( string path )
+    {
+        using ( new NoApiVersionScope( Properties ) )
+        {
+            return decorated.Content( path );
+        }
+    }
+
+    public override string Link( string routeName, object routeValues )
+    {
+        using ( new NoApiVersionScope( Properties ) )
+        {
+            return decorated.Link( routeName, routeValues );
+        }
+    }
+
+    public override string Link( string routeName, IDictionary<string, object> routeValues )
+    {
+        using ( new NoApiVersionScope( Properties ) )
+        {
+            return decorated.Link( routeName, routeValues );
+        }
+    }
+
+    public override string Route( string routeName, object routeValues )
+    {
+        using ( new NoApiVersionScope( Properties ) )
+        {
+            return decorated.Route( routeName, routeValues );
+        }
+    }
+
+    public override string Route( string routeName, IDictionary<string, object> routeValues )
+    {
+        using ( new NoApiVersionScope( Properties ) )
+        {
+            return decorated.Route( routeName, routeValues );
+        }
+    }
+
+    private sealed class NoApiVersionScope : IDisposable
+    {
+        private readonly ApiVersionRequestProperties properties;
+        private readonly string? rawVersion;
+        private readonly ApiVersion? version;
+        private bool disposed;
+
+        public NoApiVersionScope( ApiVersionRequestProperties properties )
+        {
+            this.properties = properties;
+            rawVersion = properties.RawRequestedApiVersion;
+            version = properties.RequestedApiVersion;
+            properties.RawRequestedApiVersion = default;
+            properties.RequestedApiVersion = default;
+        }
+
+        public void Dispose()
+        {
+            if ( disposed )
+            {
+                return;
+            }
+
+            disposed = true;
+            properties.RawRequestedApiVersion = rawVersion;
+            properties.RequestedApiVersion = version;
+        }
+    }
+}