From 15f25d569aabe8de9acf1b7fa974b803c284aec8 Mon Sep 17 00:00:00 2001 From: Doug Bunting Date: Thu, 30 Jun 2016 14:38:43 -0700 Subject: [PATCH] Improve `IUrlHelper` and related doc comments - #4245, #4507 --- .../IUrlHelper.cs | 34 ++++--- .../Routing/UrlActionContext.cs | 4 +- .../Routing/UrlRouteContext.cs | 5 +- .../Routing/UrlHelper.cs | 30 +++++-- .../UrlHelperExtensions.cs | 89 +++++++++++-------- 5 files changed, 98 insertions(+), 64 deletions(-) diff --git a/src/Microsoft.AspNetCore.Mvc.Abstractions/IUrlHelper.cs b/src/Microsoft.AspNetCore.Mvc.Abstractions/IUrlHelper.cs index e39e51c813..fc329aadc4 100644 --- a/src/Microsoft.AspNetCore.Mvc.Abstractions/IUrlHelper.cs +++ b/src/Microsoft.AspNetCore.Mvc.Abstractions/IUrlHelper.cs @@ -16,11 +16,13 @@ namespace Microsoft.AspNetCore.Mvc ActionContext ActionContext { get; } /// - /// Generates a fully qualified or absolute URL specified by for an action - /// method, which contains action name, controller name, route values, protocol to use, host name, and fragment. + /// Generates a URL with an absolute path for an action method, which contains the action + /// name, controller name, route values, protocol to use, host name, and fragment specified by + /// . Generates an absolute URL if and + /// are non-null. /// /// The context object for the generated URLs for an action method. - /// The fully qualified or absolute URL to an action method. + /// The generated URL. string Action(UrlActionContext actionContext); /// @@ -35,43 +37,47 @@ namespace Microsoft.AspNetCore.Mvc string Content(string contentPath); /// - /// Returns a value that indicates whether the URL is local. A URL with an absolute path is considered local - /// if it does not have a host/authority part. URLs using virtual paths ('~/') are also local. + /// Returns a value that indicates whether the URL is local. A URL is considered local if it does not have a + /// host / authority part and it has an absolute path. URLs using virtual paths ('~/') are also local. /// /// The URL. /// true if the URL is local; otherwise, false. /// /// /// For example, the following URLs are considered local: + /// /// /Views/Default/Index.html /// ~/Index.html + /// /// /// /// The following URLs are non-local: + /// /// ../Index.html /// http://www.contoso.com/ /// http://localhost/Index.html + /// /// /// bool IsLocalUrl(string url); /// - /// Generates a fully qualified or absolute URL specified by , which - /// contains the route name, the route values, protocol to use, host name and fragment. + /// Generates a URL with an absolute path, which contains the route name, route values, protocol to use, host + /// name, and fragment specified by . Generates an absolute URL if + /// and are non-null. /// /// The context object for the generated URLs for a route. - /// The fully qualified or absolute URL. + /// The generated URL. string RouteUrl(UrlRouteContext routeContext); /// - /// Generates an absolute URL using the specified route name and values. + /// Generates an absolute URL for the specified and route + /// , which contains the protocol (such as "http" or "https") and host name from the + /// current request. /// - /// The name of the route that is used to generate the URL. - /// An object that contains the route values. + /// The name of the route that is used to generate URL. + /// An object that contains route values. /// The generated absolute URL. - /// - /// The protocol and host is obtained from the current request. - /// string Link(string routeName, object values); } } diff --git a/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlActionContext.cs b/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlActionContext.cs index e09ecf1197..8260b6b680 100644 --- a/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlActionContext.cs +++ b/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlActionContext.cs @@ -27,7 +27,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing } /// - /// The object that contains the route parameters that + /// The object that contains the route values that /// uses to generate URLs. /// public object Values @@ -37,7 +37,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing } /// - /// The protocol for the URLs that generates + /// The protocol for the URLs that generates, /// such as "http" or "https" /// public string Protocol diff --git a/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlRouteContext.cs b/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlRouteContext.cs index f2844c8ebb..706414f958 100644 --- a/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlRouteContext.cs +++ b/src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlRouteContext.cs @@ -18,7 +18,8 @@ namespace Microsoft.AspNetCore.Mvc.Routing } /// - /// The object that contains the route values for the generated URLs. + /// The object that contains the route values that + /// uses to generate URLs. /// public object Values { @@ -27,7 +28,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing } /// - /// The protocol for the URLs that generates + /// The protocol for the URLs that generates, /// such as "http" or "https" /// public string Protocol diff --git a/src/Microsoft.AspNetCore.Mvc.Core/Routing/UrlHelper.cs b/src/Microsoft.AspNetCore.Mvc.Core/Routing/UrlHelper.cs index d60a3d6974..418eea5360 100644 --- a/src/Microsoft.AspNetCore.Mvc.Core/Routing/UrlHelper.cs +++ b/src/Microsoft.AspNetCore.Mvc.Core/Routing/UrlHelper.cs @@ -23,8 +23,8 @@ namespace Microsoft.AspNetCore.Mvc.Routing private readonly RouteValueDictionary _routeValueDictionary; /// - /// Initializes a new instance of the class using the specified action context and - /// action selector. + /// Initializes a new instance of the class using the specified + /// . /// /// The for the current request. public UrlHelper(ActionContext actionContext) @@ -41,10 +41,20 @@ namespace Microsoft.AspNetCore.Mvc.Routing /// public ActionContext ActionContext { get; } + /// + /// Gets the associated with the current request. + /// protected RouteValueDictionary AmbientValues => ActionContext.RouteData.Values; + /// + /// Gets the associated with the current request. + /// protected HttpContext HttpContext => ActionContext.HttpContext; + /// + /// Gets the top-level associated with the current request. Generally an + /// implementation. + /// protected IRouter Router => ActionContext.RouteData.Routers[0]; /// @@ -116,11 +126,15 @@ namespace Microsoft.AspNetCore.Mvc.Routing } /// - /// Gets the for the specified route values by using the specified route name. + /// Gets the for the specified and route + /// . /// /// The name of the route that is used to generate the . /// - /// A dictionary that contains the parameters for a route. + /// + /// The . The uses these values, in combination with + /// , to generate the URL. + /// /// The . protected virtual VirtualPathData GetVirtualPathData(string routeName, RouteValueDictionary values) { @@ -253,10 +267,10 @@ namespace Microsoft.AspNetCore.Mvc.Routing /// /// Generates the URL using the specified components. /// - /// The protocol. - /// The host. + /// The protocol for the URL, such as "http" or "https". + /// The host name for the URL. /// The . - /// The URL fragment. + /// The fragment for the URL. /// The generated URL. protected virtual string GenerateUrl(string protocol, string host, VirtualPathData pathData, string fragment) { @@ -268,7 +282,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing // VirtualPathData.VirtualPath returns string.Empty instead of null. Debug.Assert(pathData.VirtualPath != null); - // Perf: In most of the common cases, GenerateUrl is called with a null protocol, host and fragment. + // Perf: In most of the common cases, GenerateUrl is called with a null protocol, host and fragment. // In such cases, we might not need to build any URL as the url generated is mostly same as the virtual path available in pathData. // For such common cases, this FastGenerateUrl method saves a string allocation per GenerateUrl call. string url; diff --git a/src/Microsoft.AspNetCore.Mvc.Core/UrlHelperExtensions.cs b/src/Microsoft.AspNetCore.Mvc.Core/UrlHelperExtensions.cs index ff7bab72c4..87f42790dc 100644 --- a/src/Microsoft.AspNetCore.Mvc.Core/UrlHelperExtensions.cs +++ b/src/Microsoft.AspNetCore.Mvc.Core/UrlHelperExtensions.cs @@ -9,9 +9,10 @@ namespace Microsoft.AspNetCore.Mvc public static class UrlHelperExtensions { /// - /// Generates a fully qualified or absolute URL for an action method. + /// Generates a URL with an absolute path for an action method. /// - /// The fully qualified or absolute URL to an action method. + /// The . + /// The generated URL. public static string Action(this IUrlHelper helper) { if (helper == null) @@ -29,11 +30,12 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for an action method by using the specified action name. + /// Generates a URL with an absolute path for an action method, which contains the specified + /// name. /// /// The . /// The name of the action method. - /// The fully qualified or absolute URL to an action method. + /// The generated URL. public static string Action(this IUrlHelper helper, string action) { if (helper == null) @@ -45,13 +47,13 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for an action method by using the specified action name, - /// and route values. + /// Generates a URL with an absolute path for an action method, which contains the specified + /// name and route . /// /// The . /// The name of the action method. /// An object that contains route values. - /// The fully qualified or absolute URL to an action method. + /// The generated URL. public static string Action(this IUrlHelper helper, string action, object values) { if (helper == null) @@ -63,13 +65,13 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for an action method by using the specified action name, - /// and controller name. + /// Generates a URL with an absolute path for an action method, which contains the specified + /// and names. /// /// The . /// The name of the action method. /// The name of the controller. - /// The fully qualified or absolute URL to an action method. + /// The generated URL. public static string Action(this IUrlHelper helper, string action, string controller) { if (helper == null) @@ -81,14 +83,14 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for an action method by using the specified action name, - /// controller name, and route values. + /// Generates a URL with an absolute path for an action method, which contains the specified + /// name, name, and route . /// /// The . /// The name of the action method. /// The name of the controller. /// An object that contains route values. - /// The fully qualified or absolute URL to an action method. + /// The generated URL. public static string Action(this IUrlHelper helper, string action, string controller, object values) { if (helper == null) @@ -100,15 +102,16 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for an action method by using the specified action name, - /// controller name, route values, and protocol to use. + /// Generates a URL with an absolute path for an action method, which contains the specified + /// name, name, route , and + /// to use. /// /// The . /// The name of the action method. /// The name of the controller. /// An object that contains route values. /// The protocol for the URL, such as "http" or "https". - /// The fully qualified or absolute URL to an action method. + /// The generated URL. public static string Action( this IUrlHelper helper, string action, @@ -125,8 +128,11 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for an action method by using the specified action name, - /// controller name, route values, protocol to use, and host name. + /// Generates a URL with an absolute path for an action method, which contains the specified + /// name, name, route , + /// to use, and name. + /// Generates an absolute URL if the and are + /// non-null. /// /// The . /// The name of the action method. @@ -134,7 +140,7 @@ namespace Microsoft.AspNetCore.Mvc /// An object that contains route values. /// The protocol for the URL, such as "http" or "https". /// The host name for the URL. - /// The fully qualified or absolute URL to an action method. + /// The generated URL. public static string Action( this IUrlHelper helper, string action, @@ -152,8 +158,11 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for an action method by using the specified action name, - /// controller name, route values, protocol to use, host name and fragment. + /// Generates a URL with an absolute path for an action method, which contains the specified + /// name, name, route , + /// to use, name, and . + /// Generates an absolute URL if the and are + /// non-null. /// /// The . /// The name of the action method. @@ -162,7 +171,7 @@ namespace Microsoft.AspNetCore.Mvc /// The protocol for the URL, such as "http" or "https". /// The host name for the URL. /// The fragment for the URL. - /// The fully qualified or absolute URL to an action method. + /// The generated URL. public static string Action( this IUrlHelper helper, string action, @@ -189,11 +198,11 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for the specified route values. + /// Generates a URL with an absolute path for the specified route . /// /// The . /// An object that contains route values. - /// The fully qualified or absolute URL. + /// The generated URL. public static string RouteUrl(this IUrlHelper helper, object values) { if (helper == null) @@ -205,11 +214,11 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for the specified route name. + /// Generates a URL with an absolute path for the specified . /// /// The . /// The name of the route that is used to generate URL. - /// The fully qualified or absolute URL. + /// The generated URL. public static string RouteUrl(this IUrlHelper helper, string routeName) { if (helper == null) @@ -221,13 +230,13 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for the specified route values by - /// using the specified route name. + /// Generates a URL with an absolute path for the specified and route + /// . /// /// The . /// The name of the route that is used to generate URL. /// An object that contains route values. - /// The fully qualified or absolute URL. + /// The generated URL. public static string RouteUrl(this IUrlHelper helper, string routeName, object values) { if (helper == null) @@ -239,14 +248,14 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for the specified route values by - /// using the specified route name, and protocol to use. + /// Generates a URL with an absolute path for the specified route and route + /// , which contains the specified to use. /// /// The . /// The name of the route that is used to generate URL. /// An object that contains route values. /// The protocol for the URL, such as "http" or "https". - /// The fully qualified or absolute URL. + /// The generated URL. public static string RouteUrl( this IUrlHelper helper, string routeName, @@ -262,15 +271,17 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for the specified route values by - /// using the specified route name, protocol to use, and host name. + /// Generates a URL with an absolute path for the specified route and route + /// , which contains the specified to use and + /// name. Generates an absolute URL if + /// and are non-null. /// /// The . /// The name of the route that is used to generate URL. /// An object that contains route values. /// The protocol for the URL, such as "http" or "https". /// The host name for the URL. - /// The fully qualified or absolute URL. + /// The generated URL. public static string RouteUrl( this IUrlHelper helper, string routeName, @@ -287,8 +298,10 @@ namespace Microsoft.AspNetCore.Mvc } /// - /// Generates a fully qualified or absolute URL for the specified route values by - /// using the specified route name, protocol to use, host name and fragment. + /// Generates a URL with an absolute path for the specified route and route + /// , which contains the specified to use, + /// name and . Generates an absolute URL if + /// and are non-null. /// /// The . /// The name of the route that is used to generate URL. @@ -296,7 +309,7 @@ namespace Microsoft.AspNetCore.Mvc /// The protocol for the URL, such as "http" or "https". /// The host name for the URL. /// The fragment for the URL. - /// The fully qualified or absolute URL. + /// The generated URL. public static string RouteUrl( this IUrlHelper helper, string routeName,