diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/HttpResponseWritingExtensions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/HttpResponseWritingExtensions.cs index 953cd7ce6e..fd0553b3c0 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/HttpResponseWritingExtensions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/HttpResponseWritingExtensions.cs @@ -16,10 +16,10 @@ namespace Microsoft.AspNet.Http /// /// Writes the given text to the response body. UTF-8 encoding will be used. /// - /// - /// - /// - /// + /// The . + /// The text to write to the response. + /// Notifies when request operations should be cancelled. + /// A task that represents the completion of the write operation. public static Task WriteAsync(this HttpResponse response, string text, CancellationToken cancellationToken = default(CancellationToken)) { if (response == null) @@ -38,11 +38,11 @@ namespace Microsoft.AspNet.Http /// /// Writes the given text to the response body using the given encoding. /// - /// - /// - /// - /// - /// + /// The . + /// The text to write to the response. + /// The encoding to use. + /// Notifies when request operations should be cancelled. + /// A task that represents the completion of the write operation. public static Task WriteAsync(this HttpResponse response, string text, Encoding encoding, CancellationToken cancellationToken = default(CancellationToken)) { if (response == null) diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapExtensions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapExtensions.cs index 94985df589..c06c37563a 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapExtensions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapExtensions.cs @@ -7,16 +7,19 @@ using Microsoft.AspNet.Builder.Extensions; namespace Microsoft.AspNet.Builder { + /// + /// Extension methods for the . + /// public static class MapExtensions { /// - /// If the request path starts with the given pathMatch, execute the app configured via configuration parameter instead of - /// continuing to the next component in the pipeline. + /// Branches the request pipeline based on matches of the given request path. If the request path starts with + /// the given path, the branch is executed. /// - /// - /// The path to match - /// The branch to take for positive path matches - /// + /// The instance. + /// The request path to match. + /// The branch to take for positive path matches. + /// The instance. public static IApplicationBuilder Map(this IApplicationBuilder app, PathString pathMatch, Action configuration) { if (app == null) @@ -39,7 +42,7 @@ namespace Microsoft.AspNet.Builder configuration(branchBuilder); var branch = branchBuilder.Build(); - var options = new MapOptions() + var options = new MapOptions { Branch = branch, PathMatch = pathMatch, diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapMiddleware.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapMiddleware.cs index f35e0a5480..2b2c80b06f 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapMiddleware.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapMiddleware.cs @@ -7,11 +7,19 @@ using Microsoft.AspNet.Http; namespace Microsoft.AspNet.Builder.Extensions { + /// + /// Respresents a middleware that maps a request path to a sub-request pipeline. + /// public class MapMiddleware { private readonly RequestDelegate _next; private readonly MapOptions _options; + /// + /// Creates a new instace of . + /// + /// The delegate representing the next middleware in the request pipeline. + /// The middleware options. public MapMiddleware(RequestDelegate next, MapOptions options) { if (next == null) @@ -28,6 +36,11 @@ namespace Microsoft.AspNet.Builder.Extensions _options = options; } + /// + /// Executes the middleware. + /// + /// The for the current request. + /// A task that represents the execution of this middleware. public async Task Invoke(HttpContext context) { if (context == null) diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapOptions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapOptions.cs index d0453902f4..dc16d15482 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapOptions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapOptions.cs @@ -6,17 +6,17 @@ using Microsoft.AspNet.Http; namespace Microsoft.AspNet.Builder.Extensions { /// - /// Options for the Map middleware + /// Options for the . /// public class MapOptions { /// - /// The path to match + /// The path to match. /// public PathString PathMatch { get; set; } /// - /// The branch taken for a positive match + /// The branch taken for a positive match. /// public RequestDelegate Branch { get; set; } } diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenExtensions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenExtensions.cs index cabe45094d..7bd658460e 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenExtensions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenExtensions.cs @@ -11,7 +11,7 @@ namespace Microsoft.AspNet.Builder using Predicate = Func; /// - /// Extension methods for the MapWhenMiddleware + /// Extension methods for the . /// public static class MapWhenExtensions { diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenMiddleware.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenMiddleware.cs index b1ac27f800..26ba9f0d81 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenMiddleware.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenMiddleware.cs @@ -7,11 +7,19 @@ using Microsoft.AspNet.Http; namespace Microsoft.AspNet.Builder.Extensions { + /// + /// Respresents a middleware that runs a sub-request pipeline when a given predicate is matched. + /// public class MapWhenMiddleware { private readonly RequestDelegate _next; private readonly MapWhenOptions _options; + /// + /// Creates a new instance of . + /// + /// The delegate representing the next middleware in the request pipeline. + /// The middleware options. public MapWhenMiddleware(RequestDelegate next, MapWhenOptions options) { if (next == null) @@ -28,6 +36,11 @@ namespace Microsoft.AspNet.Builder.Extensions _options = options; } + /// + /// Executes the middleware. + /// + /// The for the current request. + /// A task that represents the execution of this middleware. public async Task Invoke(HttpContext context) { if (context == null) diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenOptions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenOptions.cs index aa6263366e..9b430b2d4d 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenOptions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenOptions.cs @@ -7,14 +7,14 @@ using Microsoft.AspNet.Http; namespace Microsoft.AspNet.Builder.Extensions { /// - /// Options for the MapWhen middleware + /// Options for the . /// public class MapWhenOptions { private Func _predicate; /// - /// The user callback that determines if the branch should be taken + /// The user callback that determines if the branch should be taken. /// public Func Predicate { @@ -34,7 +34,7 @@ namespace Microsoft.AspNet.Builder.Extensions } /// - /// The branch taken for a positive match + /// The branch taken for a positive match. /// public RequestDelegate Branch { get; set; } } diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/RunExtensions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/RunExtensions.cs index d79949c5c8..8280b285ce 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/RunExtensions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/RunExtensions.cs @@ -5,8 +5,16 @@ using System; namespace Microsoft.AspNet.Builder { + /// + /// Extension methods for adding terminal middleware. + /// public static class RunExtensions { + /// + /// Adds a terminal middleware delagate to the application's request pipeline. + /// + /// The instance. + /// A delegate that handles the request. public static void Run(this IApplicationBuilder app, RequestDelegate handler) { if (app == null) diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseExtensions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseExtensions.cs index 1a14048128..163dcfd19f 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseExtensions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseExtensions.cs @@ -7,14 +7,17 @@ using Microsoft.AspNet.Http; namespace Microsoft.AspNet.Builder { + /// + /// Extension methods for adding middleware. + /// public static class UseExtensions { /// - /// Use middleware defined in-line. + /// Adds a middleware delagate defined in-line to the application's request pipeline. /// - /// + /// The instance. /// A function that handles the request or calls the given next function. - /// + /// The instance. public static IApplicationBuilder Use(this IApplicationBuilder app, Func, Task> middleware) { return app.Use(next => diff --git a/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseMiddlewareExtensions.cs b/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseMiddlewareExtensions.cs index cac2100ce3..fe13dab8c8 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseMiddlewareExtensions.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/Extensions/UseMiddlewareExtensions.cs @@ -11,18 +11,36 @@ using Microsoft.Extensions.Internal; namespace Microsoft.AspNet.Builder { + /// + /// Extension methods for adding typed middlware. + /// public static class UseMiddlewareExtensions { const string InvokeMethodName = "Invoke"; - public static IApplicationBuilder UseMiddleware(this IApplicationBuilder builder, params object[] args) + + /// + /// Adds a middleware type to the application's request pipeline. + /// + /// The middleware type. + /// The instance. + /// The arguments to pass to the middleware type instance's constructor. + /// The instance. + public static IApplicationBuilder UseMiddleware(this IApplicationBuilder app, params object[] args) { - return builder.UseMiddleware(typeof(T), args); + return app.UseMiddleware(typeof(TMiddleware), args); } - public static IApplicationBuilder UseMiddleware(this IApplicationBuilder builder, Type middleware, params object[] args) + /// + /// Adds a middleware type to the application's request pipeline. + /// + /// The instance. + /// The middleware type. + /// The arguments to pass to the middleware type instance's constructor. + /// The instance. + public static IApplicationBuilder UseMiddleware(this IApplicationBuilder app, Type middleware, params object[] args) { - var applicationServices = builder.ApplicationServices; - return builder.Use(next => + var applicationServices = app.ApplicationServices; + return app.Use(next => { var methods = middleware.GetMethods(BindingFlags.Instance | BindingFlags.Public); var invokeMethods = methods.Where(m => string.Equals(m.Name, InvokeMethodName, StringComparison.Ordinal)).ToArray(); @@ -48,7 +66,7 @@ namespace Microsoft.AspNet.Builder throw new InvalidOperationException(Resources.FormatException_UseMiddlewareNoParameters(InvokeMethodName,nameof(HttpContext))); } - var instance = ActivatorUtilities.CreateInstance(builder.ApplicationServices, middleware, new[] { next }.Concat(args).ToArray()); + var instance = ActivatorUtilities.CreateInstance(app.ApplicationServices, middleware, new[] { next }.Concat(args).ToArray()); if (parameters.Length == 1) { return (RequestDelegate)methodinfo.CreateDelegate(typeof(RequestDelegate), instance); diff --git a/src/Microsoft.AspNet.Http.Abstractions/HttpContext.cs b/src/Microsoft.AspNet.Http.Abstractions/HttpContext.cs index 191d0a5d42..162f3c582d 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/HttpContext.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/HttpContext.cs @@ -10,34 +10,80 @@ using Microsoft.AspNet.Http.Features; namespace Microsoft.AspNet.Http { + /// + /// Encapsulates all HTTP-specific information about an individual HTTP request. + /// public abstract class HttpContext { + /// + /// Gets the collection of HTTP features provided by the server and middleware available on this request. + /// public abstract IFeatureCollection Features { get; } + /// + /// Gets the object for this request. + /// public abstract HttpRequest Request { get; } + /// + /// Gets the object for this request. + /// public abstract HttpResponse Response { get; } + /// + /// Gets information about the underlying connection for this request. + /// public abstract ConnectionInfo Connection { get; } + /// + /// Gets an object that manages the establishment of WebSocket connections for this request. + /// public abstract WebSocketManager WebSockets { get; } + /// + /// Gets an object that facilitates authentication for this request. + /// public abstract AuthenticationManager Authentication { get; } + /// + /// Gets or sets the the user for this request. + /// public abstract ClaimsPrincipal User { get; set; } + /// + /// Gets or sets a key/value collection that can be used to share data within the scope of this request. + /// public abstract IDictionary Items { get; set; } + /// + /// Gets or sets the that provides access to the application's service container. + /// public abstract IServiceProvider ApplicationServices { get; set; } + /// + /// Gets or sets the that provides access to the request's service container. + /// public abstract IServiceProvider RequestServices { get; set; } + /// + /// Notifies when the connection underlying this request is aborted and thus request operations should be + /// cancelled. + /// public abstract CancellationToken RequestAborted { get; set; } + /// + /// Gets or sets a unique identifier to represent this request in trace logs. + /// public abstract string TraceIdentifier { get; set; } + /// + /// Gets or sets the object used to manage user session data for this request. + /// public abstract ISession Session { get; set; } + /// + /// Aborts the connection underlying this request. + /// public abstract void Abort(); } } diff --git a/src/Microsoft.AspNet.Http.Abstractions/HttpRequest.cs b/src/Microsoft.AspNet.Http.Abstractions/HttpRequest.cs index 4cbbf62a6f..283eddf4b8 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/HttpRequest.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/HttpRequest.cs @@ -7,8 +7,14 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Http { + /// + /// Represents the incoming side of an individual HTTP request. + /// public abstract class HttpRequest { + /// + /// Gets the this request; + /// public abstract HttpContext HttpContext { get; } /// diff --git a/src/Microsoft.AspNet.Http.Abstractions/HttpResponse.cs b/src/Microsoft.AspNet.Http.Abstractions/HttpResponse.cs index 195ef02330..1e3344459c 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/HttpResponse.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/HttpResponse.cs @@ -7,6 +7,9 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Http { + /// + /// Represents the outgoing side of an individual HTTP request. + /// public abstract class HttpResponse { private static readonly Func _callbackDelegate = callback => ((Func)callback)(); @@ -16,34 +19,89 @@ namespace Microsoft.AspNet.Http return Task.FromResult(0); }; + /// + /// Gets the for this request. + /// public abstract HttpContext HttpContext { get; } + /// + /// Gets or sets the HTTP response code. + /// public abstract int StatusCode { get; set; } + /// + /// Gets the response headers. + /// public abstract IHeaderDictionary Headers { get; } + /// + /// Gets the response body . + /// public abstract Stream Body { get; set; } + /// + /// Gets or sets the value for the Content-Length response header. + /// public abstract long? ContentLength { get; set; } + /// + /// Gets or sets the value for the Content-Type response header. + /// public abstract string ContentType { get; set; } + /// + /// Gets an object that can be used to manage cookies for this response. + /// public abstract IResponseCookies Cookies { get; } + /// + /// Gets a value indicating whether response headers have been sent to the client. + /// public abstract bool HasStarted { get; } + /// + /// Adds a delegate to be invoked just before response headers will be sent to the client. + /// + /// The delegate to execute. + /// A state object to capture and pass back to the delegate. public abstract void OnStarting(Func callback, object state); + /// + /// Adds a delegate to be invoked just before response headers will be sent to the client. + /// + /// The delegate to execute. public virtual void OnStarting(Func callback) => OnStarting(_callbackDelegate, callback); + /// + /// Adds a delegate to be invoked after the response has finished being sent to the client. + /// + /// The delegate to invoke. + /// A state object to capture and pass back to the delegate. public abstract void OnCompleted(Func callback, object state); + /// + /// Registers an object for disposal by the host once the request has finished processing. + /// + /// The object to be disposed. public virtual void RegisterForDispose(IDisposable disposable) => OnCompleted(_disposeDelegate, disposable); + /// + /// Adds a delegate to be invoked after the response has finished being sent to the client. + /// + /// The delegate to invoke. public virtual void OnCompleted(Func callback) => OnCompleted(_callbackDelegate, callback); + /// + /// Returns a temporary redirect response (HTTP 302) to the client. + /// + /// The URL to redirect the client to. public virtual void Redirect(string location) => Redirect(location, permanent: false); + /// + /// Returns a redirect response (HTTP 301 or HTTP 302) to the client. + /// + /// The URL to redirect the client to. + /// True if the redirect is permanent (301), otherwise false (302). public abstract void Redirect(string location, bool permanent); } } diff --git a/src/Microsoft.AspNet.Http.Abstractions/IApplicationBuilder.cs b/src/Microsoft.AspNet.Http.Abstractions/IApplicationBuilder.cs index e74bdec015..342b7b4f30 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/IApplicationBuilder.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/IApplicationBuilder.cs @@ -7,18 +7,44 @@ using Microsoft.AspNet.Http.Features; namespace Microsoft.AspNet.Builder { + /// + /// Defines a class that provides the mechanisms to configure an application's request pipeline. + /// public interface IApplicationBuilder { + /// + /// Gets or sets the that provides access to the application's service container. + /// IServiceProvider ApplicationServices { get; set; } + /// + /// Gets the set of HTTP features the application's server provides. + /// IFeatureCollection ServerFeatures { get; } + /// + /// Gets a key/value collection that can be used to share data between middleware. + /// IDictionary Properties { get; } + /// + /// Adds a middleware delegate to the application's request pipeline. + /// + /// The middleware delgate. + /// The . IApplicationBuilder Use(Func middleware); + /// + /// Creates a new that shares the of this + /// . + /// + /// The new . IApplicationBuilder New(); + /// + /// Builds the delegate used by this application to process HTTP requests. + /// + /// The request handling delegate. RequestDelegate Build(); } } diff --git a/src/Microsoft.AspNet.Http.Abstractions/RequestDelegate.cs b/src/Microsoft.AspNet.Http.Abstractions/RequestDelegate.cs index c4c2f8d94e..87d215ad6f 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/RequestDelegate.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/RequestDelegate.cs @@ -6,5 +6,10 @@ using Microsoft.AspNet.Http; namespace Microsoft.AspNet.Builder { + /// + /// A function that can process an HTTP request. + /// + /// The for the request. + /// A task that represents the completion of request processing. public delegate Task RequestDelegate(HttpContext context); } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Http.Abstractions/WebSocketManager.cs b/src/Microsoft.AspNet.Http.Abstractions/WebSocketManager.cs index b1dd679ef0..e569e549b9 100644 --- a/src/Microsoft.AspNet.Http.Abstractions/WebSocketManager.cs +++ b/src/Microsoft.AspNet.Http.Abstractions/WebSocketManager.cs @@ -7,17 +7,35 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Http { + /// + /// Manages the establishment of WebSocket connections for a specific HTTP request. + /// public abstract class WebSocketManager { + /// + /// Gets a value indicating whether the request is a WebSocket establishment request. + /// public abstract bool IsWebSocketRequest { get; } + /// + /// Gets the list of requested WebSocket sub-protocols. + /// public abstract IList WebSocketRequestedProtocols { get; } + /// + /// Transitions the request to a WebSocket connection. + /// + /// A task representing the completion of the transition. public virtual Task AcceptWebSocketAsync() { return AcceptWebSocketAsync(subProtocol: null); } + /// + /// Transitions the request to a WebSocket connection using the specified sub-protocol. + /// + /// The sub-protocol to use. + /// A task representing the completion of the transition. public abstract Task AcceptWebSocketAsync(string subProtocol); } } diff --git a/src/Microsoft.AspNet.Http.Features/IFeatureCollection.cs b/src/Microsoft.AspNet.Http.Features/IFeatureCollection.cs index 8da86ea5b9..c7ad165c66 100644 --- a/src/Microsoft.AspNet.Http.Features/IFeatureCollection.cs +++ b/src/Microsoft.AspNet.Http.Features/IFeatureCollection.cs @@ -6,6 +6,9 @@ using System.Collections.Generic; namespace Microsoft.AspNet.Http.Features { + /// + /// Represents a collection of HTTP features. + /// public interface IFeatureCollection : IEnumerable> { /// @@ -14,7 +17,7 @@ namespace Microsoft.AspNet.Http.Features bool IsReadOnly { get; } /// - /// Incremented for each modification and can be used verify cached results. + /// Incremented for each modification and can be used to verify cached results. /// int Revision { get; }