API docs for WebSockets (#26470)

Author: BrennanConroy

src/Middleware/WebSockets/src/ExtendedWebSocketAcceptContext.cs

@@ -6,13 +6,23 @@
 
 namespace Microsoft.AspNetCore.WebSockets
 {
+    /// <summary>
+    /// Extends the <see cref="WebSocketAcceptContext"/> class with additional properties.
+    /// </summary>
     public class ExtendedWebSocketAcceptContext : WebSocketAcceptContext
     {
+        /// <inheritdoc />
         public override string SubProtocol { get; set; }
 
+        /// <summary>
+        /// This property is obsolete and has no effect.
+        /// </summary>
         [Obsolete("Setting this property has no effect. It will be removed in a future version.")]
         public int? ReceiveBufferSize { get; set; }
 
+        /// <summary>
+        /// The interval to send pong frames. This is a heart-beat that keeps the connection alive.
+        /// </summary>
         public TimeSpan? KeepAliveInterval { get; set; }
     }
 }

src/Middleware/WebSockets/src/Microsoft.AspNetCore.WebSockets.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core web socket middleware for use on top of opaque servers.</Description>
@@ -9,6 +9,7 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore</PackageTags>
     <IsPackable>false</IsPackable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Middleware/WebSockets/src/WebSocketMiddleware.cs

@@ -17,6 +17,10 @@
 
 namespace Microsoft.AspNetCore.WebSockets
 {
+    /// <summary>
+    /// Enables accepting WebSocket requests by adding a <see cref="IHttpWebSocketFeature"/>
+    /// to the <see cref="HttpContext"/> if the request is a valid WebSocket request.
+    /// </summary>
     public class WebSocketMiddleware
     {
         private readonly RequestDelegate _next;
@@ -25,6 +29,12 @@ public class WebSocketMiddleware
         private readonly bool _anyOriginAllowed;
         private readonly List<string> _allowedOrigins;
 
+        /// <summary>
+        /// Creates a new instance of the <see cref="WebSocketMiddleware"/>.
+        /// </summary>
+        /// <param name="next">The next middleware in the pipeline.</param>
+        /// <param name="options">The configuration options.</param>
+        /// <param name="loggerFactory">An <see cref="ILoggerFactory"/> instance used to create loggers.</param>
         public WebSocketMiddleware(RequestDelegate next, IOptions<WebSocketOptions> options, ILoggerFactory loggerFactory)
         {
             if (next == null)
@@ -46,6 +56,12 @@ public WebSocketMiddleware(RequestDelegate next, IOptions<WebSocketOptions> opti
             // TODO: validate options.
         }
 
+        /// <summary>
+        /// Processes a request to determine if it is a WebSocket request, and if so,
+        /// sets the <see cref="IHttpWebSocketFeature"/> on the <see cref="HttpContext.Features"/>.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> representing the request.</param>
+        /// <returns>The <see cref="Task"/> that represents the completion of the middleware pipeline.</returns>
         public Task Invoke(HttpContext context)
         {
             // Detect if an opaque upgrade is available. If so, add a websocket upgrade.

src/Middleware/WebSockets/src/WebSocketOptions.cs

@@ -7,10 +7,13 @@
 namespace Microsoft.AspNetCore.Builder
 {
     /// <summary>
-    /// Configuration options for the WebSocketMiddleware
+    /// Configuration options for the WebSocketMiddleware.
     /// </summary>
     public class WebSocketOptions
     {
+        /// <summary>
+        /// Constructs the <see cref="WebSocketOptions"/> class with default values.
+        /// </summary>
         public WebSocketOptions()
         {
             KeepAliveInterval = TimeSpan.FromMinutes(2);

src/Middleware/WebSockets/src/WebSocketsDependencyInjectionExtensions.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// 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;
@@ -7,8 +7,17 @@
 
 namespace Microsoft.AspNetCore.WebSockets
 {
+    /// <summary>
+    /// Extension method for <see cref="IServiceCollection"/> to add WebSockets configuration.
+    /// </summary>
     public static class WebSocketsDependencyInjectionExtensions
     {
+        /// <summary>
+        /// Extension method for <see cref="IServiceCollection"/> to add WebSockets configuration.
+        /// </summary>
+        /// <param name="services">The service collection to add WebSockets specific configuration to.</param>
+        /// <param name="configure">The configuration callback to setup <see cref="WebSocketOptions"/>.</param>
+        /// <returns></returns>
         public static IServiceCollection AddWebSockets(this IServiceCollection services, Action<WebSocketOptions> configure)
         {
             return services.Configure(configure);