From 9cea167cfac36cf034dbb780e3f783114ef94780 Mon Sep 17 00:00:00 2001 From: Ryan Nowak Date: Thu, 2 Aug 2018 15:24:00 -0700 Subject: [PATCH] Add docs - EndpointFeature and related types (#687) * Add docs - EndpointFeature and related types * Add docs for route patterns --- .../Endpoint.cs | 23 +- .../EndpointMetadataCollection.cs | 71 ++++++ .../IEndpointFeature.cs | 16 ++ .../EndpointFeature.cs | 21 ++ .../Patterns/RoutePattern.cs | 36 +++ .../RoutePatternConstraintReference.cs | 3 +- .../Patterns/RoutePatternException.cs | 16 ++ .../Patterns/RoutePatternFactory.cs | 210 +++++++++++++++++- .../Patterns/RoutePatternLiteralPart.cs | 7 + .../Patterns/RoutePatternMatcher.cs | 3 +- .../Patterns/RoutePatternParameterKind.cs | 15 ++ .../Patterns/RoutePatternParameterPart.cs | 24 ++ .../Patterns/RoutePatternPart.cs | 15 ++ .../Patterns/RoutePatternPartKind.cs | 14 ++ .../Patterns/RoutePatternPathSegment.cs | 17 ++ .../Patterns/RoutePatternSeparatorPart.cs | 24 ++ 16 files changed, 508 insertions(+), 7 deletions(-) diff --git a/src/Microsoft.AspNetCore.Routing.Abstractions/Endpoint.cs b/src/Microsoft.AspNetCore.Routing.Abstractions/Endpoint.cs index f58ba517e9..ef98f75d8a 100644 --- a/src/Microsoft.AspNetCore.Routing.Abstractions/Endpoint.cs +++ b/src/Microsoft.AspNetCore.Routing.Abstractions/Endpoint.cs @@ -1,13 +1,22 @@ // 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 System.Diagnostics; - namespace Microsoft.AspNetCore.Routing { - [DebuggerDisplay("{DisplayName,nq}")] + /// + /// Respresents a logical endpoint in an application. + /// public abstract class Endpoint { + /// + /// Creates a new instance of . + /// + /// + /// The endpoint . May be null. + /// + /// + /// The informational display name of the endpoint. May be null. + /// protected Endpoint( EndpointMetadataCollection metadata, string displayName) @@ -17,8 +26,16 @@ namespace Microsoft.AspNetCore.Routing DisplayName = displayName; } + /// + /// Gets the informational display name of this endpoint. + /// public string DisplayName { get; } + /// + /// Gets the collection of metadata associated with this endpoint. + /// public EndpointMetadataCollection Metadata { get; } + + public override string ToString() => DisplayName ?? base.ToString(); } } diff --git a/src/Microsoft.AspNetCore.Routing.Abstractions/EndpointMetadataCollection.cs b/src/Microsoft.AspNetCore.Routing.Abstractions/EndpointMetadataCollection.cs index 405a5581d1..54624d8717 100644 --- a/src/Microsoft.AspNetCore.Routing.Abstractions/EndpointMetadataCollection.cs +++ b/src/Microsoft.AspNetCore.Routing.Abstractions/EndpointMetadataCollection.cs @@ -8,12 +8,27 @@ using System.Linq; namespace Microsoft.AspNetCore.Routing { + /// + /// A collection of arbitrary metadata associated with an endpoint. + /// + /// + /// instances contain a list of metadata items + /// of arbitrary types. The metadata items are stored as an ordered collection with + /// items arranged in ascending order of precedence. + /// public sealed class EndpointMetadataCollection : IReadOnlyList { + /// + /// An empty . + /// public static readonly EndpointMetadataCollection Empty = new EndpointMetadataCollection(Array.Empty()); private readonly object[] _items; + /// + /// Creates a new . + /// + /// The metadata items. public EndpointMetadataCollection(IEnumerable items) { if (items == null) @@ -24,15 +39,34 @@ namespace Microsoft.AspNetCore.Routing _items = items.ToArray(); } + /// + /// Creates a new . + /// + /// The metadata items. public EndpointMetadataCollection(params object[] items) : this((IEnumerable)items) { } + /// + /// Gets the item at . + /// + /// The index of the item to retrieve. + /// The item at . public object this[int index] => _items[index]; + /// + /// Gets the count of metadata items. + /// public int Count => _items.Length; + /// + /// Gets the most significant metadata item of type . + /// + /// The type of metadata to retrieve. + /// + /// The most significant metadata of type or null. + /// public T GetMetadata() where T : class { for (var i = _items.Length - 1; i >= 0; i--) @@ -47,6 +81,12 @@ namespace Microsoft.AspNetCore.Routing return default; } + /// + /// Gets the metadata items of type in ascending + /// order of precedence. + /// + /// The type of metadata. + /// A sequence of metadata items of . public IEnumerable GetOrderedMetadata() where T : class { for (var i = 0; i < _items.Length; i++) @@ -59,12 +99,27 @@ namespace Microsoft.AspNetCore.Routing } } + /// + /// Gets an of all metadata items. + /// + /// An of all metadata items. public Enumerator GetEnumerator() => new Enumerator(this); + /// + /// Gets an of all metadata items. + /// + /// An of all metadata items. IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); + /// + /// Gets an of all metadata items. + /// + /// An of all metadata items. IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); + /// + /// Enumerates the elements of an . + /// public struct Enumerator : IEnumerator { // Intentionally not readonly to prevent defensive struct copies @@ -79,12 +134,25 @@ namespace Microsoft.AspNetCore.Routing _current = null; } + /// + /// Gets the element at the current position of the enumerator + /// public object Current => _current; + /// + /// Releases all resources used by the . + /// public void Dispose() { } + /// + /// Advances the enumerator to the next element of the . + /// + /// + /// true if the enumerator was successfully advanced to the next element; + /// false if the enumerator has passed the end of the collection. + /// public bool MoveNext() { if (_index < _items.Length) @@ -97,6 +165,9 @@ namespace Microsoft.AspNetCore.Routing return false; } + /// + /// Sets the enumerator to its initial position, which is before the first element in the collection. + /// public void Reset() { _index = 0; diff --git a/src/Microsoft.AspNetCore.Routing.Abstractions/IEndpointFeature.cs b/src/Microsoft.AspNetCore.Routing.Abstractions/IEndpointFeature.cs index 5ecf72cb56..c4b9ac95c2 100644 --- a/src/Microsoft.AspNetCore.Routing.Abstractions/IEndpointFeature.cs +++ b/src/Microsoft.AspNetCore.Routing.Abstractions/IEndpointFeature.cs @@ -6,12 +6,28 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.Routing { + /// + /// A feature interface for endpoint routing. Use + /// to access an instance associated with the current request. + /// public interface IEndpointFeature { + /// + /// Gets or sets the selected for the current + /// request. + /// Endpoint Endpoint { get; set; } + /// + /// Gets or sets a delegate that can be used to invoke the current + /// . + /// Func Invoker { get; set; } + /// + /// Gets or sets the associated with the currrent + /// request. + /// RouteValueDictionary Values { get; set; } } } diff --git a/src/Microsoft.AspNetCore.Routing/EndpointFeature.cs b/src/Microsoft.AspNetCore.Routing/EndpointFeature.cs index 99e5709867..396f9b00ee 100644 --- a/src/Microsoft.AspNetCore.Routing/EndpointFeature.cs +++ b/src/Microsoft.AspNetCore.Routing/EndpointFeature.cs @@ -6,15 +6,30 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.Routing { + /// + /// A default implementation of and . + /// public sealed class EndpointFeature : IEndpointFeature, IRoutingFeature { private RouteData _routeData; private RouteValueDictionary _values; + /// + /// Gets or sets the selected for the current + /// request. + /// public Endpoint Endpoint { get; set; } + /// + /// Gets or sets a delegate that can be used to invoke the current + /// . + /// public Func Invoker { get; set; } + /// + /// Gets or sets the associated with the currrent + /// request. + /// public RouteValueDictionary Values { get => _values; @@ -27,6 +42,12 @@ namespace Microsoft.AspNetCore.Routing } } + /// + /// Gets or sets the for the current request. + /// + /// + /// The setter is not implemented. Use to set the route values. + /// RouteData IRoutingFeature.RouteData { get diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePattern.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePattern.cs index bc1551367b..c6d80b0a06 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePattern.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePattern.cs @@ -9,6 +9,11 @@ using Microsoft.AspNetCore.Routing.Template; namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Represents a parsed route template with default values and constraints. + /// Use to create + /// instances. Instances of are immutable. + /// [DebuggerDisplay("{DebuggerToString()}")] public sealed class RoutePattern { @@ -36,18 +41,49 @@ namespace Microsoft.AspNetCore.Routing.Patterns OutboundPrecedence = RoutePrecedence.ComputeOutbound(this); } + /// + /// Gets the set of default values for the route pattern. + /// The keys of are the route parameter names. + /// public IReadOnlyDictionary Defaults { get; } + /// + /// Gets the set of constraint references for the route pattern. + /// The keys of are the route parameter names. + /// public IReadOnlyDictionary> Constraints { get; } + /// + /// Gets the precedence value of the route pattern for URL matching. + /// + /// + /// Precedence is a computed value based on the structure of the route pattern + /// used for building URL matching data structures. + /// public decimal InboundPrecedence { get; } + /// + /// Gets the precedence value of the route pattern for URL generation. + /// + /// + /// Precedence is a computed value based on the structure of the route pattern + /// used for building URL generation data structures. + /// public decimal OutboundPrecedence { get; } + /// + /// Gets the raw text supplied when parsing the route pattern. May be null. + /// public string RawText { get; } + /// + /// Gets the list of route parameters. + /// public IReadOnlyList Parameters { get; } + /// + /// Gets the list of path segments. + /// public IReadOnlyList PathSegments { get; } /// diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternConstraintReference.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternConstraintReference.cs index 088bdce200..3e832ead65 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternConstraintReference.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternConstraintReference.cs @@ -7,7 +7,8 @@ using Microsoft.AspNetCore.Routing.Matching; namespace Microsoft.AspNetCore.Routing.Patterns { /// - /// The parsed representation of a constraint in a parameter. + /// The parsed representation of a constraint in a parameter. Instances + /// of are immutable. /// [DebuggerDisplay("{DebuggerToString()}")] public sealed class RoutePatternConstraintReference diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternException.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternException.cs index 6399145256..04dc26daf4 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternException.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternException.cs @@ -6,6 +6,9 @@ using System.Runtime.Serialization; namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// An exception that is thrown for error constructing a . + /// [Serializable] public sealed class RoutePatternException : Exception { @@ -15,6 +18,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns Pattern = (string)info.GetValue(nameof(Pattern), typeof(string)); } + /// + /// Creates a new . + /// + /// The route pattern as raw text. + /// The exception message. public RoutePatternException(string pattern, string message) : base(message) { @@ -31,8 +39,16 @@ namespace Microsoft.AspNetCore.Routing.Patterns Pattern = pattern; } + /// + /// Gets the route pattern associated with this exception. + /// public string Pattern { get; } + /// + /// Populates a with the data needed to serialize the target object. + /// + /// The to populate with data. + /// The destination () for this serialization. public override void GetObjectData(SerializationInfo info, StreamingContext context) { info.AddValue(nameof(Pattern), Pattern); diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternFactory.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternFactory.cs index b0bd70c488..54a34c9d4c 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternFactory.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternFactory.cs @@ -9,8 +9,18 @@ using Microsoft.AspNetCore.Routing.Matching; namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Contains factory methods for creating and related types. + /// Use to parse a route pattern in + /// string format. + /// public static class RoutePatternFactory { + /// + /// Creates a from its string representation. + /// + /// The route pattern string to parse. + /// The . public static RoutePattern Parse(string pattern) { if (pattern == null) @@ -21,6 +31,22 @@ namespace Microsoft.AspNetCore.Routing.Patterns return RoutePatternParser.Parse(pattern); } + /// + /// Creates a from its string representation along + /// with provided default values and constraints. + /// + /// The route pattern string to parse. + /// + /// Additional default values to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the parsed route pattern. + /// + /// + /// Additional constraints to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the parsed route pattern. + /// + /// The . public static RoutePattern Parse(string pattern, object defaults, object constraints) { if (pattern == null) @@ -32,6 +58,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns return Pattern(original.RawText, defaults, constraints, original.PathSegments); } + /// + /// Creates a new from a collection of segments. + /// + /// The collection of segments. + /// The . public static RoutePattern Pattern(IEnumerable segments) { if (segments == null) @@ -42,6 +73,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns return PatternCore(null, null, null, segments); } + /// + /// Creates a new from a collection of segments. + /// + /// The raw text to associate with the route pattern. May be null. + /// The collection of segments. + /// The . public static RoutePattern Pattern(string rawText, IEnumerable segments) { if (segments == null) @@ -52,6 +89,22 @@ namespace Microsoft.AspNetCore.Routing.Patterns return PatternCore(rawText, null, null, segments); } + /// + /// Creates a from a collection of segments along + /// with provided default values and constraints. + /// + /// + /// Additional default values to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// + /// Additional constraints to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// The collection of segments. + /// The . public static RoutePattern Pattern( object defaults, object constraints, @@ -65,6 +118,23 @@ namespace Microsoft.AspNetCore.Routing.Patterns return PatternCore(null, new RouteValueDictionary(defaults), new RouteValueDictionary(constraints), segments); } + /// + /// Creates a from a collection of segments along + /// with provided default values and constraints. + /// + /// The raw text to associate with the route pattern. + /// + /// Additional default values to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// + /// Additional constraints to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// The collection of segments. + /// The . public static RoutePattern Pattern( string rawText, object defaults, @@ -79,6 +149,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns return PatternCore(rawText, new RouteValueDictionary(defaults), new RouteValueDictionary(constraints), segments); } + /// + /// Creates a new from a collection of segments. + /// + /// The collection of segments. + /// The . public static RoutePattern Pattern(params RoutePatternPathSegment[] segments) { if (segments == null) @@ -89,6 +164,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns return PatternCore(null, null, null, segments); } + /// + /// Creates a new from a collection of segments. + /// + /// The raw text to associate with the route pattern. May be null. + /// The collection of segments. + /// The . public static RoutePattern Pattern(string rawText, params RoutePatternPathSegment[] segments) { if (segments == null) @@ -99,6 +180,22 @@ namespace Microsoft.AspNetCore.Routing.Patterns return PatternCore(rawText, null, null, segments); } + /// + /// Creates a from a collection of segments along + /// with provided default values and constraints. + /// + /// + /// Additional default values to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// + /// Additional constraints to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// The collection of segments. + /// The . public static RoutePattern Pattern( object defaults, object constraints, @@ -112,6 +209,23 @@ namespace Microsoft.AspNetCore.Routing.Patterns return PatternCore(null, new RouteValueDictionary(defaults), new RouteValueDictionary(constraints), segments); } + /// + /// Creates a from a collection of segments along + /// with provided default values and constraints. + /// + /// The raw text to associate with the route pattern. + /// + /// Additional default values to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// + /// Additional constraints to associated with the route pattern. May be null. + /// The provided object will be converted to key-value pairs using + /// and then merged into the route pattern. + /// + /// The collection of segments. + /// The . public static RoutePattern Pattern( string rawText, object defaults, @@ -251,6 +365,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns } } + /// + /// Creates a from the provided collection + /// of parts. + /// + /// The collection of parts. + /// The . public static RoutePatternPathSegment Segment(IEnumerable parts) { if (parts == null) @@ -261,6 +381,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns return SegmentCore(parts); } + /// + /// Creates a from the provided collection + /// of parts. + /// + /// The collection of parts. + /// The . public static RoutePatternPathSegment Segment(params RoutePatternPart[] parts) { if (parts == null) @@ -276,6 +402,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns return new RoutePatternPathSegment(parts.ToArray()); } + /// + /// Creates a from the provided text + /// content. + /// + /// The text content. + /// The . public static RoutePatternLiteralPart LiteralPart(string content) { if (string.IsNullOrEmpty(content)) @@ -296,6 +428,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns return new RoutePatternLiteralPart(content); } + /// + /// Creates a from the provided text + /// content. + /// + /// The text content. + /// The . public static RoutePatternSeparatorPart SeparatorPart(string content) { if (string.IsNullOrEmpty(content)) @@ -311,6 +449,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns return new RoutePatternSeparatorPart(content); } + /// + /// Creates a from the provided parameter name. + /// + /// The parameter name. + /// The . public static RoutePatternParameterPart ParameterPart(string parameterName) { if (string.IsNullOrEmpty(parameterName)) @@ -329,7 +472,14 @@ namespace Microsoft.AspNetCore.Routing.Patterns parameterKind: RoutePatternParameterKind.Standard, constraints: Array.Empty()); } - + + /// + /// Creates a from the provided parameter name + /// and default value. + /// + /// The parameter name. + /// The parameter default value. May be null. + /// The . public static RoutePatternParameterPart ParameterPart(string parameterName, object @default) { if (string.IsNullOrEmpty(parameterName)) @@ -349,6 +499,14 @@ namespace Microsoft.AspNetCore.Routing.Patterns constraints: Array.Empty()); } + /// + /// Creates a from the provided parameter name + /// and default value, and parameter kind. + /// + /// The parameter name. + /// The parameter default value. May be null. + /// The parameter kind. + /// The . public static RoutePatternParameterPart ParameterPart( string parameterName, object @default, @@ -376,6 +534,15 @@ namespace Microsoft.AspNetCore.Routing.Patterns constraints: Array.Empty()); } + /// + /// Creates a from the provided parameter name + /// and default value, parameter kind, and constraints. + /// + /// The parameter name. + /// The parameter default value. May be null. + /// The parameter kind. + /// The constraints to associated with the parameter. + /// The . public static RoutePatternParameterPart ParameterPart( string parameterName, object @default, @@ -409,6 +576,15 @@ namespace Microsoft.AspNetCore.Routing.Patterns constraints: constraints); } + /// + /// Creates a from the provided parameter name + /// and default value, parameter kind, and constraints. + /// + /// The parameter name. + /// The parameter default value. May be null. + /// The parameter kind. + /// The constraints to associated with the parameter. + /// The . public static RoutePatternParameterPart ParameterPart( string parameterName, object @default, @@ -451,6 +627,16 @@ namespace Microsoft.AspNetCore.Routing.Patterns return new RoutePatternParameterPart(parameterName, @default, parameterKind, constraints.ToArray()); } + /// + /// Creates a from the provided object. + /// + /// + /// The constraint object, which must be of type , + /// , or . If the constraint object + /// is a it will be tranformed into an instance of + /// . + /// + /// The . public static RoutePatternConstraintReference Constraint(object constraint) { // Similar to RouteConstraintBuilder @@ -475,6 +661,13 @@ namespace Microsoft.AspNetCore.Routing.Patterns } } + /// + /// Creates a from the provided object. + /// + /// + /// The constraint object. + /// + /// The . public static RoutePatternConstraintReference Constraint(IRouteConstraint constraint) { if (constraint == null) @@ -485,6 +678,13 @@ namespace Microsoft.AspNetCore.Routing.Patterns return ConstraintCore(constraint); } + /// + /// Creates a from the provided object. + /// + /// + /// The match processor object. + /// + /// The . public static RoutePatternConstraintReference Constraint(MatchProcessor matchProcessor) { if (matchProcessor == null) @@ -495,6 +695,14 @@ namespace Microsoft.AspNetCore.Routing.Patterns return ConstraintCore(matchProcessor); } + /// + /// Creates a from the provided object. + /// + /// + /// The constraint text, which will be tranformed into an instance of + /// . + /// + /// The . public static RoutePatternConstraintReference Constraint(string constraint) { if (string.IsNullOrEmpty(constraint)) diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternLiteralPart.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternLiteralPart.cs index 60cc9d2a96..d9fcb22bc6 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternLiteralPart.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternLiteralPart.cs @@ -5,6 +5,10 @@ using System.Diagnostics; namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Resprents a literal text part of a route pattern. Instances of + /// are immutable. + /// [DebuggerDisplay("{DebuggerToString()}")] public sealed class RoutePatternLiteralPart : RoutePatternPart { @@ -15,6 +19,9 @@ namespace Microsoft.AspNetCore.Routing.Patterns Content = content; } + /// + /// Gets the text content. + /// public string Content { get; } internal override string DebuggerToString() diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternMatcher.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternMatcher.cs index f875b472be..7e3597086b 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternMatcher.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternMatcher.cs @@ -2,11 +2,10 @@ // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; -using System.Collections.Generic; using System.Diagnostics; +using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Routing.Internal; using Microsoft.AspNetCore.Routing.Patterns; -using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Primitives; namespace Microsoft.AspNetCore.Routing diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterKind.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterKind.cs index 5a682d4897..0eb5b987de 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterKind.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterKind.cs @@ -3,10 +3,25 @@ namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Defines the kinds of instances. + /// public enum RoutePatternParameterKind { + /// + /// The of a standard parameter + /// without optional or catch all behavior. + /// Standard, + + /// + /// The of an optional parameter. + /// Optional, + + /// + /// The of a catch-all parameter. + /// CatchAll, } } diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterPart.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterPart.cs index afe2be3096..04f9056573 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterPart.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterPart.cs @@ -7,6 +7,10 @@ using System.Text; namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Represents a parameter part in a route pattern. Instances of + /// are immutable. + /// [DebuggerDisplay("{DebuggerToString()}")] public sealed class RoutePatternParameterPart : RoutePatternPart { @@ -25,16 +29,36 @@ namespace Microsoft.AspNetCore.Routing.Patterns Constraints = constraints; } + /// + /// Gets the list of constraints associated with this parameter. + /// public IReadOnlyList Constraints { get; } + /// + /// Gets the default value of this route parameter. May be null. + /// public object Default { get; } + /// + /// Returns true if this part is a catch-all parameter. + /// Otherwise returns false. + /// public bool IsCatchAll => ParameterKind == RoutePatternParameterKind.CatchAll; + /// + /// Returns true if this part is an optional parameter. + /// Otherwise returns false. + /// public bool IsOptional => ParameterKind == RoutePatternParameterKind.Optional; + /// + /// Gets the of this parameter. + /// public RoutePatternParameterKind ParameterKind { get; } + /// + /// Gets the parameter name. + /// public string Name { get; } internal override string DebuggerToString() diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPart.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPart.cs index 7ea3865699..bc797cfee8 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPart.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPart.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Represents a part of a route pattern. + /// public abstract class RoutePatternPart { // This class is **not** an extensibility point - every part of the routing system @@ -14,12 +17,24 @@ namespace Microsoft.AspNetCore.Routing.Patterns PartKind = partKind; } + /// + /// Gets the of this part. + /// public RoutePatternPartKind PartKind { get; } + /// + /// Returns true if this part is literal text. Otherwise returns false. + /// public bool IsLiteral => PartKind == RoutePatternPartKind.Literal; + /// + /// Returns true if this part is a route parameter. Otherwise returns false. + /// public bool IsParameter => PartKind == RoutePatternPartKind.Parameter; + /// + /// Returns true if this part is an optional separator. Otherwise returns false. + /// public bool IsSeparator => PartKind == RoutePatternPartKind.Separator; internal abstract string DebuggerToString(); diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPartKind.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPartKind.cs index 1dfaad0250..1b67819322 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPartKind.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPartKind.cs @@ -3,10 +3,24 @@ namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Defines the kinds of instances. + /// public enum RoutePatternPartKind { + /// + /// The of a . + /// Literal, + + /// + /// The of a . + /// Parameter, + + /// + /// The of a . + /// Separator, } } diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPathSegment.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPathSegment.cs index 96c2a86592..1fd65f45d7 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPathSegment.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPathSegment.cs @@ -7,6 +7,16 @@ using System.Linq; namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Represents a path segment in a route pattern. Instances of are + /// immutable. + /// + /// + /// Route patterns are made up of URL path segments, delimited by /. A + /// contains a group of + /// that represent the structure of a segment + /// in a route pattern. + /// [DebuggerDisplay("{DebuggerToString()}")] public sealed class RoutePatternPathSegment { @@ -15,8 +25,15 @@ namespace Microsoft.AspNetCore.Routing.Patterns Parts = parts; } + /// + /// Returns true if the segment contains a single part; + /// otherwise returns false. + /// public bool IsSimple => Parts.Count == 1; + /// + /// Gets the list of parts in this segment. + /// public IReadOnlyList Parts { get; } internal string DebuggerToString() diff --git a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternSeparatorPart.cs b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternSeparatorPart.cs index 19333a9467..5512e62af4 100644 --- a/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternSeparatorPart.cs +++ b/src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternSeparatorPart.cs @@ -5,6 +5,27 @@ using System.Diagnostics; namespace Microsoft.AspNetCore.Routing.Patterns { + /// + /// Represents an optional separator part of a route pattern. Instances of + /// are immutable. + /// + /// + /// + /// An optional separator is a literal text delimiter that appears between + /// two parameter parts in the last segment of a route pattern. The only separator + /// that is recognized is .. + /// + /// + /// + /// In the route pattern /{controller}/{action}/{id?}.{extension?} + /// the . character is an optional separator. + /// + /// + /// + /// An optional separator character does not need to present in the URL path + /// of a request for the route pattern to match. + /// + /// [DebuggerDisplay("{DebuggerToString()}")] public sealed class RoutePatternSeparatorPart : RoutePatternPart { @@ -16,6 +37,9 @@ namespace Microsoft.AspNetCore.Routing.Patterns Content = content; } + /// + /// Gets the text content of the part. + /// public string Content { get; } internal override string DebuggerToString()