diff --git a/src/Http/Http.Abstractions/src/HttpMethods.cs b/src/Http/Http.Abstractions/src/HttpMethods.cs index 05a5f2e834..350b98faf2 100644 --- a/src/Http/Http.Abstractions/src/HttpMethods.cs +++ b/src/Http/Http.Abstractions/src/HttpMethods.cs @@ -5,12 +5,15 @@ using System; namespace Microsoft.AspNetCore.Http { + /// + /// Contains methods to verify the request method of an HTTP request. + /// public static class HttpMethods { // We are intentionally using 'static readonly' here instead of 'const'. - // 'const' values would be embedded in to each assembly that used them + // 'const' values would be embedded into each assembly that used them // and each consuming assembly would have a different 'string' instance. - // Using .'static readonly' means that all consumers get thee exact same + // Using .'static readonly' means that all consumers get these exact same // 'string' instance, which means the 'ReferenceEquals' checks below work // and allow us to optimize comparisons when these constants are used. @@ -25,46 +28,109 @@ namespace Microsoft.AspNetCore.Http public static readonly string Put = "PUT"; public static readonly string Trace = "TRACE"; + /// + /// Returns a value that indicates if the HTTP request method is CONNECT. + /// + /// The HTTP request method. + /// + /// if the method is CONNECT; otherwise, . + /// public static bool IsConnect(string method) { return object.ReferenceEquals(Connect, method) || StringComparer.OrdinalIgnoreCase.Equals(Connect, method); } + /// + /// Returns a value that indicates if the HTTP request method is DELETE. + /// + /// The HTTP request method. + /// + /// if the method is DELETE; otherwise, . + /// public static bool IsDelete(string method) { return object.ReferenceEquals(Delete, method) || StringComparer.OrdinalIgnoreCase.Equals(Delete, method); } + /// + /// Returns a value that indicates if the HTTP request method is GET. + /// + /// The HTTP request method. + /// + /// if the method is GET; otherwise, . + /// public static bool IsGet(string method) { return object.ReferenceEquals(Get, method) || StringComparer.OrdinalIgnoreCase.Equals(Get, method); } + /// + /// Returns a value that indicates if the HTTP request method is HEAD. + /// + /// The HTTP request method. + /// + /// if the method is HEAD; otherwise, . + /// public static bool IsHead(string method) { return object.ReferenceEquals(Head, method) || StringComparer.OrdinalIgnoreCase.Equals(Head, method); } + /// + /// Returns a value that indicates if the HTTP request method is OPTIONS. + /// + /// The HTTP request method. + /// + /// if the method is OPTIONS; otherwise, . + /// public static bool IsOptions(string method) { return object.ReferenceEquals(Options, method) || StringComparer.OrdinalIgnoreCase.Equals(Options, method); } + /// + /// Returns a value that indicates if the HTTP request method is PATCH. + /// + /// The HTTP request method. + /// + /// if the method is PATCH; otherwise, . + /// public static bool IsPatch(string method) { return object.ReferenceEquals(Patch, method) || StringComparer.OrdinalIgnoreCase.Equals(Patch, method); } + /// + /// Returns a value that indicates if the HTTP request method is POST. + /// + /// The HTTP request method. + /// + /// if the method is POST; otherwise, . + /// public static bool IsPost(string method) { return object.ReferenceEquals(Post, method) || StringComparer.OrdinalIgnoreCase.Equals(Post, method); } + /// + /// Returns a value that indicates if the HTTP request method is PUT. + /// + /// The HTTP request method. + /// + /// if the method is PUT; otherwise, . + /// public static bool IsPut(string method) { return object.ReferenceEquals(Put, method) || StringComparer.OrdinalIgnoreCase.Equals(Put, method); } + /// + /// Returns a value that indicates if the HTTP request method is TRACE. + /// + /// The HTTP request method. + /// + /// if the method is TRACE; otherwise, . + /// public static bool IsTrace(string method) { return object.ReferenceEquals(Trace, method) || StringComparer.OrdinalIgnoreCase.Equals(Trace, method); diff --git a/src/Http/Http/src/DefaultHttpContext.cs b/src/Http/Http/src/DefaultHttpContext.cs index 7d096f186a..59c7739e86 100644 --- a/src/Http/Http/src/DefaultHttpContext.cs +++ b/src/Http/Http/src/DefaultHttpContext.cs @@ -13,6 +13,9 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Http { + /// + /// Represents an implementation of the HTTP Context class. + /// public sealed class DefaultHttpContext : HttpContext { // Lambdas hoisted to static readonly fields to improve inlining https://github.com/dotnet/roslyn/issues/13624 @@ -32,6 +35,9 @@ namespace Microsoft.AspNetCore.Http private DefaultConnectionInfo _connection; private DefaultWebSocketManager _websockets; + /// + /// Initializes a new instance of the class. + /// public DefaultHttpContext() : this(new FeatureCollection()) { @@ -40,6 +46,10 @@ namespace Microsoft.AspNetCore.Http Features.Set(new StreamResponseBodyFeature(Stream.Null)); } + /// + /// Initializes a new instance of the class with provided features. + /// + /// Initial set of features for the . public DefaultHttpContext(IFeatureCollection features) { _features.Initalize(features); @@ -47,6 +57,13 @@ namespace Microsoft.AspNetCore.Http _response = new DefaultHttpResponse(this); } + /// + /// Reinitialize the current instant of the class with features passed in. + /// + /// + /// This method allows the consumer to re-use the for another request, rather than having to allocate a new instance. + /// + /// The new set of features for the . public void Initialize(IFeatureCollection features) { var revision = features.Revision; @@ -57,6 +74,9 @@ namespace Microsoft.AspNetCore.Http _websockets?.Initialize(features, revision); } + /// + /// Uninitialize all the features in the . + /// public void Uninitialize() { _features = default; @@ -66,8 +86,20 @@ namespace Microsoft.AspNetCore.Http _websockets?.Uninitialize(); } + /// + /// Gets or set the for this instance. + /// + /// + /// + /// public FormOptions FormOptions { get; set; } + /// + /// Gets or sets the for this instance. + /// + /// + /// + /// public IServiceScopeFactory ServiceScopeFactory { get; set; } private IItemsFeature ItemsFeature => @@ -92,16 +124,22 @@ namespace Microsoft.AspNetCore.Http private IHttpRequestIdentifierFeature RequestIdentifierFeature => _features.Fetch(ref _features.Cache.RequestIdentifier, _newHttpRequestIdentifierFeature); + /// public override IFeatureCollection Features => _features.Collection ?? ContextDisposed(); + /// public override HttpRequest Request => _request; + /// public override HttpResponse Response => _response; + /// public override ConnectionInfo Connection => _connection ?? (_connection = new DefaultConnectionInfo(Features)); + /// public override WebSocketManager WebSockets => _websockets ?? (_websockets = new DefaultWebSocketManager(Features)); + /// public override ClaimsPrincipal User { get @@ -117,30 +155,35 @@ namespace Microsoft.AspNetCore.Http set { HttpAuthenticationFeature.User = value; } } + /// public override IDictionary Items { get { return ItemsFeature.Items; } set { ItemsFeature.Items = value; } } + /// public override IServiceProvider RequestServices { get { return ServiceProvidersFeature.RequestServices; } set { ServiceProvidersFeature.RequestServices = value; } } + /// public override CancellationToken RequestAborted { get { return LifetimeFeature.RequestAborted; } set { LifetimeFeature.RequestAborted = value; } } + /// public override string TraceIdentifier { get { return RequestIdentifierFeature.TraceIdentifier; } set { RequestIdentifierFeature.TraceIdentifier = value; } } + /// public override ISession Session { get @@ -166,6 +209,7 @@ namespace Microsoft.AspNetCore.Http [EditorBrowsable(EditorBrowsableState.Never)] public HttpContext HttpContext => this; + /// public override void Abort() { LifetimeFeature.Abort(); diff --git a/src/Http/Http/src/HttpContextAccessor.cs b/src/Http/Http/src/HttpContextAccessor.cs index 286151029c..762e454c42 100644 --- a/src/Http/Http/src/HttpContextAccessor.cs +++ b/src/Http/Http/src/HttpContextAccessor.cs @@ -5,10 +5,14 @@ using System.Threading; namespace Microsoft.AspNetCore.Http { + /// + /// Provides an implementation of based on the current execution context. + /// public class HttpContextAccessor : IHttpContextAccessor { private static AsyncLocal _httpContextCurrent = new AsyncLocal(); + /// public HttpContext HttpContext { get diff --git a/src/Http/Http/src/HttpContextFactory.cs b/src/Http/Http/src/HttpContextFactory.cs index 3121c1704b..edddc658d3 100644 --- a/src/Http/Http/src/HttpContextFactory.cs +++ b/src/Http/Http/src/HttpContextFactory.cs @@ -8,6 +8,9 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.Http { + /// + /// Represents methods used to create an HTTP context object. + /// [Obsolete("This is obsolete and will be removed in a future version. Use DefaultHttpContextFactory instead.")] public class HttpContextFactory : IHttpContextFactory { @@ -15,21 +18,41 @@ namespace Microsoft.AspNetCore.Http private readonly FormOptions _formOptions; private readonly IServiceScopeFactory _serviceScopeFactory; + /// + /// Initializes a new instance of the HttpContext class with options passed in. + /// + /// Options to set when instantianting the HTTP context object. public HttpContextFactory(IOptions formOptions) : this(formOptions, serviceScopeFactory: null) { } + /// + /// Initializes a new instance of the DefaultHttpContext class with options passed in. + /// + /// Options to set when instantianting the HTTP context object. + /// Factory object used to create the service scope for the HTTP context. public HttpContextFactory(IOptions formOptions, IServiceScopeFactory serviceScopeFactory) : this(formOptions, serviceScopeFactory, httpContextAccessor: null) { } + /// + /// Initializes a new instance of the DefaultHttpContext class with options passed in. + /// + /// Options to set when instantianting the HTTP context object. + /// Object to be used to access the HTTP context instance. public HttpContextFactory(IOptions formOptions, IHttpContextAccessor httpContextAccessor) : this(formOptions, serviceScopeFactory: null, httpContextAccessor: httpContextAccessor) { } + /// + /// Initializes a new instance of the DefaultHttpContext class with options passed in. + /// + /// Options to set when instantianting the HTTP context object. + /// Factory object used to create the service scope for the HTTP context. + /// Options to set when instantianting the Default HTTP context object. public HttpContextFactory(IOptions formOptions, IServiceScopeFactory serviceScopeFactory, IHttpContextAccessor httpContextAccessor) { if (formOptions == null) @@ -47,6 +70,10 @@ namespace Microsoft.AspNetCore.Http _httpContextAccessor = httpContextAccessor; } + /// + /// Initializes a new instance of the DefaultHttpContext class with options passed in. + /// + /// Options to set when instantianting the Default HTTP context object. public HttpContext Create(IFeatureCollection featureCollection) { if (featureCollection == null) @@ -66,6 +93,10 @@ namespace Microsoft.AspNetCore.Http return httpContext; } + /// + /// Sets the HTTP context object to null for garbage collection. + /// + /// HTTP context to dispose. public void Dispose(HttpContext httpContext) { if (_httpContextAccessor != null) diff --git a/src/Middleware/HttpsPolicy/src/HttpsRedirectionMiddleware.cs b/src/Middleware/HttpsPolicy/src/HttpsRedirectionMiddleware.cs index e20e8b8a33..1a67121215 100644 --- a/src/Middleware/HttpsPolicy/src/HttpsRedirectionMiddleware.cs +++ b/src/Middleware/HttpsPolicy/src/HttpsRedirectionMiddleware.cs @@ -13,6 +13,9 @@ using Microsoft.Net.Http.Headers; namespace Microsoft.AspNetCore.HttpsPolicy { + /// + /// Middleware that redirects non-HTTPS requests to an HTTPS URL. + /// public class HttpsRedirectionMiddleware { private const int PortNotFound = -1; @@ -26,7 +29,7 @@ namespace Microsoft.AspNetCore.HttpsPolicy private readonly ILogger _logger; /// - /// Initializes the HttpsRedirectionMiddleware + /// Initializes . /// /// /// @@ -56,13 +59,13 @@ namespace Microsoft.AspNetCore.HttpsPolicy } /// - /// Initializes the HttpsRedirectionMiddleware + /// Initializes . /// /// /// /// /// - /// The + /// public HttpsRedirectionMiddleware(RequestDelegate next, IOptions options, IConfiguration config, ILoggerFactory loggerFactory, IServerAddressesFeature serverAddressesFeature) : this(next, options, config, loggerFactory) @@ -71,7 +74,7 @@ namespace Microsoft.AspNetCore.HttpsPolicy } /// - /// Invokes the HttpsRedirectionMiddleware + /// Invokes the HttpsRedirectionMiddleware. /// /// /// diff --git a/src/Middleware/HttpsPolicy/src/HttpsRedirectionOptions.cs b/src/Middleware/HttpsPolicy/src/HttpsRedirectionOptions.cs index 07a166c162..0e1c625bd7 100644 --- a/src/Middleware/HttpsPolicy/src/HttpsRedirectionOptions.cs +++ b/src/Middleware/HttpsPolicy/src/HttpsRedirectionOptions.cs @@ -6,7 +6,7 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.HttpsPolicy { /// - /// Options for the HttpsRedirection middleware + /// Options for the HTTPS Redirection Middleware. /// public class HttpsRedirectionOptions { diff --git a/src/Servers/HttpSys/src/WebHostBuilderHttpSysExtensions.cs b/src/Servers/HttpSys/src/WebHostBuilderHttpSysExtensions.cs index 7b4caaef62..f7c2b9445f 100644 --- a/src/Servers/HttpSys/src/WebHostBuilderHttpSysExtensions.cs +++ b/src/Servers/HttpSys/src/WebHostBuilderHttpSysExtensions.cs @@ -9,16 +9,19 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.Hosting { + /// + /// Provides extensions method to use Http.sys as the server for the web host. + /// public static class WebHostBuilderHttpSysExtensions { /// - /// Specify HttpSys as the server to be used by the web host. + /// Specify Http.sys as the server to be used by the web host. /// /// /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder to configure. /// /// - /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder. + /// A reference to the parameter object. /// public static IWebHostBuilder UseHttpSys(this IWebHostBuilder hostBuilder) { @@ -38,16 +41,16 @@ namespace Microsoft.AspNetCore.Hosting } /// - /// Specify HttpSys as the server to be used by the web host. + /// Specify Http.sys as the server to be used by the web host. /// /// /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder to configure. /// /// - /// A callback to configure HttpSys options. + /// A callback to configure Http.sys options. /// /// - /// The Microsoft.AspNetCore.Hosting.IWebHostBuilder. + /// A reference to the parameter object. /// public static IWebHostBuilder UseHttpSys(this IWebHostBuilder hostBuilder, Action options) {