huahaofeng
/
aspnetcore
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Dairai/add http class descriptions (#17349)

This commit is contained in:
Andrew Stanton-Nurse 2019-12-05 09:28:29 -08:00 committed by GitHub
parent 5033efb3fe d4f380f67a
commit 06a85e5db2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 163 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
src/Http/Http.Abstractions/src/HttpMethods.cs
View File

@ -5,12 +5,15 @@ using System;
namespace Microsoft.AspNetCore.Http
{
/// <summary>
/// Contains methods to verify the request method of an HTTP request.
/// </summary>
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";
/// <summary>
/// Returns a value that indicates if the HTTP request method is CONNECT.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is CONNECT; otherwise, <see langword="false" />.
/// </returns>
public static bool IsConnect(string method)
{
return object.ReferenceEquals(Connect, method) || StringComparer.OrdinalIgnoreCase.Equals(Connect, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is DELETE.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is DELETE; otherwise, <see langword="false" />.
/// </returns>
public static bool IsDelete(string method)
{
return object.ReferenceEquals(Delete, method) || StringComparer.OrdinalIgnoreCase.Equals(Delete, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is GET.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is GET; otherwise, <see langword="false" />.
/// </returns>
public static bool IsGet(string method)
{
return object.ReferenceEquals(Get, method) || StringComparer.OrdinalIgnoreCase.Equals(Get, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is HEAD.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is HEAD; otherwise, <see langword="false" />.
/// </returns>
public static bool IsHead(string method)
{
return object.ReferenceEquals(Head, method) || StringComparer.OrdinalIgnoreCase.Equals(Head, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is OPTIONS.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is OPTIONS; otherwise, <see langword="false" />.
/// </returns>
public static bool IsOptions(string method)
{
return object.ReferenceEquals(Options, method) || StringComparer.OrdinalIgnoreCase.Equals(Options, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is PATCH.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is PATCH; otherwise, <see langword="false" />.
/// </returns>
public static bool IsPatch(string method)
{
return object.ReferenceEquals(Patch, method) || StringComparer.OrdinalIgnoreCase.Equals(Patch, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is POST.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is POST; otherwise, <see langword="false" />.
/// </returns>
public static bool IsPost(string method)
{
return object.ReferenceEquals(Post, method) || StringComparer.OrdinalIgnoreCase.Equals(Post, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is PUT.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is PUT; otherwise, <see langword="false" />.
/// </returns>
public static bool IsPut(string method)
{
return object.ReferenceEquals(Put, method) || StringComparer.OrdinalIgnoreCase.Equals(Put, method);
}
/// <summary>
/// Returns a value that indicates if the HTTP request method is TRACE.
/// </summary>
/// <param name="method">The HTTP request method.</param>
/// <returns>
/// <see langword="true" /> if the method is TRACE; otherwise, <see langword="false" />.
/// </returns>
public static bool IsTrace(string method)
{
return object.ReferenceEquals(Trace, method) || StringComparer.OrdinalIgnoreCase.Equals(Trace, method);

44
src/Http/Http/src/DefaultHttpContext.cs
View File

@ -13,6 +13,9 @@ using Microsoft.Extensions.DependencyInjection;
namespace Microsoft.AspNetCore.Http
{
/// <summary>
/// Represents an implementation of the HTTP Context class.
/// </summary>
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;
/// <summary>
/// Initializes a new instance of the <see cref="DefaultHttpContext"/> class.
/// </summary>
public DefaultHttpContext()
: this(new FeatureCollection())
{
@ -40,6 +46,10 @@ namespace Microsoft.AspNetCore.Http
Features.Set<IHttpResponseBodyFeature>(new StreamResponseBodyFeature(Stream.Null));
}
/// <summary>
/// Initializes a new instance of the <see cref="DefaultHttpContext"/> class with provided features.
/// </summary>
/// <param name="features">Initial set of features for the <see cref="DefaultHttpContext"/>.</param>
public DefaultHttpContext(IFeatureCollection features)
{
_features.Initalize(features);
@ -47,6 +57,13 @@ namespace Microsoft.AspNetCore.Http
_response = new DefaultHttpResponse(this);
}
/// <summary>
/// Reinitialize the current instant of the class with features passed in.
/// </summary>
/// <remarks>
/// This method allows the consumer to re-use the <see cref="DefaultHttpContext" /> for another request, rather than having to allocate a new instance.
/// </remarks>
/// <param name="features">The new set of features for the <see cref="DefaultHttpContext" />.</param>
public void Initialize(IFeatureCollection features)
{
var revision = features.Revision;
@ -57,6 +74,9 @@ namespace Microsoft.AspNetCore.Http
_websockets?.Initialize(features, revision);
}
/// <summary>
/// Uninitialize all the features in the <see cref="DefaultHttpContext" />.
/// </summary>
public void Uninitialize()
{
_features = default;
@ -66,8 +86,20 @@ namespace Microsoft.AspNetCore.Http
_websockets?.Uninitialize();
}
/// <summary>
/// Gets or set the <see cref="FormOptions" /> for this instance.
/// </summary>
/// <returns>
/// <see cref="FormOptions"/>
/// </returns>
public FormOptions FormOptions { get; set; }
/// <summary>
/// Gets or sets the <see cref="IServiceScopeFactory" /> for this instance.
/// </summary>
/// <returns>
/// <see cref="IServiceScopeFactory"/>
/// </returns>
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);
/// <inheritdoc/>
public override IFeatureCollection Features => _features.Collection ?? ContextDisposed();
/// <inheritdoc/>
public override HttpRequest Request => _request;
/// <inheritdoc/>
public override HttpResponse Response => _response;
/// <inheritdoc/>
public override ConnectionInfo Connection => _connection ?? (_connection = new DefaultConnectionInfo(Features));
/// <inheritdoc/>
public override WebSocketManager WebSockets => _websockets ?? (_websockets = new DefaultWebSocketManager(Features));
/// <inheritdoc/>
public override ClaimsPrincipal User
{
get
@ -117,30 +155,35 @@ namespace Microsoft.AspNetCore.Http
set { HttpAuthenticationFeature.User = value; }
}
/// <inheritdoc/>
public override IDictionary<object, object> Items
{
get { return ItemsFeature.Items; }
set { ItemsFeature.Items = value; }
}
/// <inheritdoc/>
public override IServiceProvider RequestServices
{
get { return ServiceProvidersFeature.RequestServices; }
set { ServiceProvidersFeature.RequestServices = value; }
}
/// <inheritdoc/>
public override CancellationToken RequestAborted
{
get { return LifetimeFeature.RequestAborted; }
set { LifetimeFeature.RequestAborted = value; }
}
/// <inheritdoc/>
public override string TraceIdentifier
{
get { return RequestIdentifierFeature.TraceIdentifier; }
set { RequestIdentifierFeature.TraceIdentifier = value; }
}
/// <inheritdoc/>
public override ISession Session
{
get
@ -166,6 +209,7 @@ namespace Microsoft.AspNetCore.Http
[EditorBrowsable(EditorBrowsableState.Never)]
public HttpContext HttpContext => this;
/// <inheritdoc/>
public override void Abort()
{
LifetimeFeature.Abort();

4
src/Http/Http/src/HttpContextAccessor.cs
View File

@ -5,10 +5,14 @@ using System.Threading;
namespace Microsoft.AspNetCore.Http
{
/// <summary>
/// Provides an implementation of <see cref="IHttpContextAccessor" /> based on the current execution context.
/// </summary>
public class HttpContextAccessor : IHttpContextAccessor
{
private static AsyncLocal<HttpContextHolder> _httpContextCurrent = new AsyncLocal<HttpContextHolder>();
/// <inheritdoc/>
public HttpContext HttpContext
{
get

31
src/Http/Http/src/HttpContextFactory.cs
View File

@ -8,6 +8,9 @@ using Microsoft.Extensions.Options;
namespace Microsoft.AspNetCore.Http
{
/// <summary>
/// Represents methods used to create an HTTP context object.
/// </summary>
[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;
/// <summary>
/// Initializes a new instance of the HttpContext class with options passed in.
/// </summary>
/// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
public HttpContextFactory(IOptions<FormOptions> formOptions)
: this(formOptions, serviceScopeFactory: null)
{
}
/// <summary>
/// Initializes a new instance of the DefaultHttpContext class with options passed in.
/// </summary>
/// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
/// <param name="serviceScopeFactory">Factory object used to create the service scope for the HTTP context.</param>
public HttpContextFactory(IOptions<FormOptions> formOptions, IServiceScopeFactory serviceScopeFactory)
: this(formOptions, serviceScopeFactory, httpContextAccessor: null)
{
}
/// <summary>
/// Initializes a new instance of the DefaultHttpContext class with options passed in.
/// </summary>
/// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
/// <param name="httpContextAccessor">Object to be used to access the HTTP context instance.</param>
public HttpContextFactory(IOptions<FormOptions> formOptions, IHttpContextAccessor httpContextAccessor)
: this(formOptions, serviceScopeFactory: null, httpContextAccessor: httpContextAccessor)
{
}
/// <summary>
/// Initializes a new instance of the DefaultHttpContext class with options passed in.
/// </summary>
/// <param name="formOptions">Options to set when instantianting the HTTP context object.</param>
/// <param name="serviceScopeFactory">Factory object used to create the service scope for the HTTP context.</param>
/// <param name="httpContextAccessor">Options to set when instantianting the Default HTTP context object.</param>
public HttpContextFactory(IOptions<FormOptions> formOptions, IServiceScopeFactory serviceScopeFactory, IHttpContextAccessor httpContextAccessor)
{
if (formOptions == null)
@ -47,6 +70,10 @@ namespace Microsoft.AspNetCore.Http
_httpContextAccessor = httpContextAccessor;
}
/// <summary>
/// Initializes a new instance of the DefaultHttpContext class with options passed in.
/// </summary>
/// <param name="featureCollection">Options to set when instantianting the Default HTTP context object.</param>
public HttpContext Create(IFeatureCollection featureCollection)
{
if (featureCollection == null)
@ -66,6 +93,10 @@ namespace Microsoft.AspNetCore.Http
return httpContext;
}
/// <summary>
/// Sets the HTTP context object to null for garbage collection.
/// </summary>
/// <param name="httpContext">HTTP context to dispose.</param>
public void Dispose(HttpContext httpContext)
{
if (_httpContextAccessor != null)

11
src/Middleware/HttpsPolicy/src/HttpsRedirectionMiddleware.cs
View File

@ -13,6 +13,9 @@ using Microsoft.Net.Http.Headers;
namespace Microsoft.AspNetCore.HttpsPolicy
{
/// <summary>
/// Middleware that redirects non-HTTPS requests to an HTTPS URL.
/// </summary>
public class HttpsRedirectionMiddleware
{
private const int PortNotFound = -1;
@ -26,7 +29,7 @@ namespace Microsoft.AspNetCore.HttpsPolicy
private readonly ILogger _logger;
/// <summary>
/// Initializes the HttpsRedirectionMiddleware
/// Initializes <see cref="HttpsRedirectionMiddleware" />.
/// </summary>
/// <param name="next"></param>
/// <param name="options"></param>
@ -56,13 +59,13 @@ namespace Microsoft.AspNetCore.HttpsPolicy
}
/// <summary>
/// Initializes the HttpsRedirectionMiddleware
/// Initializes <see cref="HttpsRedirectionMiddleware" />.
/// </summary>
/// <param name="next"></param>
/// <param name="options"></param>
/// <param name="config"></param>
/// <param name="loggerFactory"></param>
/// <param name="serverAddressesFeature">The</param>
/// <param name="serverAddressesFeature"></param>
public HttpsRedirectionMiddleware(RequestDelegate next, IOptions<HttpsRedirectionOptions> options, IConfiguration config, ILoggerFactory loggerFactory,
IServerAddressesFeature serverAddressesFeature)
: this(next, options, config, loggerFactory)
@ -71,7 +74,7 @@ namespace Microsoft.AspNetCore.HttpsPolicy
}
/// <summary>
/// Invokes the HttpsRedirectionMiddleware
/// Invokes the HttpsRedirectionMiddleware.
/// </summary>
/// <param name="context"></param>
/// <returns></returns>

2
src/Middleware/HttpsPolicy/src/HttpsRedirectionOptions.cs
View File

@ -6,7 +6,7 @@ using Microsoft.AspNetCore.Http;
namespace Microsoft.AspNetCore.HttpsPolicy
{
/// <summary>
/// Options for the HttpsRedirection middleware
/// Options for the HTTPS Redirection Middleware.
/// </summary>
public class HttpsRedirectionOptions
{

13
src/Servers/HttpSys/src/WebHostBuilderHttpSysExtensions.cs
View File

@ -9,16 +9,19 @@ using Microsoft.Extensions.Options;
namespace Microsoft.AspNetCore.Hosting
{
/// <summary>
/// Provides extensions method to use Http.sys as the server for the web host.
/// </summary>
public static class WebHostBuilderHttpSysExtensions
{
/// <summary>
/// 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.
/// </summary>
/// <param name="hostBuilder">
/// The Microsoft.AspNetCore.Hosting.IWebHostBuilder to configure.
/// </param>
/// <returns>
/// The Microsoft.AspNetCore.Hosting.IWebHostBuilder.
/// A reference to the <see cref="IWebHostBuilder" /> parameter object.
/// </returns>
public static IWebHostBuilder UseHttpSys(this IWebHostBuilder hostBuilder)
{
@ -38,16 +41,16 @@ namespace Microsoft.AspNetCore.Hosting
}
/// <summary>
/// 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.
/// </summary>
/// <param name="hostBuilder">
/// The Microsoft.AspNetCore.Hosting.IWebHostBuilder to configure.
/// </param>
/// <param name="options">
/// A callback to configure HttpSys options.
/// A callback to configure Http.sys options.
/// </param>
/// <returns>
/// The Microsoft.AspNetCore.Hosting.IWebHostBuilder.
/// A reference to the <see cref="IWebHostBuilder" /> parameter object.
/// </returns>
public static IWebHostBuilder UseHttpSys(this IWebHostBuilder hostBuilder, Action<HttpSysOptions> options)
{