-
Notifications
You must be signed in to change notification settings - Fork 9.9k
/
IRouteValueProvider.cs
83 lines (79 loc) · 3.31 KB
/
IRouteValueProvider.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using Microsoft.AspNetCore.Mvc.Controllers;
using Microsoft.AspNetCore.Routing;
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 <c>MyApp.Controllers.HomeController.Index()</c>, 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 <c>Index</c> action method:
/// - <c>MyApp.Controllers.HomeController.Index()</c>
/// - <c>MyApp.Areas.Blog.Controllers.HomeController.Index()</c>
/// where <c>MyApp.Areas.Blog.Controllers.HomeController</c> has an area attribute
/// <c>[Area("Blog")]</c>.
///
/// For <see cref="RouteData.Values"/> like:
/// {
/// "action": "Index",
/// "controller": "Home"
/// }
///
/// <c>MyApp.Controllers.HomeController.Index()</c> will be selected.
/// <c>MyApp.Area.Blog.Controllers.HomeController.Index()</c> 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"
/// }
///
/// <c>MyApp.Area.Blog.Controllers.HomeController.Index()</c> will be selected.
/// <c>MyApp.Controllers.HomeController.Index()</c> is not considered eligible because the route values
/// contain a value for 'area'. <c>MyApp.Controllers.HomeController.Index()</c> 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; }
}