huahaofeng
/
aspnetcore
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve `IUrlHelper` and related doc comments 

- #4245, #4507
This commit is contained in:
Doug Bunting 2016-06-30 14:38:43 -07:00
parent 42cea41737
commit 15f25d569a
5 changed files with 98 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
src/Microsoft.AspNetCore.Mvc.Abstractions/IUrlHelper.cs
View File

@ -16,11 +16,13 @@ namespace Microsoft.AspNetCore.Mvc
ActionContext ActionContext { get; }
/// <summary>
/// Generates a fully qualified or absolute URL specified by <see cref="UrlActionContext"/> 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
/// <see cref="UrlActionContext"/>. Generates an absolute URL if <see cref="UrlActionContext.Protocol"/> and
/// <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
/// </summary>
/// <param name="actionContext">The context object for the generated URLs for an action method.</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
string Action(UrlActionContext actionContext);
/// <summary>
@ -35,43 +37,47 @@ namespace Microsoft.AspNetCore.Mvc
string Content(string contentPath);
/// <summary>
/// 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.
/// </summary>
/// <param name="url">The URL.</param>
/// <returns><c>true</c> if the URL is local; otherwise, <c>false</c>.</returns>
/// <example>
/// <para>
/// For example, the following URLs are considered local:
/// <code>
/// /Views/Default/Index.html
/// ~/Index.html
/// </code>
/// </para>
/// <para>
/// The following URLs are non-local:
/// <code>
/// ../Index.html
/// http://www.contoso.com/
/// http://localhost/Index.html
/// </code>
/// </para>
/// </example>
bool IsLocalUrl(string url);
/// <summary>
/// Generates a fully qualified or absolute URL specified by <see cref="UrlRouteContext"/>, 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 <see cref="UrlRouteContext"/>. Generates an absolute URL if
/// <see cref="UrlActionContext.Protocol"/> and <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
/// </summary>
/// <param name="routeContext">The context object for the generated URLs for a route.</param>
/// <returns>The fully qualified or absolute URL.</returns>
/// <returns>The generated URL.</returns>
string RouteUrl(UrlRouteContext routeContext);
/// <summary>
/// Generates an absolute URL using the specified route name and values.
/// Generates an absolute URL for the specified <paramref name="routeName"/> and route
/// <paramref name="values"/>, which contains the protocol (such as "http" or "https") and host name from the
/// current request.
/// </summary>
/// <param name="routeName">The name of the route that is used to generate the URL.</param>
/// <param name="values">An object that contains the route values.</param>
/// <param name="routeName">The name of the route that is used to generate URL.</param>
/// <param name="values">An object that contains route values.</param>
/// <returns>The generated absolute URL.</returns>
/// <remarks>
/// The protocol and host is obtained from the current request.
/// </remarks>
string Link(string routeName, object values);
}
}

4
src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlActionContext.cs
View File

@ -27,7 +27,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing
}
/// <summary>
/// The object that contains the route parameters that <see cref="IUrlHelper.Action(UrlActionContext)"/>
/// The object that contains the route values that <see cref="IUrlHelper.Action(UrlActionContext)"/>
/// uses to generate URLs.
/// </summary>
public object Values
@ -37,7 +37,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing
}
/// <summary>
/// The protocol for the URLs that <see cref="IUrlHelper.Action(UrlActionContext)"/> generates
/// The protocol for the URLs that <see cref="IUrlHelper.Action(UrlActionContext)"/> generates,
/// such as "http" or "https"
/// </summary>
public string Protocol

5
src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlRouteContext.cs
View File

@ -18,7 +18,8 @@ namespace Microsoft.AspNetCore.Mvc.Routing
}
/// <summary>
/// The object that contains the route values for the generated URLs.
/// The object that contains the route values that <see cref="IUrlHelper.RouteUrl(UrlRouteContext)"/>
/// uses to generate URLs.
/// </summary>
public object Values
{
@ -27,7 +28,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing
}
/// <summary>
/// The protocol for the URLs that <see cref="IUrlHelper.RouteUrl(UrlRouteContext)"/> generates
/// The protocol for the URLs that <see cref="IUrlHelper.RouteUrl(UrlRouteContext)"/> generates,
/// such as "http" or "https"
/// </summary>
public string Protocol

30
src/Microsoft.AspNetCore.Mvc.Core/Routing/UrlHelper.cs
View File

@ -23,8 +23,8 @@ namespace Microsoft.AspNetCore.Mvc.Routing
private readonly RouteValueDictionary _routeValueDictionary;
/// <summary>
/// Initializes a new instance of the <see cref="UrlHelper"/> class using the specified action context and
/// action selector.
/// Initializes a new instance of the <see cref="UrlHelper"/> class using the specified
/// <paramref name="actionContext"/>.
/// </summary>
/// <param name="actionContext">The <see cref="Mvc.ActionContext"/> for the current request.</param>
public UrlHelper(ActionContext actionContext)
@ -41,10 +41,20 @@ namespace Microsoft.AspNetCore.Mvc.Routing
/// <inheritdoc />
public ActionContext ActionContext { get; }
/// <summary>
/// Gets the <see cref="RouteValueDictionary"/> associated with the current request.
/// </summary>
protected RouteValueDictionary AmbientValues => ActionContext.RouteData.Values;
/// <summary>
/// Gets the <see cref="Http.HttpContext"/> associated with the current request.
/// </summary>
protected HttpContext HttpContext => ActionContext.HttpContext;
/// <summary>
/// Gets the top-level <see cref="IRouter"/> associated with the current request. Generally an
/// <see cref="IRouteCollection"/> implementation.
/// </summary>
protected IRouter Router => ActionContext.RouteData.Routers[0];
/// <inheritdoc />
@ -116,11 +126,15 @@ namespace Microsoft.AspNetCore.Mvc.Routing
}
/// <summary>
/// Gets the <see cref="VirtualPathData"/> for the specified route values by using the specified route name.
/// Gets the <see cref="VirtualPathData"/> for the specified <paramref name="routeName"/> and route
/// <paramref name="values"/>.
/// </summary>
/// <param name="routeName">The name of the route that is used to generate the <see cref="VirtualPathData"/>.
/// </param>
/// <param name="values">A dictionary that contains the parameters for a route.</param>
/// <param name="values">
/// The <see cref="RouteValueDictionary"/>. The <see cref="Router"/> uses these values, in combination with
/// <see cref="AmbientValues"/>, to generate the URL.
/// </param>
/// <returns>The <see cref="VirtualPathData"/>.</returns>
protected virtual VirtualPathData GetVirtualPathData(string routeName, RouteValueDictionary values)
{
@ -253,10 +267,10 @@ namespace Microsoft.AspNetCore.Mvc.Routing
/// <summary>
/// Generates the URL using the specified components.
/// </summary>
/// <param name="protocol">The protocol.</param>
/// <param name="host">The host.</param>
/// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
/// <param name="host">The host name for the URL.</param>
/// <param name="pathData">The <see cref="VirtualPathData"/>.</param>
/// <param name="fragment">The URL fragment.</param>
/// <param name="fragment">The fragment for the URL.</param>
/// <returns>The generated URL.</returns>
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;

89
src/Microsoft.AspNetCore.Mvc.Core/UrlHelperExtensions.cs
View File

@ -9,9 +9,10 @@ namespace Microsoft.AspNetCore.Mvc
public static class UrlHelperExtensions
{
/// <summary>
/// Generates a fully qualified or absolute URL for an action method.
/// Generates a URL with an absolute path for an action method.
/// </summary>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <returns>The generated URL.</returns>
public static string Action(this IUrlHelper helper)
{
if (helper == null)
@ -29,11 +30,12 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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
/// <paramref name="action"/> name.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="action">The name of the action method.</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
public static string Action(this IUrlHelper helper, string action)
{
if (helper == null)
@ -45,13 +47,13 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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
/// <paramref name="action"/> name and route <paramref name="values"/>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="action">The name of the action method.</param>
/// <param name="values">An object that contains route values.</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
public static string Action(this IUrlHelper helper, string action, object values)
{
if (helper == null)
@ -63,13 +65,13 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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
/// <paramref name="action"/> and <paramref name="controller"/> names.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="action">The name of the action method.</param>
/// <param name="controller">The name of the controller.</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
public static string Action(this IUrlHelper helper, string action, string controller)
{
if (helper == null)
@ -81,14 +83,14 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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
/// <paramref name="action"/> name, <paramref name="controller"/> name, and route <paramref name="values"/>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="action">The name of the action method.</param>
/// <param name="controller">The name of the controller.</param>
/// <param name="values">An object that contains route values.</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
public static string Action(this IUrlHelper helper, string action, string controller, object values)
{
if (helper == null)
@ -100,15 +102,16 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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
/// <paramref name="action"/> name, <paramref name="controller"/> name, route <paramref name="values"/>, and
/// <paramref name="protocol"/> to use.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="action">The name of the action method.</param>
/// <param name="controller">The name of the controller.</param>
/// <param name="values">An object that contains route values.</param>
/// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
public static string Action(
this IUrlHelper helper,
string action,
@ -125,8 +128,11 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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
/// <paramref name="action"/> name, <paramref name="controller"/> name, route <paramref name="values"/>,
/// <paramref name="protocol"/> to use, and <paramref name="host"/> name.
/// Generates an absolute URL if the <paramref name="protocol"/> and <paramref name="host"/> are
/// non-<c>null</c>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="action">The name of the action method.</param>
@ -134,7 +140,7 @@ namespace Microsoft.AspNetCore.Mvc
/// <param name="values">An object that contains route values.</param>
/// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
/// <param name="host">The host name for the URL.</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
public static string Action(
this IUrlHelper helper,
string action,
@ -152,8 +158,11 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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
/// <paramref name="action"/> name, <paramref name="controller"/> name, route <paramref name="values"/>,
/// <paramref name="protocol"/> to use, <paramref name="host"/> name, and <paramref name="fragment"/>.
/// Generates an absolute URL if the <paramref name="protocol"/> and <paramref name="host"/> are
/// non-<c>null</c>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="action">The name of the action method.</param>
@ -162,7 +171,7 @@ namespace Microsoft.AspNetCore.Mvc
/// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
/// <param name="host">The host name for the URL.</param>
/// <param name="fragment">The fragment for the URL.</param>
/// <returns>The fully qualified or absolute URL to an action method.</returns>
/// <returns>The generated URL.</returns>
public static string Action(
this IUrlHelper helper,
string action,
@ -189,11 +198,11 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// Generates a fully qualified or absolute URL for the specified route values.
/// Generates a URL with an absolute path for the specified route <paramref name="values"/>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="values">An object that contains route values.</param>
/// <returns>The fully qualified or absolute URL.</returns>
/// <returns>The generated URL.</returns>
public static string RouteUrl(this IUrlHelper helper, object values)
{
if (helper == null)
@ -205,11 +214,11 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// Generates a fully qualified or absolute URL for the specified route name.
/// Generates a URL with an absolute path for the specified <paramref name="routeName"/>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="routeName">The name of the route that is used to generate URL.</param>
/// <returns>The fully qualified or absolute URL.</returns>
/// <returns>The generated URL.</returns>
public static string RouteUrl(this IUrlHelper helper, string routeName)
{
if (helper == null)
@ -221,13 +230,13 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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 <paramref name="routeName"/> and route
/// <paramref name="values"/>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="routeName">The name of the route that is used to generate URL.</param>
/// <param name="values">An object that contains route values.</param>
/// <returns>The fully qualified or absolute URL.</returns>
/// <returns>The generated URL.</returns>
public static string RouteUrl(this IUrlHelper helper, string routeName, object values)
{
if (helper == null)
@ -239,14 +248,14 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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 <paramref name="routeName"/> and route
/// <paramref name="values"/>, which contains the specified <paramref name="protocol"/> to use.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="routeName">The name of the route that is used to generate URL.</param>
/// <param name="values">An object that contains route values.</param>
/// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
/// <returns>The fully qualified or absolute URL.</returns>
/// <returns>The generated URL.</returns>
public static string RouteUrl(
this IUrlHelper helper,
string routeName,
@ -262,15 +271,17 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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 <paramref name="routeName"/> and route
/// <paramref name="values"/>, which contains the specified <paramref name="protocol"/> to use and
/// <paramref name="host"/> name. Generates an absolute URL if
/// <see cref="UrlActionContext.Protocol"/> and <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="routeName">The name of the route that is used to generate URL.</param>
/// <param name="values">An object that contains route values.</param>
/// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
/// <param name="host">The host name for the URL.</param>
/// <returns>The fully qualified or absolute URL.</returns>
/// <returns>The generated URL.</returns>
public static string RouteUrl(
this IUrlHelper helper,
string routeName,
@ -287,8 +298,10 @@ namespace Microsoft.AspNetCore.Mvc
}
/// <summary>
/// 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 <paramref name="routeName"/> and route
/// <paramref name="values"/>, which contains the specified <paramref name="protocol"/> to use,
/// <paramref name="host"/> name and <paramref name="fragment"/>. Generates an absolute URL if
/// <see cref="UrlActionContext.Protocol"/> and <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
/// </summary>
/// <param name="helper">The <see cref="IUrlHelper"/>.</param>
/// <param name="routeName">The name of the route that is used to generate URL.</param>
@ -296,7 +309,7 @@ namespace Microsoft.AspNetCore.Mvc
/// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
/// <param name="host">The host name for the URL.</param>
/// <param name="fragment">The fragment for the URL.</param>
/// <returns>The fully qualified or absolute URL.</returns>
/// <returns>The generated URL.</returns>
public static string RouteUrl(
this IUrlHelper helper,
string routeName,