Merge pull request #809 from dotnet-maestro-bot/merge/release/2.2-to-master

[automated] Merge branch 'release/2.2' => 'master'

Author: rynowak

src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerationTemplate.cs

@@ -9,7 +9,7 @@ namespace Microsoft.AspNetCore.Routing
     /// Defines a contract to generate a URL from a template.
     /// </summary>
     /// <remarks>
-    /// A <see cref="LinkGenerationTemplate"/> can be created from <see cref="LinkGenerator.GetTemplateByAddress{TAddress}(TAddress)"/>
+    /// A <see cref="LinkGenerationTemplate"/> can be created from <see cref="LinkGenerator.GetTemplateByAddress{TAddress}(TAddress, LinkGenerationTemplateOptions)"/>
     /// by supplying an address value which has matching endpoints. The returned <see cref="LinkGenerationTemplate"/>
     /// will be bound to the endpoints matching the address that was originally provided.
     /// </remarks>
@@ -20,6 +20,9 @@ public abstract class LinkGenerationTemplate
         /// </summary>
         /// <param name="httpContext">The <see cref="HttpContext"/> associated with the current request.</param>
         /// <param name="values">The route values. Used to expand parameters in the route template. Optional.</param>
+        /// <param name="pathBase">
+        /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
+        /// </param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
         /// An optional <see cref="LinkOptions"/>. Settings on provided object override the settings with matching
@@ -29,6 +32,7 @@ public abstract class LinkGenerationTemplate
         public abstract string GetPath(
             HttpContext httpContext,
             object values,
+            PathString? pathBase = default,
             FragmentString fragment = default,
             LinkOptions options = default);
 
@@ -54,6 +58,15 @@ public abstract string GetPath(
         /// </summary>
         /// <param name="httpContext">The <see cref="HttpContext"/> associated with the current request.</param>
         /// <param name="values">The route values. Used to expand parameters in the route template. Optional.</param>
+        /// <param name="scheme">
+        /// The URI scheme, applied to the resulting URI. Optional. If not provided, the value of <see cref="HttpRequest.Scheme"/> will be used.
+        /// </param>
+        /// <param name="host">
+        /// The URI host/authority, applied to the resulting URI. Optional. If not provided, the value <see cref="HttpRequest.Host"/> will be used.
+        /// </param>
+        /// <param name="pathBase">
+        /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
+        /// </param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
         /// An optional <see cref="LinkOptions"/>. Settings on provided object override the settings with matching
@@ -63,6 +76,9 @@ public abstract string GetPath(
         public abstract string GetUri(
             HttpContext httpContext,
             object values,
+            string scheme = default,
+            HostString? host = default,
+            PathString? pathBase = default,
             FragmentString fragment = default,
             LinkOptions options = default);
 

src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerationTemplateOptions.cs

@@ -0,0 +1,17 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+namespace Microsoft.AspNetCore.Routing
+{
+    /// <summary>
+    /// Contains options for creating a <see cref="LinkGenerationTemplate" />.
+    /// </summary>
+    public class LinkGenerationTemplateOptions
+    {
+        /// <summary>
+        /// Gets or sets a value indicating whether the template will use route values from the current request
+        /// when generating a URI.
+        /// </summary>
+        public bool UseAmbientValues { get; set; }
+    }
+}

src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerator.cs

@@ -25,12 +25,16 @@ namespace Microsoft.AspNetCore.Routing
     public abstract class LinkGenerator
     {
         /// <summary>
-        /// Generates a URI with an absolute path based on the provided values.
+        /// Generates a URI with an absolute path based on the provided values and <see cref="HttpContext"/>.
         /// </summary>
         /// <typeparam name="TAddress">The address type.</typeparam>
         /// <param name="httpContext">The <see cref="HttpContext"/> associated with the current request.</param>
         /// <param name="address">The address value. Used to resolve endpoints.</param>
         /// <param name="values">The route values. Used to expand parameters in the route template. Optional.</param>
+        /// <param name="ambientValues">The values associated with the current request. Optional.</param>
+        /// <param name="pathBase">
+        /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
+        /// </param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
         /// An optional <see cref="LinkOptions"/>. Settings on provided object override the settings with matching
@@ -41,6 +45,8 @@ public abstract string GetPathByAddress<TAddress>(
             HttpContext httpContext,
             TAddress address,
             RouteValueDictionary values,
+            RouteValueDictionary ambientValues = default,
+            PathString? pathBase = default,
             FragmentString fragment = default,
             LinkOptions options = default);
 
@@ -65,12 +71,22 @@ public abstract string GetPathByAddress<TAddress>(
             LinkOptions options = default);
 
         /// <summary>
-        /// Generates an absolute URI based on the provided values.
+        /// Generates an absolute URI based on the provided values and <see cref="HttpContext"/>.
         /// </summary>
         /// <typeparam name="TAddress">The address type.</typeparam>
         /// <param name="httpContext">The <see cref="HttpContext"/> associated with the current request.</param>
         /// <param name="address">The address value. Used to resolve endpoints.</param>
         /// <param name="values">The route values. Used to expand parameters in the route template. Optional.</param>
+        /// <param name="ambientValues">The values associated with the current request. Optional.</param>
+        /// <param name="scheme">
+        /// The URI scheme, applied to the resulting URI. Optional. If not provided, the value of <see cref="HttpRequest.Scheme"/> will be used.
+        /// </param>
+        /// <param name="host">
+        /// The URI host/authority, applied to the resulting URI. Optional. If not provided, the value <see cref="HttpRequest.Host"/> will be used.
+        /// </param>
+        /// <param name="pathBase">
+        /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
+        /// </param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
         /// An optional <see cref="LinkOptions"/>. Settings on provided object override the settings with matching
@@ -81,6 +97,10 @@ public abstract string GetUriByAddress<TAddress>(
             HttpContext httpContext,
             TAddress address,
             RouteValueDictionary values,
+            RouteValueDictionary ambientValues = default,
+            string scheme = default,
+            HostString? host = default,
+            PathString? pathBase = default,
             FragmentString fragment = default,
             LinkOptions options = default);
 
@@ -113,9 +133,10 @@ public abstract string GetUriByAddress<TAddress>(
         /// </summary>
         /// <typeparam name="TAddress">The address type.</typeparam>
         /// <param name="address">The address value. Used to resolve endpoints.</param>
+        /// <param name="options">Options for the created <see cref="LinkGenerationTemplate"/>.</param>
         /// <returns>
         /// A <see cref="LinkGenerationTemplate"/> if one or more endpoints matching the address can be found, otherwise <c>null</c>.
         /// </returns>
-        public abstract LinkGenerationTemplate GetTemplateByAddress<TAddress>(TAddress address);
+        public abstract LinkGenerationTemplate GetTemplateByAddress<TAddress>(TAddress address, LinkGenerationTemplateOptions options = null);
     }
 }

src/Microsoft.AspNetCore.Routing/DefaultLinkGenerationTemplate.cs

@@ -1,29 +1,33 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using Microsoft.AspNetCore.Http;
 using System;
 using System.Collections.Generic;
-using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Routing
 {
     internal sealed class DefaultLinkGenerationTemplate : LinkGenerationTemplate
     {
-        public DefaultLinkGenerationTemplate(DefaultLinkGenerator linkGenerator, List<RouteEndpoint> endpoints)
+        public DefaultLinkGenerationTemplate(DefaultLinkGenerator linkGenerator, List<RouteEndpoint> endpoints, LinkGenerationTemplateOptions options)
         {
             LinkGenerator = linkGenerator;
             Endpoints = endpoints;
+            Options = options;
         }
 
         public DefaultLinkGenerator LinkGenerator { get; }
 
         public List<RouteEndpoint> Endpoints { get; }
 
+        public LinkGenerationTemplateOptions Options { get; }
+
         public override string GetPath(
             HttpContext httpContext,
             object values,
+            PathString? pathBase = default,
             FragmentString fragment = default,
-            LinkOptions options = null)
+            LinkOptions options = default)
         {
             if (httpContext == null)
             {
@@ -32,9 +36,9 @@ public override string GetPath(
 
             return LinkGenerator.GetPathByEndpoints(
                 Endpoints,
-                DefaultLinkGenerator.GetAmbientValues(httpContext),
                 new RouteValueDictionary(values),
-                httpContext.Request.PathBase,
+                GetAmbientValues(httpContext),
+                pathBase ?? httpContext.Request.PathBase,
                 fragment,
                 options);
         }
@@ -43,22 +47,25 @@ public override string GetPath(
             object values,
             PathString pathBase = default,
             FragmentString fragment = default,
-            LinkOptions options = null)
+            LinkOptions options = default)
         {
             return LinkGenerator.GetPathByEndpoints(
                 Endpoints,
-                ambientValues: null,
                 new RouteValueDictionary(values),
-                pathBase,
-                fragment,
-                options);
+                ambientValues: null,
+                pathBase: pathBase,
+                fragment: fragment,
+                options: options);
         }
 
         public override string GetUri(
             HttpContext httpContext,
             object values,
+            string scheme = default,
+            HostString? host = default,
+            PathString? pathBase = default,
             FragmentString fragment = default,
-            LinkOptions options = null)
+            LinkOptions options = default)
         {
             if (httpContext == null)
             {
@@ -67,11 +74,11 @@ public override string GetUri(
 
             return LinkGenerator.GetUriByEndpoints(
                 Endpoints,
-                DefaultLinkGenerator.GetAmbientValues(httpContext),
                 new RouteValueDictionary(values),
-                httpContext.Request.Scheme,
-                httpContext.Request.Host,
-                httpContext.Request.PathBase,
+                GetAmbientValues(httpContext),
+                scheme ?? httpContext.Request.Scheme,
+                host ?? httpContext.Request.Host,
+                pathBase ?? httpContext.Request.PathBase,
                 fragment,
                 options);
         }
@@ -82,17 +89,32 @@ public override string GetUri(
             HostString host,
             PathString pathBase = default,
             FragmentString fragment = default,
-            LinkOptions options = null)
+            LinkOptions options = default)
         {
+            if (string.IsNullOrEmpty(scheme))
+            {
+                throw new ArgumentException("A scheme must be provided.", nameof(scheme));
+            }
+
+            if (!host.HasValue)
+            {
+                throw new ArgumentException("A host must be provided.", nameof(host));
+            }
+
             return LinkGenerator.GetUriByEndpoints(
                 Endpoints,
-                ambientValues: null,
                 new RouteValueDictionary(values),
-                scheme,
-                host,
-                pathBase,
-                fragment,
-                options);
+                ambientValues: null,
+                scheme: scheme,
+                host: host,
+                pathBase: pathBase,
+                fragment: fragment,
+                options: options);
+        }
+
+        private RouteValueDictionary GetAmbientValues(HttpContext httpContext)
+        {
+            return (Options?.UseAmbientValues ?? false) ? DefaultLinkGenerator.GetAmbientValues(httpContext) : null;
         }
     }
 }