[修改] WebSocket.Server 模块增加 XML 文档注释，优化子协议处理器、压缩扩展工厂和 WebSocket 主机构建器

Author: AlianBlank

src/GameFrameX.SuperSocket.WebSocket.Server/CommandSubProtocolHandler.cs

@@ -5,10 +5,21 @@
 
 namespace GameFrameX.SuperSocket.WebSocket.Server;
 
-internal sealed class CommandSubProtocolHandler<TPackageInfo> : SubProtocolHandlerBase
+/// <summary>
+/// Handles WebSocket sub-protocol commands.
+/// </summary>
+/// <typeparam name="TPackageInfo">The type of the package information.</typeparam>
+sealed class CommandSubProtocolHandler<TPackageInfo> : SubProtocolHandlerBase
 {
-    private readonly IPackageHandler<WebSocketPackage> _commandMiddleware;
+    private IPackageHandler<WebSocketPackage> _commandMiddleware;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CommandSubProtocolHandler{TPackageInfo}"/> class.
+    /// </summary>
+    /// <param name="name">The name of the sub-protocol.</param>
+    /// <param name="serviceProvider">The service provider.</param>
+    /// <param name="commandOptions">The command options.</param>
+    /// <param name="mapper">The package mapper.</param>
     public CommandSubProtocolHandler(string name, IServiceProvider serviceProvider, IOptions<CommandOptions> commandOptions, IPackageMapper<WebSocketPackage, TPackageInfo> mapper)
         : base(name)
     {
@@ -17,6 +28,13 @@ public CommandSubProtocolHandler(string name, IServiceProvider serviceProvider,
         _commandMiddleware = Activator.CreateInstance(commandMiddlewareType, serviceProvider, commandOptions, mapper) as IPackageHandler<WebSocketPackage>;
     }
 
+    /// <summary>
+    /// Handles a WebSocket package for the sub-protocol.
+    /// </summary>
+    /// <param name="session">The session associated with the package.</param>
+    /// <param name="package">The WebSocket package.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous handling operation.</returns>
     public override async ValueTask Handle(IAppSession session, WebSocketPackage package, CancellationToken cancellationToken)
     {
         await _commandMiddleware.Handle(session, package, cancellationToken);

src/GameFrameX.SuperSocket.WebSocket.Server/DelegateSubProtocolHandler.cs

@@ -2,22 +2,42 @@
 
 namespace GameFrameX.SuperSocket.WebSocket.Server;
 
-internal class DelegateSubProtocolHandler : SubProtocolHandlerBase
+/// <summary>
+/// Handles WebSocket sub-protocols using delegates.
+/// </summary>
+class DelegateSubProtocolHandler : SubProtocolHandlerBase
 {
-    private readonly Func<WebSocketSession, WebSocketPackage, CancellationToken, ValueTask> _packageHandler;
+    private Func<WebSocketSession, WebSocketPackage, CancellationToken, ValueTask> _packageHandler;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DelegateSubProtocolHandler"/> class with a delegate that does not use a cancellation token.
+    /// </summary>
+    /// <param name="name">The name of the sub-protocol.</param>
+    /// <param name="packageHandler">The delegate to handle the package.</param>
     public DelegateSubProtocolHandler(string name, Func<WebSocketSession, WebSocketPackage, ValueTask> packageHandler)
         : base(name)
     {
         _packageHandler = (session, package, cancellationToken) => packageHandler(session, package);
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DelegateSubProtocolHandler"/> class with a delegate that uses a cancellation token.
+    /// </summary>
+    /// <param name="name">The name of the sub-protocol.</param>
+    /// <param name="packageHandler">The delegate to handle the package.</param>
     public DelegateSubProtocolHandler(string name, Func<WebSocketSession, WebSocketPackage, CancellationToken, ValueTask> packageHandler)
         : base(name)
     {
         _packageHandler = packageHandler;
     }
 
+    /// <summary>
+    /// Handles a WebSocket package for the sub-protocol.
+    /// </summary>
+    /// <param name="session">The session associated with the package.</param>
+    /// <param name="package">The WebSocket package.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous handling operation.</returns>
     public override async ValueTask Handle(IAppSession session, WebSocketPackage package, CancellationToken cancellationToken)
     {
         await _packageHandler(session as WebSocketSession, package, cancellationToken);

src/GameFrameX.SuperSocket.WebSocket.Server/Extensions/Compression/WebSocketPerMessageCompressionExtensionFactory.cs

@@ -4,41 +4,53 @@
 
 namespace GameFrameX.SuperSocket.WebSocket.Server.Extensions.Compression;
 
-/// <summary>
-///     WebSocket Per-Message Compression Extension
-///     https://tools.ietf.org/html/rfc7692
-/// </summary>
-public class WebSocketPerMessageCompressionExtensionFactory : IWebSocketExtensionFactory
-{
-    private static readonly NameValueCollection _supportedOptions;
-
-    static WebSocketPerMessageCompressionExtensionFactory()
+    /// <summary>
+    /// WebSocket Per-Message Compression Extension
+    /// https://tools.ietf.org/html/rfc7692
+    /// </summary>
+    /// <summary>
+    /// Represents a factory for creating WebSocket Per-Message Compression extensions.
+    /// </summary>
+    /// <remarks>
+    /// Implements the WebSocket Per-Message Compression Extension as defined in RFC 7692.
+    /// </remarks>
+    public class WebSocketPerMessageCompressionExtensionFactory : IWebSocketExtensionFactory
     {
-        _supportedOptions = new NameValueCollection();
-        _supportedOptions.Add("client_no_context_takeover", string.Empty);
-    }
+        /// <summary>
+        /// Gets the name of the WebSocket extension.
+        /// </summary>
+        public string Name => WebSocketPerMessageCompressionExtension.PMCE;
 
-    public string Name
-    {
-        get { return WebSocketPerMessageCompressionExtension.PMCE; }
-    }
+        private static readonly NameValueCollection _supportedOptions;
 
-    public IWebSocketExtension Create(NameValueCollection options, out NameValueCollection supportedOptions)
-    {
-        supportedOptions = _supportedOptions;
+        static WebSocketPerMessageCompressionExtensionFactory()
+        {
+            _supportedOptions = new NameValueCollection();
+            _supportedOptions.Add("client_no_context_takeover", string.Empty);          
+        }
 
-        if (options != null && options.Count > 0)
+        /// <summary>
+        /// Creates a WebSocket Per-Message Compression extension based on the specified options.
+        /// </summary>
+        /// <param name="options">The options for the extension.</param>
+        /// <param name="supportedOptions">The supported options for the extension.</param>
+        /// <returns>The created WebSocket extension, or null if the options are invalid.</returns>
+        public IWebSocketExtension Create(NameValueCollection options, out NameValueCollection supportedOptions)
         {
-            foreach (var key in options.AllKeys)
+            supportedOptions = _supportedOptions;
+            
+            if (options != null && options.Count > 0)
             {
-                if (key.StartsWith("server_", StringComparison.OrdinalIgnoreCase))
+                foreach (var key in options.AllKeys)
                 {
-                    if (!string.IsNullOrEmpty(options.Get(key)))
-                        return null;
+                    if (key.StartsWith("server_", StringComparison.OrdinalIgnoreCase))
+                    {
+                        if (!string.IsNullOrEmpty(options.Get(key)))
+                            return null;
+                    }
                 }
             }
-        }
 
-        return new WebSocketPerMessageCompressionExtension();
+            return new WebSocketPerMessageCompressionExtension();
+        }
     }
-}

src/GameFrameX.SuperSocket.WebSocket.Server/Extensions/IWebSocketExtensionFactory.cs

@@ -3,18 +3,21 @@
 
 namespace GameFrameX.SuperSocket.WebSocket.Server.Extensions;
 
+/// <summary>
+/// Defines a factory for creating WebSocket extensions.
+/// </summary>
 public interface IWebSocketExtensionFactory
 {
     /// <summary>
-    /// The name of the WebSocket extension.
+    /// Gets the name of the WebSocket extension.
     /// </summary>
     string Name { get; }
 
     /// <summary>
-    /// Creates a new instance of the WebSocket extension.
+    /// Creates a WebSocket extension based on the specified options.
     /// </summary>
-    /// <param name="options">The options for the WebSocket extension.</param>
-    /// <param name="supportedOptions">The supported options for the WebSocket extension.</param>
+    /// <param name="options">The options for the extension.</param>
+    /// <param name="supportedOptions">The supported options for the extension.</param>
     /// <returns>The created WebSocket extension.</returns>
     IWebSocketExtension Create(NameValueCollection options, out NameValueCollection supportedOptions);
 }

src/GameFrameX.SuperSocket.WebSocket.Server/HandshakeOptions.cs

@@ -1,28 +1,30 @@
 namespace GameFrameX.SuperSocket.WebSocket.Server;
 
+/// <summary>
+/// Represents options for WebSocket handshake operations.
+/// </summary>
 public class HandshakeOptions
 {
     /// <summary>
-    ///     Handshake queue checking interval, in seconds
+    /// Gets or sets the handshake queue checking interval, in seconds.
     /// </summary>
-    /// <value>default: 60</value>
+    /// <value>Default: 60 seconds.</value>
     public int CheckingInterval { get; set; } = 60;
 
     /// <summary>
-    ///     Open handshake timeout, in seconds
+    /// Gets or sets the open handshake timeout, in seconds.
     /// </summary>
-    /// <value>default: 120</value>
+    /// <value>Default: 120 seconds.</value>
     public int OpenHandshakeTimeOut { get; set; } = 120;
 
     /// <summary>
-    ///     Close handshake timeout, in seconds
+    /// Gets or sets the close handshake timeout, in seconds.
     /// </summary>
-    /// <value>default: 120</value>
+    /// <value>Default: 120 seconds.</value>
     public int CloseHandshakeTimeOut { get; set; } = 120;
 
-
     /// <summary>
-    ///     Gets or sets the handshake validator.
+    /// Gets or sets the validator function for WebSocket handshakes.
     /// </summary>
     public Func<WebSocketSession, WebSocketPackage, ValueTask<bool>> HandshakeValidator { get; set; }
 }

src/GameFrameX.SuperSocket.WebSocket.Server/ISubProtocolHandler.cs

@@ -2,7 +2,13 @@
 
 namespace GameFrameX.SuperSocket.WebSocket.Server;
 
-internal interface ISubProtocolHandler : IPackageHandler<WebSocketPackage>
+/// <summary>
+/// Defines a handler for WebSocket sub-protocols.
+/// </summary>
+interface ISubProtocolHandler : IPackageHandler<WebSocketPackage>
 {
+    /// <summary>
+    /// Gets the name of the sub-protocol.
+    /// </summary>
     string Name { get; }
 }

src/GameFrameX.SuperSocket.WebSocket.Server/SubProtocolHandlerBase.cs

@@ -2,14 +2,31 @@
 
 namespace GameFrameX.SuperSocket.WebSocket.Server;
 
-internal abstract class SubProtocolHandlerBase : ISubProtocolHandler
+/// <summary>
+/// Serves as a base class for WebSocket sub-protocol handlers.
+/// </summary>
+abstract class SubProtocolHandlerBase : ISubProtocolHandler
 {
+    /// <summary>
+    /// Gets the name of the sub-protocol.
+    /// </summary>
+    public string Name { get; private set; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SubProtocolHandlerBase"/> class.
+    /// </summary>
+    /// <param name="name">The name of the sub-protocol.</param>
     public SubProtocolHandlerBase(string name)
     {
         Name = name;
     }
 
-    public string Name { get; }
-
+    /// <summary>
+    /// Handles a WebSocket package for the sub-protocol.
+    /// </summary>
+    /// <param name="session">The session associated with the package.</param>
+    /// <param name="package">The WebSocket package.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous handling operation.</returns>
     public abstract ValueTask Handle(IAppSession session, WebSocketPackage package, CancellationToken cancellationToken);
 }