85 lines
3.7 KiB
C#
85 lines
3.7 KiB
C#
// 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.Routing;
|
|
using Microsoft.AspNetCore.Mvc.Controllers;
|
|
|
|
namespace Microsoft.AspNetCore.Mvc.Routing
|
|
{
|
|
/// <summary>
|
|
/// <para>
|
|
/// A metadata interface which specifies a route value which is required for the action selector to
|
|
/// choose an action. When applied to an action using attribute routing, the route value will be added
|
|
/// to the <see cref="RouteData.Values"/> when the action is selected.
|
|
/// </para>
|
|
/// <para>
|
|
/// When an <see cref="IRouteValueProvider"/> is used to provide a new route value to an action, all
|
|
/// actions in the application must also have a value associated with that key, or have an implicit value
|
|
/// of <c>null</c>. See remarks for more details.
|
|
/// </para>
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// The typical scheme for action selection in an MVC application is that an action will require the
|
|
/// matching values for its <see cref="ControllerActionDescriptor.ControllerName"/> and
|
|
/// <see cref="ControllerActionDescriptor.ActionName"/>
|
|
/// </para>
|
|
/// <example>
|
|
/// For an action like <code>MyApp.Controllers.HomeController.Index()</code>, in order to be selected, the
|
|
/// <see cref="RouteData.Values"/> must contain the values
|
|
/// {
|
|
/// "action": "Index",
|
|
/// "controller": "Home"
|
|
/// }
|
|
/// </example>
|
|
/// <para>
|
|
/// If areas are in use in the application (see <see cref="AreaAttribute"/> which implements
|
|
/// <see cref="IRouteValueProvider"/>) then all actions are consider either in an area by having a
|
|
/// non-<c>null</c> area value (specified by <see cref="AreaAttribute"/> or another
|
|
/// <see cref="IRouteValueProvider"/>) or are considered 'outside' of areas by having the value <c>null</c>.
|
|
/// </para>
|
|
/// <example>
|
|
/// Consider an application with two controllers, each with an <code>Index</code> action method:
|
|
/// - <code>MyApp.Controllers.HomeController.Index()</code>
|
|
/// - <code>MyApp.Areas.Blog.Controllers.HomeController.Index()</code>
|
|
/// where <code>MyApp.Areas.Blog.Controllers.HomeController</code> has an area attribute
|
|
/// <code>[Area("Blog")]</code>.
|
|
///
|
|
/// For <see cref="RouteData.Values"/> like:
|
|
/// {
|
|
/// "action": "Index",
|
|
/// "controller": "Home"
|
|
/// }
|
|
///
|
|
/// <code>MyApp.Controllers.HomeController.Index()</code> will be selected.
|
|
/// <code>MyApp.Area.Blog.Controllers.HomeController.Index()</code> is not considered eligible because the
|
|
/// <see cref="RouteData.Values"/> does not contain the value 'Blog' for 'area'.
|
|
///
|
|
/// For <see cref="RouteData.Values"/> like:
|
|
/// {
|
|
/// "area": "Blog",
|
|
/// "action": "Index",
|
|
/// "controller": "Home"
|
|
/// }
|
|
///
|
|
/// <code>MyApp.Area.Blog.Controllers.HomeController.Index()</code> will be selected.
|
|
/// <code>MyApp.Controllers.HomeController.Index()</code> is not considered eligible because the route values
|
|
/// contain a value for 'area'. <code>MyApp.Controllers.HomeController.Index()</code> cannot match any value
|
|
/// for 'area' other than <c>null</c>.
|
|
/// </example>
|
|
/// </remarks>
|
|
public interface IRouteValueProvider
|
|
{
|
|
/// <summary>
|
|
/// The route value key.
|
|
/// </summary>
|
|
string RouteKey { get; }
|
|
|
|
/// <summary>
|
|
/// The route value. If <c>null</c> or empty, requires the route value associated with <see cref="RouteKey"/>
|
|
/// to be missing or <c>null</c>.
|
|
/// </summary>
|
|
string RouteValue { get; }
|
|
}
|
|
}
|