adding more docs
This commit is contained in:
Ryan Nowak
parent
5ee3ae9002
commit
e53a9f57db
|
|
@ -6,6 +6,11 @@ using System.Runtime.CompilerServices;
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// Represents a set of <see cref="Endpoint"/> candidates that have been matched
|
||||
/// by the routing system. Used by implementations of <see cref="EndpointSelector"/>
|
||||
/// and <see cref="IEndpointSelectorPolicy"/>.
|
||||
/// </summary>
|
||||
public sealed class CandidateSet
|
||||
{
|
||||
// We inline storage for 4 candidates here to avoid allocations in common
|
||||
|
|
@ -18,8 +23,18 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
|
||||
private CandidateState[] _additionalCandidates;
|
||||
|
||||
// Provided to make testing possible/easy for someone implementing
|
||||
// an EndpointSelector.
|
||||
/// <summary>
|
||||
/// <para>
|
||||
/// Initializes a new instances of the candidate set structure with the provided list of endpoints
|
||||
/// and associated scores.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The constructor is provided to enable unit tests of implementations of <see cref="EndpointSelector"/>
|
||||
/// and <see cref="IEndpointSelectorPolicy"/>.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
/// <param name="endpoints">The list of endpoints, sorted in descending priority order.</param>
|
||||
/// <param name="scores">The list of endpoint scores. <see cref="CandidateState.Score"/>.</param>
|
||||
public CandidateSet(MatcherEndpoint[] endpoints, int[] scores)
|
||||
{
|
||||
Count = endpoints.Length;
|
||||
|
|
@ -112,12 +127,25 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the count of candidates in the set.
|
||||
/// </summary>
|
||||
public int Count { get; }
|
||||
|
||||
// Note that this is a ref-return because of both mutability and performance.
|
||||
// We don't want to copy these fat structs if it can be avoided.
|
||||
/// <summary>
|
||||
/// Gets the <see cref="CandidateState"/> associated with the candidate <see cref="Endpoint"/>
|
||||
/// at <paramref name="index"/>.
|
||||
/// </summary>
|
||||
/// <param name="index">The candidate index.</param>
|
||||
/// <returns>
|
||||
/// A reference to the <see cref="CandidateState"/>. The result is returned by reference
|
||||
/// and intended to be mutated.
|
||||
/// </returns>
|
||||
public ref CandidateState this[int index]
|
||||
{
|
||||
// Note that this is a ref-return because of both mutability and performance.
|
||||
// We don't want to copy these fat structs if it can be avoided.
|
||||
|
||||
// PERF: Force inlining
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
get
|
||||
|
|
|
|||
|
|
@ -3,6 +3,9 @@
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// The mutable state associated with a candidate in a <see cref="CandidateSet"/>.
|
||||
/// </summary>
|
||||
public struct CandidateState
|
||||
{
|
||||
internal CandidateState(MatcherEndpoint endpoint, int score)
|
||||
|
|
@ -14,12 +17,39 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
Values = null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the <see cref="Routing.Endpoint"/>.
|
||||
/// </summary>
|
||||
public MatcherEndpoint Endpoint { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets the score of the <see cref="Routing.Endpoint"/> within the current
|
||||
/// <see cref="CandidateSet"/>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Candidates within a set are ordered in priority order and then assigned a
|
||||
/// sequential score value based on that ordering. Candiates with the same
|
||||
/// score are considered to have equal priority.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The score values are used in the <see cref="EndpointSelector"/> to determine
|
||||
/// whether a set of matching candidates is an ambiguous match.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public int Score { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets a value which indicates where the <see cref="Routing.Endpoint"/> is considered
|
||||
/// a valid candiate for the current request. Set this value to <c>false</c> to exclude an
|
||||
/// <see cref="Routing.Endpoint"/> from consideration.
|
||||
/// </summary>
|
||||
public bool IsValidCandidate { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets the <see cref="RouteValueDictionary"/> associated with the
|
||||
/// <see cref="Routing.Endpoint"/> and the current request.
|
||||
/// </summary>
|
||||
public RouteValueDictionary Values { get; set; }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -6,10 +6,30 @@ using System.Collections.Generic;
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// A base class for <see cref="IComparer{Endpoint}"/> implementations that use
|
||||
/// a specific type of metadata from <see cref="Endpoint.Metadata"/> for comparison.
|
||||
/// Useful for implementing <see cref="IEndpointComparerPolicy.Comparer"/>.
|
||||
/// </summary>
|
||||
/// <typeparam name="TMetadata">
|
||||
/// The type of metadata to compare. Typically this is a type of metadata related
|
||||
/// to the application concern being handled.
|
||||
/// </typeparam>
|
||||
public abstract class EndpointMetadataComparer<TMetadata> : IComparer<Endpoint> where TMetadata : class
|
||||
{
|
||||
public static readonly EndpointMetadataComparer<TMetadata> Default = new DefaultComparer<TMetadata>();
|
||||
|
||||
/// <summary>
|
||||
/// Compares two objects and returns a value indicating whether one is less than, equal to,
|
||||
/// or greater than the other.
|
||||
/// </summary>
|
||||
/// <param name="x">The first object to compare.</param>
|
||||
/// <param name="y">The second object to compare.</param>
|
||||
/// <returns>
|
||||
/// An implementation of this method must return a value less than zero if
|
||||
/// x is less than y, zero if x is equal to y, or a value greater than zero if x is
|
||||
/// greater than y.
|
||||
/// </returns>
|
||||
public int Compare(Endpoint x, Endpoint y)
|
||||
{
|
||||
if (x == null)
|
||||
|
|
@ -25,11 +45,32 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
return CompareMetadata(GetMetadata(x), GetMetadata(y));
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the metadata of type <typeparamref name="TMetadata"/> from the provided endpoint.
|
||||
/// </summary>
|
||||
/// <param name="endpoint">The <see cref="Endpoint"/>.</param>
|
||||
/// <returns>The <typeparamref name="TMetadata"/> instance or <c>null</c>.</returns>
|
||||
protected virtual TMetadata GetMetadata(Endpoint endpoint)
|
||||
{
|
||||
return endpoint.Metadata.GetMetadata<TMetadata>();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Compares two <typeparamref name="TMetadata"/> instances.
|
||||
/// </summary>
|
||||
/// <param name="x">The first object to compare.</param>
|
||||
/// <param name="y">The second object to compare.</param>
|
||||
/// <returns>
|
||||
/// An implementation of this method must return a value less than zero if
|
||||
/// x is less than y, zero if x is equal to y, or a value greater than zero if x is
|
||||
/// greater than y.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// The base-class implementation of this method will compare metadata based on whether
|
||||
/// or not they are <c>null</c>. The effect of this is that when endpoints are being
|
||||
/// compared, the endpoint that defines an instance of <typeparamref name="TMetadata"/>
|
||||
/// will be considered higher priority.
|
||||
/// </remarks>
|
||||
protected virtual int CompareMetadata(TMetadata x, TMetadata y)
|
||||
{
|
||||
// The default policy is that if x endpoint defines TMetadata, and
|
||||
|
|
|
|||
|
|
@ -6,8 +6,25 @@ using Microsoft.AspNetCore.Http;
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// A service that is responsible for the final <see cref="Endpoint"/> selection
|
||||
/// decision. To use a custom <see cref="EndpointSelector"/> register an implementation
|
||||
/// of <see cref="EndpointSelector"/> in the dependency injection container as a singleton.
|
||||
/// </summary>
|
||||
public abstract class EndpointSelector
|
||||
{
|
||||
/// <summary>
|
||||
/// Asynchronously selects an <see cref="Endpoint"/> from the <see cref="CandidateSet"/>.
|
||||
/// </summary>
|
||||
/// <param name="httpContext">The <see cref="HttpContext"/> associated with the current request.</param>
|
||||
/// <param name="feature">The <see cref="IEndpointFeature"/> associated with the current request.</param>
|
||||
/// <param name="candidates">The <see cref="CandidateSet"/>.</param>
|
||||
/// <returns>A <see cref="Task"/> that completes asynchronously once endpoint selection is complete.</returns>
|
||||
/// <remarks>
|
||||
/// An <see cref="EndpointSelector"/> should assign the <see cref="IEndpointFeature.Endpoint"/>,
|
||||
/// <see cref="IEndpointFeature.Invoker"/>, and <see cref="IEndpointFeature.Values"/> properties
|
||||
/// once an endpoint is selected.
|
||||
/// </remarks>
|
||||
public abstract Task SelectAsync(
|
||||
HttpContext httpContext,
|
||||
IEndpointFeature feature,
|
||||
|
|
|
|||
|
|
@ -12,6 +12,10 @@ using Microsoft.Extensions.Primitives;
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// An <see cref="MatcherPolicy"/> that implements filtering and selection by
|
||||
/// the HTTP method of a request.
|
||||
/// </summary>
|
||||
public sealed class HttpMethodMatcherPolicy : MatcherPolicy, IEndpointComparerPolicy, INodeBuilderPolicy
|
||||
{
|
||||
// Used in tests
|
||||
|
|
@ -25,12 +29,23 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
// Used in tests
|
||||
internal const string AnyMethod = "*";
|
||||
|
||||
/// <summary>
|
||||
/// For framework use only.
|
||||
/// </summary>
|
||||
public IComparer<Endpoint> Comparer => new HttpMethodMetadataEndpointComparer();
|
||||
|
||||
// The order value is chosen to be less than 0, so that it comes before naively
|
||||
// written policies.
|
||||
/// <summary>
|
||||
/// For framework use only.
|
||||
/// </summary>
|
||||
public override int Order => -1000;
|
||||
|
||||
/// <summary>
|
||||
/// For framework use only.
|
||||
/// </summary>
|
||||
/// <param name="endpoints"></param>
|
||||
/// <returns></returns>
|
||||
public bool AppliesToNode(IReadOnlyList<Endpoint> endpoints)
|
||||
{
|
||||
if (endpoints == null)
|
||||
|
|
@ -49,6 +64,11 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
return false;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// For framework use only.
|
||||
/// </summary>
|
||||
/// <param name="endpoints"></param>
|
||||
/// <returns></returns>
|
||||
public IReadOnlyList<PolicyNodeEdge> GetEdges(IReadOnlyList<Endpoint> endpoints)
|
||||
{
|
||||
// The algorithm here is designed to be preserve the order of the endpoints
|
||||
|
|
@ -180,6 +200,12 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// For framework use only.
|
||||
/// </summary>
|
||||
/// <param name="exitDestination"></param>
|
||||
/// <param name="edges"></param>
|
||||
/// <returns></returns>
|
||||
public PolicyJumpTable BuildJumpTable(int exitDestination, IReadOnlyList<PolicyJumpTableEdge> edges)
|
||||
{
|
||||
var destinations = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);
|
||||
|
|
|
|||
|
|
@ -5,8 +5,30 @@ using System.Collections.Generic;
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// A <see cref="MatcherPolicy"/> interface that can be implemented to sort
|
||||
/// endpoints. Implementations of <see cref="IEndpointComparerPolicy"/> must
|
||||
/// inherit from <see cref="MatcherPolicy"/> and should be registered in
|
||||
/// the dependency injection container as singleton services of type <see cref="MatcherPolicy"/>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Candidates in a <see cref="CandidateSet"/> are sorted based on their priority. Defining
|
||||
/// a <see cref="IEndpointComparerPolicy"/> adds an additional criterion to the sorting
|
||||
/// operation used to order candidates.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// As an example, the implementation of <see cref="HttpMethodMatcherPolicy"/> implements
|
||||
/// <see cref="IEndpointComparerPolicy"/> to ensure that endpoints matching specific HTTP
|
||||
/// methods are sorted with a higher priority than endpoints without a specific HTTP method
|
||||
/// requirement.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public interface IEndpointComparerPolicy
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets an <see cref="IComparer{Endpoint}"/> that will be used to sort the endpoints.
|
||||
/// </summary>
|
||||
IComparer<Endpoint> Comparer { get; }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -5,8 +5,26 @@ using Microsoft.AspNetCore.Http;
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// A <see cref="MatcherPolicy"/> interface that can implemented to filter endpoints
|
||||
/// in a <see cref="CandidateSet"/>. Implementations of <see cref="IEndpointSelectorPolicy"/> must
|
||||
/// inherit from <see cref="MatcherPolicy"/> and should be registered in
|
||||
/// the dependency injection container as singleton services of type <see cref="MatcherPolicy"/>.
|
||||
/// </summary>
|
||||
public interface IEndpointSelectorPolicy
|
||||
{
|
||||
/// <summary>
|
||||
/// Applies the policy to the <see cref="CandidateSet"/>.
|
||||
/// </summary>
|
||||
/// <param name="httpContext">
|
||||
/// The <see cref="HttpContext"/> associated with the current request.
|
||||
/// </param>
|
||||
/// <param name="candidates">The <see cref="CandidateSet"/>.</param>
|
||||
/// <remarks>
|
||||
/// Implementations of <see cref="IEndpointSelectorPolicy"/> should implement this method
|
||||
/// and filter the set of candidates in the <paramref name="candidates"/> by setting
|
||||
/// <see cref="CandidateState.IsValidCandidate"/> to <c>false</c> where desired.
|
||||
/// </remarks>
|
||||
void Apply(HttpContext httpContext, CandidateSet candidates);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -9,6 +9,9 @@ using Microsoft.AspNetCore.Routing.Patterns;
|
|||
|
||||
namespace Microsoft.AspNetCore.Routing.Matching
|
||||
{
|
||||
/// <summary>
|
||||
/// Represents an <see cref="Endpoint"/> that can be used in URL matching or URL generation.
|
||||
/// </summary>
|
||||
public sealed class MatcherEndpoint : Endpoint
|
||||
{
|
||||
internal static readonly Func<RequestDelegate, RequestDelegate> EmptyInvoker = (next) =>
|
||||
|
|
@ -16,6 +19,16 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
return (context) => Task.CompletedTask;
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="MatcherEndpoint"/> class.
|
||||
/// </summary>
|
||||
/// <param name="invoker">The delegate to invoke to create a <see cref="RequestDelegate"/>.</param>
|
||||
/// <param name="routePattern">The <see cref="RoutePattern"/> to use in URL matching.</param>
|
||||
/// <param name="order">The order assigned to the endpoint.</param>
|
||||
/// <param name="metadata">
|
||||
/// The <see cref="EndpointMetadataCollection"/> or metadata associated with the endpoint.
|
||||
/// </param>
|
||||
/// <param name="displayName">The informational display name of the endpoint.</param>
|
||||
public MatcherEndpoint(
|
||||
Func<RequestDelegate, RequestDelegate> invoker,
|
||||
RoutePattern routePattern,
|
||||
|
|
@ -39,10 +52,23 @@ namespace Microsoft.AspNetCore.Routing.Matching
|
|||
Order = order;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the invoker. The invoker is a delegate used to create a <see cref="RequestDelegate"/>.
|
||||
/// </summary>
|
||||
public Func<RequestDelegate, RequestDelegate> Invoker { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets the order value of endpoint.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The order value provides absolute control over the priority
|
||||
/// of an endpoint. Endpoints with a lower numeric value of order have higher priority.
|
||||
/// </remarks>
|
||||
public int Order { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets the <see cref="RoutePattern"/> associated with the endpoint.
|
||||
/// </summary>
|
||||
public RoutePattern RoutePattern { get; }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,10 +1,28 @@
|
|||
// 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.Matching;
|
||||
|
||||
namespace Microsoft.AspNetCore.Routing
|
||||
{
|
||||
/// <summary>
|
||||
/// Defines a policy that applies behaviors to the URL matcher. Implementations
|
||||
/// of <see cref="MatcherPolicy"/> and related interfaces must be registered
|
||||
/// in the dependency injection container as singleton services of type
|
||||
/// <see cref="MatcherPolicy"/>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <see cref="MatcherPolicy"/> implementations can implement the following
|
||||
/// interfaces <see cref="IEndpointComparerPolicy"/>, <see cref="IEndpointSelectorPolicy"/>,
|
||||
/// and <see cref="INodeBuilderPolicy"/>.
|
||||
/// </remarks>
|
||||
public abstract class MatcherPolicy
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets a value that determines the order the <see cref="MatcherPolicy"/> should
|
||||
/// be applied. Policies are applied in ascending numeric value of the <see cref="Order"/>
|
||||
/// property.
|
||||
/// </summary>
|
||||
public abstract int Order { get; }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue