From 295801ac505883721d8b792d3bfbd2bcf533c90f Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 1 May 2018 16:08:09 -0700 Subject: [PATCH] XML documentation (#2106) --- .../HttpConnection.cs | 57 +++++ .../HttpConnectionOptions.cs | 49 +++- .../HttpTransportType.cs | 18 ++ .../HttpTransports.cs | 8 +- .../ConnectionsAppBuilderExtensions.cs | 9 + ...onnectionsDependencyInjectionExtensions.cs | 8 + .../ConnectionsRouteBuilder.cs | 30 +++ .../HttpConnectionDispatcherOptions.cs | 24 ++ .../LongPollingOptions.cs | 6 + .../HubConnection.cs | 91 +++++++- .../HubConnectionBuilder.cs | 11 + .../HubConnectionBuilderExtensions.cs | 9 + .../HubConnectionExtensions.InvokeAsync.cs | 143 ++++++++++++ ...ConnectionExtensions.InvokeAsyncGeneric.cs | 191 +++++++++++++++ .../HubConnectionExtensions.SendAsync.cs | 146 ++++++++++++ ...nnectionExtensions.StreamAsChannelAsync.cs | 191 +++++++++++++++ .../HubConnectionExtensions.cs | 111 ++++++++- .../IConnectionFactory.cs | 19 +- .../IHubConnectionBuilder.cs | 9 + .../HttpConnectionFactory.cs | 12 +- .../HubConnectionBuilderHttpExtensions.cs | 64 +++++ .../HubException.cs | 24 ++ .../ISignalRBuilder.cs | 6 + .../Protocol/CloseMessage.cs | 13 ++ .../Protocol/HandshakeProtocol.cs | 28 +++ .../Protocol/HandshakeRequestMessage.cs | 15 ++ .../Protocol/HandshakeResponseMessage.cs | 13 ++ .../Protocol/HubInvocationMessage.cs | 13 ++ .../Protocol/HubMessage.cs | 3 + .../Protocol/HubMethodInvocationMessage.cs | 40 ++++ .../Protocol/HubProtocolConstants.cs | 30 +++ .../Protocol/HubProtocolExtensions.cs | 10 +- .../Protocol/IHubProtocol.cs | 34 +++ .../InvocationBindingFailureMessage.cs | 13 ++ .../ClientProxyExtensions.cs | 157 +++++++------ .../DefaultHubLifetimeManager.cs | 20 ++ .../DefaultUserIdProvider.cs | 5 + .../DynamicHub.cs | 6 + .../DynamicHubClients.cs | 73 ++++++ src/Microsoft.AspNetCore.SignalR.Core/Hub.cs | 26 +++ .../HubCallerContext.cs | 24 ++ .../HubConnectionContext.cs | 30 +++ .../HubConnectionHandler.cs | 15 ++ .../HubLifetimeManager.cs | 100 +++++++- .../HubMethodNameAttribute.cs | 10 + .../HubOptions.cs | 17 ++ .../HubOptions`T.cs | 4 + .../Hub`T.cs | 7 + .../IClientProxy.cs | 5 +- .../IGroupManager.cs | 18 ++ .../IHubActivator.cs | 13 ++ .../IHubCallerClients.cs | 3 + .../IHubCallerClients`T.cs | 14 ++ .../IHubClients.cs | 3 + .../IHubClientsExtensions.cs | 219 +++++++++++------- .../IHubClients`T.cs | 49 ++++ .../IHubContext.cs | 9 + .../IHubContext`T.cs | 9 + .../IHubProtocolResolver.cs | 13 ++ .../ISignalRServerBuilder.cs | 3 + .../IUserIdProvider.cs | 9 + .../Internal/DefaultHubCallerContext.cs | 10 + .../SerializedHubMessage.cs | 17 +- .../SerializedMessage.cs | 15 ++ .../SignalRConnectionBuilderExtensions.cs | 9 + .../SignalRDependencyInjectionExtensions.cs | 9 + .../JsonHubProtocolOptions.cs | 6 + ...onProtocolDependencyInjectionExtensions.cs | 3 + .../Protocol/JsonHubProtocol.cs | 21 +- ...ckProtocolDependencyInjectionExtensions.cs | 3 + .../Protocol/MessagePackHubProtocol.cs | 17 ++ .../RedisDependencyInjectionExtensions.cs | 27 +++ .../RedisOptions.cs | 9 + .../GetHttpContextExtensions.cs | 13 ++ .../HubRouteBuilder.cs | 18 ++ .../SignalRAppBuilderExtensions.cs | 9 + .../SignalRDependencyInjectionExtensions.cs | 21 ++ 77 files changed, 2338 insertions(+), 178 deletions(-) diff --git a/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnection.cs b/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnection.cs index a641f8475b..24709e4860 100644 --- a/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnection.cs +++ b/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnection.cs @@ -18,6 +18,9 @@ using Microsoft.Extensions.Logging.Abstractions; namespace Microsoft.AspNetCore.Http.Connections.Client { + /// + /// Used to make a connection to an ASP.NET Core ConnectionHandler using an HTTP-based transport. + /// public partial class HttpConnection : ConnectionContext, IConnectionInherentKeepAliveFeature { // Not configurable on purpose, high enough that if we reach here, it's likely @@ -47,6 +50,7 @@ namespace Microsoft.AspNetCore.Http.Connections.Client private readonly ILoggerFactory _loggerFactory; private Func> _accessTokenProvider; + /// public override IDuplexPipe Transport { get @@ -61,21 +65,42 @@ namespace Microsoft.AspNetCore.Http.Connections.Client set => throw new NotSupportedException("The transport pipe isn't settable."); } + /// public override IFeatureCollection Features { get; } = new FeatureCollection(); + + /// public override string ConnectionId { get; set; } + + /// public override IDictionary Items { get; set; } = new ConnectionItems(); + /// bool IConnectionInherentKeepAliveFeature.HasInherentKeepAlive => _hasInherentKeepAlive; + /// + /// Initializes a new instance of the class. + /// + /// The URL to connect to. public HttpConnection(Uri url) : this(url, HttpTransports.All) { } + /// + /// Initializes a new instance of the class. + /// + /// The URL to connect to. + /// A bitmask comprised of one or more that specify what transports the client should use. public HttpConnection(Uri url, HttpTransportType transports) : this(url, transports, loggerFactory: null) { } + /// + /// Initializes a new instance of the class. + /// + /// The URL to connect to. + /// A bitmask comprised of one or more that specify what transports the client should use. + /// The logger factory. public HttpConnection(Uri url, HttpTransportType transports, ILoggerFactory loggerFactory) : this(CreateHttpOptions(url, transports), loggerFactory) { @@ -90,6 +115,11 @@ namespace Microsoft.AspNetCore.Http.Connections.Client return new HttpConnectionOptions { Url = url, Transports = transports }; } + /// + /// Initializes a new instance of the class. + /// + /// The connection options to use. + /// The logger factory. public HttpConnection(HttpConnectionOptions httpConnectionOptions, ILoggerFactory loggerFactory) { if (httpConnectionOptions.Url == null) @@ -121,11 +151,30 @@ namespace Microsoft.AspNetCore.Http.Connections.Client _transportFactory = transportFactory; } + /// + /// Starts the connection. + /// + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous start. + /// + /// A connection cannot be restarted after it has stopped. To restart a connection + /// a new instance should be created using the same options. + /// public async Task StartAsync(CancellationToken cancellationToken = default) { await StartAsync(TransferFormat.Binary, cancellationToken); } + /// + /// Starts the connection using the specified transfer format. + /// + /// The transfer format the connection should use. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous start. + /// + /// A connection cannot be restarted after it has stopped. To restart a connection + /// a new instance should be created using the same options. + /// public async Task StartAsync(TransferFormat transferFormat, CancellationToken cancellationToken = default) { await StartAsyncCore(transferFormat).ForceAsync(); @@ -165,6 +214,14 @@ namespace Microsoft.AspNetCore.Http.Connections.Client } } + /// + /// Disposes the connection. + /// + /// A that represents the asynchronous dispose. + /// + /// A connection cannot be restarted after it has stopped. To restart a connection + /// a new instance should be created using the same options. + /// public async Task DisposeAsync() => await DisposeAsyncCore().ForceAsync(); private async Task DisposeAsyncCore() diff --git a/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnectionOptions.cs b/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnectionOptions.cs index 5e30dd4594..197e3681a9 100644 --- a/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnectionOptions.cs +++ b/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnectionOptions.cs @@ -11,12 +11,18 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Http.Connections.Client { + /// + /// Options used to configure a instance. + /// public class HttpConnectionOptions { private IDictionary _headers; private X509CertificateCollection _clientCertificates; private CookieContainer _cookies; + /// + /// Initializes a new instance of the class. + /// public HttpConnectionOptions() { _headers = new Dictionary(); @@ -28,37 +34,78 @@ namespace Microsoft.AspNetCore.Http.Connections.Client /// /// Gets or sets a delegate for wrapping or replacing the - /// that will make HTTP requests the server. + /// that will make HTTP requests. /// public Func HttpMessageHandlerFactory { get; set; } + /// + /// Gets or sets a collection of headers that will be sent with HTTP requests. + /// public IDictionary Headers { get => _headers; set => _headers = value ?? throw new ArgumentNullException(nameof(value)); } + /// + /// Gets or sets a collection of client certificates that will be sent with HTTP requests. + /// public X509CertificateCollection ClientCertificates { get => _clientCertificates; set => _clientCertificates = value ?? throw new ArgumentNullException(nameof(value)); } + /// + /// Gets or sets a collection of cookies that will be sent with HTTP requests. + /// public CookieContainer Cookies { get => _cookies; set => _cookies = value ?? throw new ArgumentNullException(nameof(value)); } + /// + /// Gets or sets the URL used to send HTTP requests. + /// public Uri Url { get; set; } + + /// + /// Gets or sets a bitmask comprised of one or more that specify what transports the client should use to send HTTP requests. + /// public HttpTransportType Transports { get; set; } + /// + /// Gets or sets a value indicating whether negotiation is skipped when connecting to the server. + /// + /// + /// Negotiation can only be skipped when using the transport. + /// public bool SkipNegotiation { get; set; } + /// + /// Gets or sets an access token provider that will be called to return a token for each HTTP request. + /// public Func> AccessTokenProvider { get; set; } + + /// + /// Gets or sets a close timeout. + /// public TimeSpan CloseTimeout { get; set; } = TimeSpan.FromSeconds(5); + + /// + /// Gets or sets the credentials used when making HTTP requests. + /// public ICredentials Credentials { get; set; } + + /// + /// Gets or sets the proxy used when making HTTP requests. + /// public IWebProxy Proxy { get; set; } + + /// + /// Gets or sets a value indicating whether default credentials are used when making HTTP requests. + /// public bool? UseDefaultCredentials { get; set; } /// diff --git a/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransportType.cs b/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransportType.cs index 054cc66b2e..85b88d80c4 100644 --- a/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransportType.cs +++ b/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransportType.cs @@ -5,12 +5,30 @@ using System; namespace Microsoft.AspNetCore.Http.Connections { + /// + /// Specifies transports that the client can use to send HTTP requests. + /// + /// + /// This enumeration has a attribute that allows a bitwise combination of its member values. + /// [Flags] public enum HttpTransportType { + /// + /// Specifies that no transport is used. + /// None = 0, + /// + /// Specifies that the web sockets transport is used. + /// WebSockets = 1, + /// + /// Specifies that the server sent events transport is used. + /// ServerSentEvents = 2, + /// + /// Specifies that the long polling transport is used. + /// LongPolling = 4, } } diff --git a/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransports.cs b/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransports.cs index 5743ea324d..de2ce47683 100644 --- a/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransports.cs +++ b/src/Microsoft.AspNetCore.Http.Connections.Common/HttpTransports.cs @@ -3,10 +3,14 @@ namespace Microsoft.AspNetCore.Http.Connections { + /// + /// Constants related to HTTP transports. + /// public static class HttpTransports { - // Note that this is static readonly instead of const so it is not baked into a DLL when referenced - // Updating package without recompiling will automatically pick up new transports added here + /// + /// A bitmask comprised of all available values. + /// public static readonly HttpTransportType All = HttpTransportType.WebSockets | HttpTransportType.ServerSentEvents | HttpTransportType.LongPolling; } } diff --git a/src/Microsoft.AspNetCore.Http.Connections/ConnectionsAppBuilderExtensions.cs b/src/Microsoft.AspNetCore.Http.Connections/ConnectionsAppBuilderExtensions.cs index a2219f0649..a663b31d6b 100644 --- a/src/Microsoft.AspNetCore.Http.Connections/ConnectionsAppBuilderExtensions.cs +++ b/src/Microsoft.AspNetCore.Http.Connections/ConnectionsAppBuilderExtensions.cs @@ -9,8 +9,17 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Builder { + /// + /// Extension methods for . + /// public static class ConnectionsAppBuilderExtensions { + /// + /// Adds support for ASP.NET Core Connection Handlers to the request execution pipeline. + /// + /// The . + /// A callback to configure connection routes. + /// The same instance of the for chaining. public static IApplicationBuilder UseConnections(this IApplicationBuilder app, Action configure) { if (configure == null) diff --git a/src/Microsoft.AspNetCore.Http.Connections/ConnectionsDependencyInjectionExtensions.cs b/src/Microsoft.AspNetCore.Http.Connections/ConnectionsDependencyInjectionExtensions.cs index bf7b7b8996..c77bcda43f 100644 --- a/src/Microsoft.AspNetCore.Http.Connections/ConnectionsDependencyInjectionExtensions.cs +++ b/src/Microsoft.AspNetCore.Http.Connections/ConnectionsDependencyInjectionExtensions.cs @@ -6,8 +6,16 @@ using Microsoft.Extensions.DependencyInjection.Extensions; namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods for . + /// public static class ConnectionsDependencyInjectionExtensions { + /// + /// Adds required services for ASP.NET Core Connection Handlers to the specified . + /// + /// The to add services to. + /// The same instance of the for chaining. public static IServiceCollection AddConnections(this IServiceCollection services) { services.AddRouting(); diff --git a/src/Microsoft.AspNetCore.Http.Connections/ConnectionsRouteBuilder.cs b/src/Microsoft.AspNetCore.Http.Connections/ConnectionsRouteBuilder.cs index 903062bef8..da7ca1b637 100644 --- a/src/Microsoft.AspNetCore.Http.Connections/ConnectionsRouteBuilder.cs +++ b/src/Microsoft.AspNetCore.Http.Connections/ConnectionsRouteBuilder.cs @@ -10,20 +10,39 @@ using Microsoft.AspNetCore.Routing; namespace Microsoft.AspNetCore.Http.Connections { + /// + /// Maps routes to ASP.NET Core Connection Handlers. + /// public class ConnectionsRouteBuilder { private readonly HttpConnectionDispatcher _dispatcher; private readonly RouteBuilder _routes; + /// + /// Initializes a new instance of the class. + /// + /// The underlying . + /// The dispatcher. public ConnectionsRouteBuilder(RouteBuilder routes, HttpConnectionDispatcher dispatcher) { _routes = routes; _dispatcher = dispatcher; } + /// + /// Maps incoming requests with the specified path to the provided connection pipeline. + /// + /// The request path. + /// A callback to configure the connection. public void MapConnections(PathString path, Action configure) => MapConnections(path, new HttpConnectionDispatcherOptions(), configure); + /// + /// Maps incoming requests with the specified path to the provided connection pipeline. + /// + /// The request path. + /// Options used to configure the connection. + /// A callback to configure the connection. public void MapConnections(PathString path, HttpConnectionDispatcherOptions options, Action configure) { var connectionBuilder = new ConnectionBuilder(_routes.ServiceProvider); @@ -33,11 +52,22 @@ namespace Microsoft.AspNetCore.Http.Connections _routes.MapRoute(path + "/negotiate", c => _dispatcher.ExecuteNegotiateAsync(c, options)); } + /// + /// Maps incoming requests with the specified path to the provided connection pipeline. + /// + /// The type. + /// The request path. public void MapConnectionHandler(PathString path) where TConnectionHandler : ConnectionHandler { MapConnectionHandler(path, configureOptions: null); } + /// + /// Maps incoming requests with the specified path to the provided connection pipeline. + /// + /// The type. + /// The request path. + /// A callback to configure dispatcher options. public void MapConnectionHandler(PathString path, Action configureOptions) where TConnectionHandler : ConnectionHandler { var authorizeAttributes = typeof(TConnectionHandler).GetCustomAttributes(inherit: true); diff --git a/src/Microsoft.AspNetCore.Http.Connections/HttpConnectionDispatcherOptions.cs b/src/Microsoft.AspNetCore.Http.Connections/HttpConnectionDispatcherOptions.cs index 91c4d5da5b..3acc25f91d 100644 --- a/src/Microsoft.AspNetCore.Http.Connections/HttpConnectionDispatcherOptions.cs +++ b/src/Microsoft.AspNetCore.Http.Connections/HttpConnectionDispatcherOptions.cs @@ -6,12 +6,18 @@ using Microsoft.AspNetCore.Authorization; namespace Microsoft.AspNetCore.Http.Connections { + /// + /// Options used to configure the HTTP connection dispatcher. + /// public class HttpConnectionDispatcherOptions { // Selected because this is the default value of PipeWriter.PauseWriterThreshold. // There maybe the opportunity for performance gains by tuning this default. private const int DefaultPipeBufferSize = 32768; + /// + /// Initializes a new instance of the class. + /// public HttpConnectionDispatcherOptions() { AuthorizationData = new List(); @@ -22,16 +28,34 @@ namespace Microsoft.AspNetCore.Http.Connections ApplicationMaxBufferSize = DefaultPipeBufferSize; } + /// + /// Gets a collection of used during HTTP connection pipeline. + /// public IList AuthorizationData { get; } + /// + /// Gets or sets a bitmask comprised of one or more that specify what transports the server should use to receive HTTP requests. + /// public HttpTransportType Transports { get; set; } + /// + /// Gets the used by the web sockets transport. + /// public WebSocketOptions WebSockets { get; } + /// + /// Gets the used by the long polling transport. + /// public LongPollingOptions LongPolling { get; } + /// + /// Gets or sets the maximum buffer size of the transport writer. + /// public long TransportMaxBufferSize { get; set; } + /// + /// Gets or sets the maximum buffer size of the application writer. + /// public long ApplicationMaxBufferSize { get; set; } } } diff --git a/src/Microsoft.AspNetCore.Http.Connections/LongPollingOptions.cs b/src/Microsoft.AspNetCore.Http.Connections/LongPollingOptions.cs index 57dfbe2dcb..0ddc3ee12a 100644 --- a/src/Microsoft.AspNetCore.Http.Connections/LongPollingOptions.cs +++ b/src/Microsoft.AspNetCore.Http.Connections/LongPollingOptions.cs @@ -2,8 +2,14 @@ using System; namespace Microsoft.AspNetCore.Http.Connections { + /// + /// Options used to configure the long polling transport. + /// public class LongPollingOptions { + /// + /// Gets or sets the poll timeout. + /// public TimeSpan PollTimeout { get; set; } = TimeSpan.FromSeconds(90); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnection.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnection.cs index bc7016e8a6..fc8cc15de3 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnection.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnection.cs @@ -20,6 +20,14 @@ using Microsoft.Extensions.Logging.Abstractions; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// A connection used to invoke hub methods on a SignalR Server. + /// + /// + /// A should be created using . + /// Before hub methods can be invoked the connection must be started using . + /// Clean up a connection using or . + /// public partial class HubConnection { public static readonly TimeSpan DefaultServerTimeout = TimeSpan.FromSeconds(30); // Server ping rate is 15 sec, this is 2 times that. @@ -49,12 +57,28 @@ namespace Microsoft.AspNetCore.SignalR.Client public TimeSpan ServerTimeout { get; set; } = DefaultServerTimeout; public TimeSpan HandshakeTimeout { get; set; } = DefaultHandshakeTimeout; + /// + /// Initializes a new instance of the class. + /// + /// The used to create a connection each time is called. + /// The used by the connection. + /// An containing the services provided to this instance. + /// The logger factory. + /// + /// The used to initialize the connection will be disposed when the connection is disposed. + /// public HubConnection(IConnectionFactory connectionFactory, IHubProtocol protocol, IServiceProvider serviceProvider, ILoggerFactory loggerFactory) : this(connectionFactory, protocol, loggerFactory) { _serviceProvider = serviceProvider ?? throw new ArgumentNullException(nameof(serviceProvider)); } + /// + /// Initializes a new instance of the class. + /// + /// The used to create a connection each time is called. + /// The used by the connection. + /// The logger factory. public HubConnection(IConnectionFactory connectionFactory, IHubProtocol protocol, ILoggerFactory loggerFactory) { _connectionFactory = connectionFactory ?? throw new ArgumentNullException(nameof(connectionFactory)); @@ -64,12 +88,22 @@ namespace Microsoft.AspNetCore.SignalR.Client _logger = _loggerFactory.CreateLogger(); } + /// + /// Starts a connection to the server. + /// + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous start. public async Task StartAsync(CancellationToken cancellationToken = default) { CheckDisposed(); await StartAsyncCore(cancellationToken).ForceAsync(); } + /// + /// Stops a connection to the server. + /// + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous stop. public async Task StopAsync(CancellationToken cancellationToken = default) { CheckDisposed(); @@ -78,6 +112,10 @@ namespace Microsoft.AspNetCore.SignalR.Client // Current plan for IAsyncDisposable is that DisposeAsync will NOT take a CancellationToken // https://github.com/dotnet/csharplang/blob/195efa07806284d7b57550e7447dc8bd39c156bf/proposals/async-streams.md#iasyncdisposable + /// + /// Disposes the . + /// + /// A that represents the asynchronous dispose. public async Task DisposeAsync() { if (!_disposed) @@ -86,6 +124,18 @@ namespace Microsoft.AspNetCore.SignalR.Client } } + // If the registered callback blocks it can cause the client to stop receiving messages. If you need to block, get off the current thread first. + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The name of the hub method to define. + /// The parameters types expected by the hub method. + /// The handler that will be raised when the hub method is invoked. + /// A state object that will be passed to the handler. + /// A subscription that can be disposed to unsubscribe from the hub method. + /// + /// This is a low level method for registering a handler. Using an On extension method is recommended. + /// public IDisposable On(string methodName, Type[] parameterTypes, Func handler, object state) { Log.RegisteringHandler(_logger, methodName); @@ -107,14 +157,51 @@ namespace Microsoft.AspNetCore.SignalR.Client return new Subscription(invocationHandler, invocationList); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The name of the server method to invoke. + /// The return type of the server method. + /// The arguments used to invoke the server method. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// + /// + /// This is a low level method for invoking a streaming hub method on the server. Using an StreamAsChannelAsync extension method is recommended. + /// public async Task> StreamAsChannelCoreAsync(string methodName, Type returnType, object[] args, CancellationToken cancellationToken = default) => await StreamAsChannelCoreAsyncCore(methodName, returnType, args, cancellationToken).ForceAsync(); + /// + /// Invokes a hub method on the server using the specified method name, return type and arguments. + /// + /// The name of the server method to invoke. + /// The return type of the server method. + /// The arguments used to invoke the server method. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns an for the hub method return value. + /// + /// + /// This is a low level method for invoking a hub method on the server. Using an InvokeAsync extension method is recommended. + /// public async Task InvokeCoreAsync(string methodName, Type returnType, object[] args, CancellationToken cancellationToken = default) => await InvokeCoreAsyncCore(methodName, returnType, args, cancellationToken).ForceAsync(); - // REVIEW: We don't generally use cancellation tokens when writing to a pipe because the asynchrony is only the result of backpressure. - // However, this would be the only "invocation" method _without_ a cancellation token... which is odd. + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The name of the server method to invoke. + /// The arguments used to invoke the server method. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. + /// + /// This is a low level method for invoking a hub method on the server. Using an SendAsync extension method is recommended. + /// public async Task SendCoreAsync(string methodName, object[] args, CancellationToken cancellationToken = default) => await SendCoreAsyncCore(methodName, args, cancellationToken).ForceAsync(); diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilder.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilder.cs index 6605dcb7d7..bb7f9071f6 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilder.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilder.cs @@ -7,12 +7,19 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// A builder for configuring instances. + /// public class HubConnectionBuilder : IHubConnectionBuilder { private bool _hubConnectionBuilt; + /// public IServiceCollection Services { get; } + /// + /// Initializes a new instance of the class. + /// public HubConnectionBuilder() { Services = new ServiceCollection(); @@ -21,6 +28,7 @@ namespace Microsoft.AspNetCore.SignalR.Client this.AddJsonProtocol(); } + /// public HubConnection Build() { // Build can only be used once @@ -44,6 +52,7 @@ namespace Microsoft.AspNetCore.SignalR.Client } // Prevents from being displayed in intellisense + /// [EditorBrowsable(EditorBrowsableState.Never)] public override int GetHashCode() { @@ -51,6 +60,7 @@ namespace Microsoft.AspNetCore.SignalR.Client } // Prevents from being displayed in intellisense + /// [EditorBrowsable(EditorBrowsableState.Never)] public override bool Equals(object obj) { @@ -58,6 +68,7 @@ namespace Microsoft.AspNetCore.SignalR.Client } // Prevents from being displayed in intellisense + /// [EditorBrowsable(EditorBrowsableState.Never)] public override string ToString() { diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilderExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilderExtensions.cs index 070ce4b958..132d236c15 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilderExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionBuilderExtensions.cs @@ -7,8 +7,17 @@ using Microsoft.Extensions.Logging; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// Extension methods for . + /// public static class HubConnectionBuilderExtensions { + /// + /// Adds a delegate for configuring the provided . This may be called multiple times. + /// + /// The to configure. + /// The delegate that configures the . + /// The same instance of the for chaining. public static IHubConnectionBuilder ConfigureLogging(this IHubConnectionBuilder hubConnectionBuilder, Action configureLogging) { hubConnectionBuilder.Services.AddLogging(configureLogging); diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsync.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsync.cs index 4bacff91fa..f8d2a0ddb7 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsync.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsync.cs @@ -7,63 +7,206 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// Extension methods for . + /// public partial class HubConnectionExtensions { + /// + /// Invokes a hub method on the server using the specified method name. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, Array.Empty(), cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and argument. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The tenth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, object arg10, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The arguments used to invoke the server method. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task InvokeCoreAsync(this HubConnection hubConnection, string methodName, object[] args, CancellationToken cancellationToken = default) { if (hubConnection == null) diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsyncGeneric.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsyncGeneric.cs index 5e6ea49e4e..5d5df546a6 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsyncGeneric.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.InvokeAsyncGeneric.cs @@ -7,63 +7,254 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// Extension methods for . + /// public static partial class HubConnectionExtensions { + /// + /// Invokes a hub method on the server using the specified method name. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, Array.Empty(), cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and argument. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The tenth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static Task InvokeAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, object arg10, CancellationToken cancellationToken = default) { return hubConnection.InvokeCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// + /// The return type of the server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The arguments used to invoke the server method. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the hub method return value. + /// public static async Task InvokeCoreAsync(this HubConnection hubConnection, string methodName, object[] args, CancellationToken cancellationToken = default) { if (hubConnection == null) diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.SendAsync.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.SendAsync.cs index c7f57cce17..ea41429607 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.SendAsync.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.SendAsync.cs @@ -7,58 +7,204 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// Extension methods for . + /// public static partial class HubConnectionExtensions { + /// + /// Invokes a hub method on the server using the specified method name. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, Array.Empty(), cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and argument. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9 }, cancellationToken); } + /// + /// Invokes a hub method on the server using the specified method name and arguments. + /// Does not wait for a response from the receiver. + /// + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The tenth argument. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous invoke. public static Task SendAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, object arg10, CancellationToken cancellationToken = default) { return hubConnection.SendCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 }, cancellationToken); diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.StreamAsChannelAsync.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.StreamAsChannelAsync.cs index b7032954fc..b4095d1dc0 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.StreamAsChannelAsync.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.StreamAsChannelAsync.cs @@ -8,63 +8,254 @@ using System.Threading.Channels; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// Extension methods for . + /// public static partial class HubConnectionExtensions { + /// + /// Invokes a streaming hub method on the server using the specified method name and return type. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, Array.Empty(), cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and argument. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eighth argument. + /// The ninth argument. + /// The tenth argument. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static Task> StreamAsChannelAsync(this HubConnection hubConnection, string methodName, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, object arg10, CancellationToken cancellationToken = default) { return hubConnection.StreamAsChannelCoreAsync(methodName, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 }, cancellationToken); } + /// + /// Invokes a streaming hub method on the server using the specified method name, return type and arguments. + /// + /// The return type of the streaming server method. + /// The hub connection. + /// The name of the server method to invoke. + /// The arguments used to invoke the server method. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous invoke. + /// The property returns a for the streamed hub method values. + /// public static async Task> StreamAsChannelCoreAsync(this HubConnection hubConnection, string methodName, object[] args, CancellationToken cancellationToken = default) { if (hubConnection == null) diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.cs index 71ca9ca27d..47e87549f4 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/HubConnectionExtensions.cs @@ -6,6 +6,9 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// Extension methods for . + /// public static partial class HubConnectionExtensions { private static IDisposable On(this HubConnection hubConnetion, string methodName, Type[] parameterTypes, Action handler) @@ -18,6 +21,13 @@ namespace Microsoft.AspNetCore.SignalR.Client }, handler); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -28,6 +38,14 @@ namespace Microsoft.AspNetCore.SignalR.Client return hubConnection.On(methodName, Type.EmptyTypes, args => handler()); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -40,6 +58,15 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0])); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The second argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -52,6 +79,16 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0], (T2)args[1])); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The second argument type. + /// The third argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -64,6 +101,17 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0], (T2)args[1], (T3)args[2])); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The second argument type. + /// The third argument type. + /// The fourth argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -76,6 +124,18 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0], (T2)args[1], (T3)args[2], (T4)args[3])); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The second argument type. + /// The third argument type. + /// The fourth argument type. + /// The fifth argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -88,6 +148,19 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0], (T2)args[1], (T3)args[2], (T4)args[3], (T5)args[4])); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The second argument type. + /// The third argument type. + /// The fourth argument type. + /// The fifth argument type. + /// The sixth argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -100,6 +173,20 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0], (T2)args[1], (T3)args[2], (T4)args[3], (T5)args[4], (T6)args[5])); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The second argument type. + /// The third argument type. + /// The fourth argument type. + /// The fifth argument type. + /// The sixth argument type. + /// The seventh argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -112,7 +199,21 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0], (T2)args[1], (T3)args[2], (T4)args[3], (T5)args[4], (T6)args[5], (T7)args[6])); } - + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The first argument type. + /// The second argument type. + /// The third argument type. + /// The fourth argument type. + /// The fifth argument type. + /// The sixth argument type. + /// The seventh argument type. + /// The eighth argument type. + /// The hub connection. + /// The name of the hub method to define. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Action handler) { if (hubConnection == null) @@ -125,6 +226,14 @@ namespace Microsoft.AspNetCore.SignalR.Client args => handler((T1)args[0], (T2)args[1], (T3)args[2], (T4)args[3], (T5)args[4], (T6)args[5], (T7)args[6], (T8)args[7])); } + /// + /// Registers a handler that will be invoked when the hub method with the specified method name is invoked. + /// + /// The hub connection. + /// The name of the hub method to define. + /// The parameters types expected by the hub method. + /// The handler that will be raised when the hub method is invoked. + /// A subscription that can be disposed to unsubscribe from the hub method. public static IDisposable On(this HubConnection hubConnection, string methodName, Type[] parameterTypes, Func handler) { return hubConnection.On(methodName, parameterTypes, (parameters, state) => diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/IConnectionFactory.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/IConnectionFactory.cs index 13f88f5369..6749b6140e 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/IConnectionFactory.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/IConnectionFactory.cs @@ -7,12 +7,29 @@ using Microsoft.AspNetCore.Connections; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// A factory abstraction for creating connections to a SignalR server. + /// public interface IConnectionFactory { + /// + /// Creates a new connection to a SignalR server using the specified . + /// + /// The transfer format the connection should use. + /// The token to monitor for cancellation requests. The default value is . + /// + /// A that represents the asynchronous connect. + /// The property returns a for the new connection. + /// Task ConnectAsync(TransferFormat transferFormat, CancellationToken cancellationToken = default); // Current plan for IAsyncDisposable is that DisposeAsync will NOT take a CancellationToken // https://github.com/dotnet/csharplang/blob/195efa07806284d7b57550e7447dc8bd39c156bf/proposals/async-streams.md#iasyncdisposable + /// + /// Disposes the specified . + /// + /// The connection to dispose. + /// A that represents the asynchronous dispose. Task DisposeAsync(ConnectionContext connection); } -} +} \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.SignalR.Client.Core/IHubConnectionBuilder.cs b/src/Microsoft.AspNetCore.SignalR.Client.Core/IHubConnectionBuilder.cs index efb3ed5bc9..eec2150305 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client.Core/IHubConnectionBuilder.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client.Core/IHubConnectionBuilder.cs @@ -3,8 +3,17 @@ namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// A builder abstraction for configuring instances. + /// public interface IHubConnectionBuilder : ISignalRBuilder { + /// + /// Creates a . + /// + /// + /// A built using the configured options. + /// HubConnection Build(); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Client/HttpConnectionFactory.cs b/src/Microsoft.AspNetCore.SignalR.Client/HttpConnectionFactory.cs index e669bef6b3..95a9dfe76e 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client/HttpConnectionFactory.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client/HttpConnectionFactory.cs @@ -11,11 +11,19 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// A factory for creating instances. + /// public class HttpConnectionFactory : IConnectionFactory { private readonly HttpConnectionOptions _httpConnectionOptions; private readonly ILoggerFactory _loggerFactory; + /// + /// Initializes a new instance of the class. + /// + /// The connection options. + /// The logger factory. public HttpConnectionFactory(IOptions options, ILoggerFactory loggerFactory) { if (options == null) @@ -32,6 +40,7 @@ namespace Microsoft.AspNetCore.SignalR.Client _loggerFactory = loggerFactory; } + /// public async Task ConnectAsync(TransferFormat transferFormat, CancellationToken cancellationToken = default) { var connection = new HttpConnection(_httpConnectionOptions, _loggerFactory); @@ -39,9 +48,10 @@ namespace Microsoft.AspNetCore.SignalR.Client return connection; } + /// public Task DisposeAsync(ConnectionContext connection) { return ((HttpConnection)connection).DisposeAsync(); } } -} +} \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.SignalR.Client/HubConnectionBuilderHttpExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Client/HubConnectionBuilderHttpExtensions.cs index 624b00f22c..979119e143 100644 --- a/src/Microsoft.AspNetCore.SignalR.Client/HubConnectionBuilderHttpExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Client/HubConnectionBuilderHttpExtensions.cs @@ -8,50 +8,109 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.SignalR.Client { + /// + /// Extension methods for . + /// public static class HubConnectionBuilderHttpExtensions { + /// + /// Configures the to use HTTP-based transports to connect to the specified URL. + /// + /// The to configure. + /// The URL the will use. + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, string url) { hubConnectionBuilder.WithUrlCore(new Uri(url), null, _ => { }); return hubConnectionBuilder; } + /// + /// Configures the to use HTTP-based transports to connect to the specified URL. + /// + /// The to configure. + /// The URL the will use. + /// The delegate that configures the . + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, string url, Action configureHttpConnection) { hubConnectionBuilder.WithUrlCore(new Uri(url), null, configureHttpConnection); return hubConnectionBuilder; } + /// + /// Configures the to use HTTP-based transports to connect to the specified URL and transports. + /// + /// The to configure. + /// The URL the will use. + /// A bitmask comprised of one or more that specify what transports the client should use. + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, string url, HttpTransportType transports) { hubConnectionBuilder.WithUrlCore(new Uri(url), transports, _ => { }); return hubConnectionBuilder; } + /// + /// Configures the to use HTTP-based transports to connect to the specified URL and transports. + /// + /// The to configure. + /// The URL the will use. + /// A bitmask comprised of one or more that specify what transports the client should use. + /// The delegate that configures the . + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, string url, HttpTransportType transports, Action configureHttpConnection) { hubConnectionBuilder.WithUrlCore(new Uri(url), transports, configureHttpConnection); return hubConnectionBuilder; } + /// + /// Configures the to use HTTP-based transports to connect to the specified URL. + /// + /// The to configure. + /// The URL the will use. + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, Uri url) { hubConnectionBuilder.WithUrlCore(url, null, _ => { }); return hubConnectionBuilder; } + /// + /// Configures the to use HTTP-based transports to connect to the specified URL. + /// + /// The to configure. + /// The URL the will use. + /// The delegate that configures the . + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, Uri url, Action configureHttpConnection) { hubConnectionBuilder.WithUrlCore(url, null, configureHttpConnection); return hubConnectionBuilder; } + /// + /// Configures the to use HTTP-based transports to connect to the specified URL and transports. + /// + /// The to configure. + /// The URL the will use. + /// A bitmask comprised of one or more that specify what transports the client should use. + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, Uri url, HttpTransportType transports) { hubConnectionBuilder.WithUrlCore(url, null, _ => { }); return hubConnectionBuilder; } + /// + /// Configures the to use HTTP-based transports to connect to the specified URL and transports. + /// + /// The to configure. + /// The URL the will use. + /// A bitmask comprised of one or more that specify what transports the client should use. + /// The delegate that configures the . + /// The same instance of the for chaining. public static IHubConnectionBuilder WithUrl(this IHubConnectionBuilder hubConnectionBuilder, Uri url, HttpTransportType transports, Action configureHttpConnection) { hubConnectionBuilder.WithUrlCore(url, transports, _ => { }); @@ -60,6 +119,11 @@ namespace Microsoft.AspNetCore.SignalR.Client private static IHubConnectionBuilder WithUrlCore(this IHubConnectionBuilder hubConnectionBuilder, Uri url, HttpTransportType? transports, Action configureHttpConnection) { + if (hubConnectionBuilder == null) + { + throw new ArgumentNullException(nameof(hubConnectionBuilder)); + } + hubConnectionBuilder.Services.Configure(o => { o.Url = url; diff --git a/src/Microsoft.AspNetCore.SignalR.Common/HubException.cs b/src/Microsoft.AspNetCore.SignalR.Common/HubException.cs index 62759e05a5..cb87c50c10 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/HubException.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/HubException.cs @@ -6,21 +6,45 @@ using System.Runtime.Serialization; namespace Microsoft.AspNetCore.SignalR { + /// + /// The exception thrown from a hub when an error occurs. + /// [Serializable] public class HubException : Exception { + /// + /// Initializes a new instance of the class. + /// public HubException() { } + /// + /// Initializes a new instance of the class + /// with a specified error message. + /// + /// The error message that explains the reason for the exception. public HubException(string message) : base(message) { } + /// + /// Initializes a new instance of the class + /// with a specified error message and a reference to the inner exception that is the cause of this exception. + /// + /// The error message that explains the reason for the exception. + /// The exception that is the cause of the current exception, or null if no inner exception is specified. public HubException(string message, Exception innerException) : base(message, innerException) { } + /// + /// Initializes a new instance of the class. + /// + /// The that holds the serialized object data about the exception being thrown. + /// The that contains contextual information about the source or destination. + /// The parameter is null. + /// The class name is null or is zero (0). public HubException(SerializationInfo info, StreamingContext context) : base(info, context) { } diff --git a/src/Microsoft.AspNetCore.SignalR.Common/ISignalRBuilder.cs b/src/Microsoft.AspNetCore.SignalR.Common/ISignalRBuilder.cs index bc16d08dec..48bfd38cec 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/ISignalRBuilder.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/ISignalRBuilder.cs @@ -9,8 +9,14 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.SignalR { + /// + /// A builder abstraction for configuring SignalR object instances. + /// public interface ISignalRBuilder { + /// + /// Gets the builder service collection. + /// IServiceCollection Services { get; } } } diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/CloseMessage.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/CloseMessage.cs index fc5e801441..604eeb8299 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/CloseMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/CloseMessage.cs @@ -6,12 +6,25 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// The message sent when closing a connection. + /// public class CloseMessage : HubMessage { + /// + /// An empty close message with no error. + /// public static readonly CloseMessage Empty = new CloseMessage(null); + /// + /// Gets the optional error message. + /// public string Error { get; } + /// + /// Initializes a new instance of the class with an optional error message. + /// + /// An optional error message. public CloseMessage(string error) { Error = error; diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeProtocol.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeProtocol.cs index 9e80ca0446..89e72f3ece 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeProtocol.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeProtocol.cs @@ -10,6 +10,9 @@ using Newtonsoft.Json; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// A helper class for working with SignalR handshakes. + /// public static class HandshakeProtocol { private const string ProtocolPropertyName = "protocol"; @@ -17,6 +20,9 @@ namespace Microsoft.AspNetCore.SignalR.Protocol private const string ErrorPropertyName = "error"; private const string TypePropertyName = "type"; + /// + /// The serialized representation of a success handshake. + /// public static ReadOnlyMemory SuccessHandshakeData; static HandshakeProtocol() @@ -33,6 +39,11 @@ namespace Microsoft.AspNetCore.SignalR.Protocol } } + /// + /// Writes the serialized representation of a to the specified writer. + /// + /// The message to write. + /// The output writer. public static void WriteRequestMessage(HandshakeRequestMessage requestMessage, IBufferWriter output) { var textWriter = Utf8BufferTextWriter.Get(output); @@ -57,6 +68,11 @@ namespace Microsoft.AspNetCore.SignalR.Protocol TextMessageFormatter.WriteRecordSeparator(output); } + /// + /// Writes the serialized representation of a to the specified writer. + /// + /// The message to write. + /// The output writer. public static void WriteResponseMessage(HandshakeResponseMessage responseMessage, IBufferWriter output) { var textWriter = Utf8BufferTextWriter.Get(output); @@ -83,6 +99,12 @@ namespace Microsoft.AspNetCore.SignalR.Protocol TextMessageFormatter.WriteRecordSeparator(output); } + /// + /// Creates a new from the specified serialized representation. + /// + /// The serialized representation of the message. + /// When this method returns, contains the parsed message. + /// A value that is true if the was successfully parsed; otherwise, false. public static bool TryParseResponseMessage(ref ReadOnlySequence buffer, out HandshakeResponseMessage responseMessage) { if (!TextMessageParser.TryParseMessage(ref buffer, out var payload)) @@ -142,6 +164,12 @@ namespace Microsoft.AspNetCore.SignalR.Protocol } } + /// + /// Creates a new from the specified serialized representation. + /// + /// The serialized representation of the message. + /// When this method returns, contains the parsed message. + /// A value that is true if the was successfully parsed; otherwise, false. public static bool TryParseRequestMessage(ref ReadOnlySequence buffer, out HandshakeRequestMessage requestMessage) { if (!TextMessageParser.TryParseMessage(ref buffer, out var payload)) diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeRequestMessage.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeRequestMessage.cs index f39ba57777..41c82b08fe 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeRequestMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeRequestMessage.cs @@ -3,15 +3,30 @@ namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// A handshake request message. + /// public class HandshakeRequestMessage : HubMessage { + /// + /// Initializes a new instance of the class. + /// + /// The requested protocol name. + /// The requested protocol version. public HandshakeRequestMessage(string protocol, int version) { Protocol = protocol; Version = version; } + /// + /// Gets the requested protocol name. + /// public string Protocol { get; } + + /// + /// Gets the requested protocol version. + /// public int Version { get; } } } diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeResponseMessage.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeResponseMessage.cs index ba164b54db..4288ea94e2 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeResponseMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HandshakeResponseMessage.cs @@ -3,12 +3,25 @@ namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// A handshake response message. + /// public class HandshakeResponseMessage : HubMessage { + /// + /// An empty response message with no error. + /// public static readonly HandshakeResponseMessage Empty = new HandshakeResponseMessage(null); + /// + /// Gets the optional error message. + /// public string Error { get; } + /// + /// Initializes a new instance of the class. + /// + /// An optional response error message. A null error message indicates a succesful handshake. public HandshakeResponseMessage(string error) { // Note that a response with an empty string for error in the JSON is considered an errored response diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubInvocationMessage.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubInvocationMessage.cs index 46ca956dd1..32e9f25d03 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubInvocationMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubInvocationMessage.cs @@ -5,12 +5,25 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// A base class for hub messages related to a specific invocation. + /// public abstract class HubInvocationMessage : HubMessage { + /// + /// Gets or sets a name/value collection of headers. + /// public IDictionary Headers { get; set; } + /// + /// Gets the invocation ID. + /// public string InvocationId { get; } + /// + /// Initializes a new instance of the class. + /// + /// The invocation ID. protected HubInvocationMessage(string invocationId) { InvocationId = invocationId; diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMessage.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMessage.cs index 96ec7c024c..dd1466a34e 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMessage.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// A base class for hub messages. + /// public abstract class HubMessage { } diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMethodInvocationMessage.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMethodInvocationMessage.cs index 272e446d0b..4b0b0ad079 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMethodInvocationMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubMethodInvocationMessage.cs @@ -6,12 +6,27 @@ using System.Linq; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// A base class for hub messages representing an invocation. + /// public abstract class HubMethodInvocationMessage : HubInvocationMessage { + /// + /// Gets the target method name. + /// public string Target { get; } + /// + /// Gets the target method arguments. + /// public object[] Arguments { get; } + /// + /// Initializes a new instance of the class. + /// + /// The invocation ID. + /// The target method name. + /// The target method arguments. protected HubMethodInvocationMessage(string invocationId, string target, object[] arguments) : base(invocationId) { @@ -25,18 +40,33 @@ namespace Microsoft.AspNetCore.SignalR.Protocol } } + /// + /// A hub message representing a non-streaming invocation. + /// public class InvocationMessage : HubMethodInvocationMessage { + /// + /// Initializes a new instance of the class. + /// + /// The target method name. + /// The target method arguments. public InvocationMessage(string target, object[] arguments) : this(null, target, arguments) { } + /// + /// Initializes a new instance of the class. + /// + /// The invocation ID. + /// The target method name. + /// The target method arguments. public InvocationMessage(string invocationId, string target, object[] arguments) : base(invocationId, target, arguments) { } + /// public override string ToString() { string args; @@ -52,8 +82,17 @@ namespace Microsoft.AspNetCore.SignalR.Protocol } } + /// + /// A hub message representing a streaming invocation. + /// public class StreamInvocationMessage : HubMethodInvocationMessage { + /// + /// Initializes a new instance of the class. + /// + /// The invocation ID. + /// The target method name. + /// The target method arguments. public StreamInvocationMessage(string invocationId, string target, object[] arguments) : base(invocationId, target, arguments) { @@ -63,6 +102,7 @@ namespace Microsoft.AspNetCore.SignalR.Protocol } } + /// public override string ToString() { string args; diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolConstants.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolConstants.cs index 44c6fb25f4..ce1e3cbfd5 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolConstants.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolConstants.cs @@ -3,14 +3,44 @@ namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// Constants related to the SignalR hub protocol. + /// public static class HubProtocolConstants { + /// + /// Represents the invocation message type. + /// public const int InvocationMessageType = 1; + + /// + /// Represents the stream item message type. + /// public const int StreamItemMessageType = 2; + + /// + /// Represents the completion message type. + /// public const int CompletionMessageType = 3; + + /// + /// Represents the stream invocation message type. + /// public const int StreamInvocationMessageType = 4; + + /// + /// Represents the cancel invocation message type. + /// public const int CancelInvocationMessageType = 5; + + /// + /// Represents the ping message type. + /// public const int PingMessageType = 6; + + /// + /// Represents the close message type. + /// public const int CloseMessageType = 7; } } diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolExtensions.cs index d94037db49..862bea3938 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/HubProtocolExtensions.cs @@ -5,9 +5,17 @@ using Microsoft.AspNetCore.Internal; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// Extension methods for . + /// public static class HubProtocolExtensions { - // Would work as default interface impl + /// + /// Converts the specified to its serialized representation. + /// + /// The hub protocol. + /// The message to convert to bytes. + /// The serialized representation of the specified message. public static byte[] GetMessageBytes(this IHubProtocol hubProtocol, HubMessage message) { var writer = MemoryBufferWriter.Get(); diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/IHubProtocol.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/IHubProtocol.cs index 9445928139..7aaedc65fa 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/IHubProtocol.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/IHubProtocol.cs @@ -7,20 +7,54 @@ using Microsoft.AspNetCore.Connections; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// A protocol abstraction for communicating with SignalR hubs. + /// public interface IHubProtocol { + /// + /// Gets the name of the protocol. The name is used by SignalR to resolve the protocol between the client and server. + /// string Name { get; } + /// + /// Gets the version of the protocol. + /// int Version { get; } + /// + /// Gets the transfer format of the protocol. + /// TransferFormat TransferFormat { get; } + /// + /// Creates a new from the specified serialized representation, and using the specified binder. + /// + /// The serialized representation of the message. + /// The binder used to parse the message. + /// When this method returns true, contains the parsed message. + /// A value that is true if the was successfully parsed; otherwise, false. bool TryParseMessage(ref ReadOnlySequence input, IInvocationBinder binder, out HubMessage message); + /// + /// Writes the specified to a writer. + /// + /// The message to write. + /// The output writer. void WriteMessage(HubMessage message, IBufferWriter output); + /// + /// Converts the specified to its serialized representation. + /// + /// The message to convert. + /// The serialized representation of the message. ReadOnlyMemory GetMessageBytes(HubMessage message); + /// + /// Gets a value indicating whether the protocol supports the specified version. + /// + /// The version. + /// A value indicating whether the protocol supports the specified version. bool IsVersionSupported(int version); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/InvocationBindingFailureMessage.cs b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/InvocationBindingFailureMessage.cs index 74c88ddc85..0b866f871e 100644 --- a/src/Microsoft.AspNetCore.SignalR.Common/Protocol/InvocationBindingFailureMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Common/Protocol/InvocationBindingFailureMessage.cs @@ -10,9 +10,22 @@ namespace Microsoft.AspNetCore.SignalR.Protocol /// public class InvocationBindingFailureMessage : HubInvocationMessage { + /// + /// Gets the exception thrown during binding. + /// public ExceptionDispatchInfo BindingFailure { get; } + + /// + /// Gets the target method name. + /// public string Target { get; } + /// + /// Initializes a new instance of the class. + /// + /// The invocation ID. + /// The target method name. + /// The exception thrown during binding. public InvocationBindingFailureMessage(string invocationId, string target, ExceptionDispatchInfo bindingFailure) : base(invocationId) { Target = target; diff --git a/src/Microsoft.AspNetCore.SignalR.Core/ClientProxyExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Core/ClientProxyExtensions.cs index 569dea75ea..2e21956e91 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/ClientProxyExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/ClientProxyExtensions.cs @@ -7,6 +7,9 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR { + /// + /// Extension methods for . + /// public static class ClientProxyExtensions { /// @@ -14,9 +17,9 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke + /// The name of the method to invoke. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, Array.Empty(), cancellationToken); @@ -27,10 +30,10 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument + /// The name of the method to invoke. + /// The first argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1 }, cancellationToken); @@ -41,11 +44,11 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2 }, cancellationToken); @@ -56,12 +59,12 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3 }, cancellationToken); @@ -72,13 +75,13 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument - /// The fourth argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, object arg4, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3, arg4 }, cancellationToken); @@ -89,14 +92,14 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument - /// The fourth argument - /// The fifth argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, object arg4, object arg5, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3, arg4, arg5 }, cancellationToken); @@ -107,15 +110,15 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument - /// The fourth argument - /// The fifth argument - /// The sixth argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3, arg4, arg5, arg6 }, cancellationToken); @@ -126,16 +129,16 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument - /// The fourth argument - /// The fifth argument - /// The sixth argument - /// The seventh argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7 }, cancellationToken); @@ -146,17 +149,17 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument - /// The fourth argument - /// The fifth argument - /// The sixth argument - /// The seventh argument - /// The eigth argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eigth argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 }, cancellationToken); @@ -167,18 +170,18 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument - /// The fourth argument - /// The fifth argument - /// The sixth argument - /// The seventh argument - /// The eigth argument - /// The ninth argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eigth argument. + /// The ninth argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9 }, cancellationToken); @@ -189,19 +192,19 @@ namespace Microsoft.AspNetCore.SignalR /// Does not wait for a response from the receiver. /// /// The - /// name of the method to invoke - /// The first argument - /// The second argument - /// The third argument - /// The fourth argument - /// The fifth argument - /// The sixth argument - /// The seventh argument - /// The eigth argument - /// The ninth argument - /// The tenth argument + /// The name of the method to invoke. + /// The first argument. + /// The second argument. + /// The third argument. + /// The fourth argument. + /// The fifth argument. + /// The sixth argument. + /// The seventh argument. + /// The eigth argument. + /// The ninth argument. + /// The tenth argument. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. public static Task SendAsync(this IClientProxy clientProxy, string method, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9, object arg10, CancellationToken cancellationToken = default) { return clientProxy.SendCoreAsync(method, new[] { arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 }, cancellationToken); diff --git a/src/Microsoft.AspNetCore.SignalR.Core/DefaultHubLifetimeManager.cs b/src/Microsoft.AspNetCore.SignalR.Core/DefaultHubLifetimeManager.cs index fb4baacb14..3c835ab933 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/DefaultHubLifetimeManager.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/DefaultHubLifetimeManager.cs @@ -13,17 +13,25 @@ using Microsoft.Extensions.Logging; namespace Microsoft.AspNetCore.SignalR { + /// + /// A default in-memory lifetime manager abstraction for instances. + /// public class DefaultHubLifetimeManager : HubLifetimeManager where THub : Hub { private readonly HubConnectionStore _connections = new HubConnectionStore(); private readonly HubGroupList _groups = new HubGroupList(); private readonly ILogger _logger; + /// + /// Initializes a new instance of the class. + /// + /// The logger. public DefaultHubLifetimeManager(ILogger> logger) { _logger = logger; } + /// public override Task AddToGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default) { if (connectionId == null) @@ -47,6 +55,7 @@ namespace Microsoft.AspNetCore.SignalR return Task.CompletedTask; } + /// public override Task RemoveFromGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default) { if (connectionId == null) @@ -70,6 +79,7 @@ namespace Microsoft.AspNetCore.SignalR return Task.CompletedTask; } + /// public override Task SendAllAsync(string methodName, object[] args, CancellationToken cancellationToken = default) { return SendToAllConnections(methodName, args, null); @@ -146,6 +156,7 @@ namespace Microsoft.AspNetCore.SignalR } } + /// public override Task SendConnectionAsync(string connectionId, string methodName, object[] args, CancellationToken cancellationToken = default) { if (connectionId == null) @@ -167,6 +178,7 @@ namespace Microsoft.AspNetCore.SignalR return connection.WriteAsync(message).AsTask(); } + /// public override Task SendGroupAsync(string groupName, string methodName, object[] args, CancellationToken cancellationToken = default) { if (groupName == null) @@ -192,6 +204,7 @@ namespace Microsoft.AspNetCore.SignalR return Task.CompletedTask; } + /// public override Task SendGroupsAsync(IReadOnlyList groupNames, string methodName, object[] args, CancellationToken cancellationToken = default) { // Each task represents the list of tasks for each of the writes within a group @@ -220,6 +233,7 @@ namespace Microsoft.AspNetCore.SignalR return Task.CompletedTask; } + /// public override Task SendGroupExceptAsync(string groupName, string methodName, object[] args, IReadOnlyList excludedConnectionIds, CancellationToken cancellationToken = default) { if (groupName == null) @@ -254,17 +268,20 @@ namespace Microsoft.AspNetCore.SignalR return new InvocationMessage(methodName, args); } + /// public override Task SendUserAsync(string userId, string methodName, object[] args, CancellationToken cancellationToken = default) { return SendToAllConnections(methodName, args, connection => string.Equals(connection.UserIdentifier, userId, StringComparison.Ordinal)); } + /// public override Task OnConnectedAsync(HubConnectionContext connection) { _connections.Add(connection); return Task.CompletedTask; } + /// public override Task OnDisconnectedAsync(HubConnectionContext connection) { _connections.Remove(connection); @@ -272,16 +289,19 @@ namespace Microsoft.AspNetCore.SignalR return Task.CompletedTask; } + /// public override Task SendAllExceptAsync(string methodName, object[] args, IReadOnlyList excludedConnectionIds, CancellationToken cancellationToken = default) { return SendToAllConnections(methodName, args, connection => !excludedConnectionIds.Contains(connection.ConnectionId)); } + /// public override Task SendConnectionsAsync(IReadOnlyList connectionIds, string methodName, object[] args, CancellationToken cancellationToken = default) { return SendToAllConnections(methodName, args, connection => connectionIds.Contains(connection.ConnectionId)); } + /// public override Task SendUsersAsync(IReadOnlyList userIds, string methodName, object[] args, CancellationToken cancellationToken = default) { return SendToAllConnections(methodName, args, connection => userIds.Contains(connection.UserIdentifier)); diff --git a/src/Microsoft.AspNetCore.SignalR.Core/DefaultUserIdProvider.cs b/src/Microsoft.AspNetCore.SignalR.Core/DefaultUserIdProvider.cs index 194f527b02..809114eb68 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/DefaultUserIdProvider.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/DefaultUserIdProvider.cs @@ -5,8 +5,13 @@ using System.Security.Claims; namespace Microsoft.AspNetCore.SignalR { + /// + /// The default provider for getting the user ID from a connection. + /// This provider gets the user ID from the connection's name identifier claim. + /// public class DefaultUserIdProvider : IUserIdProvider { + /// public virtual string GetUserId(HubConnectionContext connection) { return connection.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value; diff --git a/src/Microsoft.AspNetCore.SignalR.Core/DynamicHub.cs b/src/Microsoft.AspNetCore.SignalR.Core/DynamicHub.cs index f37460cacd..2941b32ee5 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/DynamicHub.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/DynamicHub.cs @@ -3,10 +3,16 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// A base class for SignalR hubs that use dynamic to represent client invocations. + /// public abstract class DynamicHub : Hub { private DynamicHubClients _clients; + /// + /// Gets or sets an object that can be used to invoke methods on the clients connected to this hub. + /// public new DynamicHubClients Clients { get diff --git a/src/Microsoft.AspNetCore.SignalR.Core/DynamicHubClients.cs b/src/Microsoft.AspNetCore.SignalR.Core/DynamicHubClients.cs index 2f49cc9d2d..8d3b43ddef 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/DynamicHubClients.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/DynamicHubClients.cs @@ -6,26 +6,99 @@ using Microsoft.AspNetCore.SignalR.Internal; namespace Microsoft.AspNetCore.SignalR { + /// + /// A class that provides dynamic access to connections, including the one that sent the current invocation. + /// public class DynamicHubClients { private readonly IHubCallerClients _clients; + /// + /// Initializes a new instance of the class. + /// + /// A wrapped that is used to invoke methods. public DynamicHubClients(IHubCallerClients clients) { _clients = clients; } + /// + /// Gets an object that can be used to invoke methods on all clients connected to the hub. + /// + /// An object that can be used to invoke methods on the specified user. public dynamic All => new DynamicClientProxy(_clients.All); + + /// + /// Gets an object that can be used to invoke methods on all clients connected to the hub excluding the specified connections. + /// + /// A collection of connection IDs to exclude. + /// An object that can be used to invoke methods on the specified user. public dynamic AllExcept(IReadOnlyList excludedConnectionIds) => new DynamicClientProxy(_clients.AllExcept(excludedConnectionIds)); + + /// + /// Gets an object that can be used to invoke methods on the connection which triggered the current invocation. + /// public dynamic Caller => new DynamicClientProxy(_clients.Caller); + + /// + /// Gets an object that can be used to invoke methods on the specified connection. + /// + /// The connection ID. + /// An object that can be used to invoke methods. public dynamic Client(string connectionId) => new DynamicClientProxy(_clients.Client(connectionId)); + + /// + /// Gets an object that can be used to invoke methods on the specified connections. + /// + /// The connection IDs. + /// An object that can be used to invoke methods. public dynamic Clients(IReadOnlyList connectionIds) => new DynamicClientProxy(_clients.Clients(connectionIds)); + + /// + /// Gets an object that can be used to invoke methods on all connections in the specified group. + /// + /// The group name. + /// An object that can be used to invoke methods. public dynamic Group(string groupName) => new DynamicClientProxy(_clients.Group(groupName)); + + /// + /// Gets an object that can be used to invoke methods on all connections in all of the specified groups. + /// + /// The group names. + /// An object that can be used to invoke methods on the specified user. public dynamic Groups(IReadOnlyList groupNames) => new DynamicClientProxy(_clients.Groups(groupNames)); + + /// + /// Gets an object that can be used to invoke methods on all connections in the specified group excluding the specified connections. + /// + /// The group name. + /// A collection of connection IDs to exclude. + /// An object that can be used to invoke methods. public dynamic GroupExcept(string groupName, IReadOnlyList excludedConnectionIds) => new DynamicClientProxy(_clients.GroupExcept(groupName, excludedConnectionIds)); + + /// + /// Gets an object that can be used to invoke methods on connections in a group other than the caller. + /// + /// An object that can be used to invoke methods. public dynamic OthersInGroup(string groupName) => new DynamicClientProxy(_clients.OthersInGroup(groupName)); + + /// + /// Gets an object that can be used to invoke methods on connections other than the caller. + /// public dynamic Others => new DynamicClientProxy(_clients.Others); + + /// + /// Gets an object that can be used to invoke methods on all connections associated with the specified user. + /// + /// The user ID. + /// An object that can be used to invoke methods. public dynamic User(string userId) => new DynamicClientProxy(_clients.User(userId)); + + /// + /// Gets an object that can be used to invoke methods on all connections associated with all of the specified users. + /// + /// The user IDs. + /// An object that can be used to invoke methods. public dynamic Users(IReadOnlyList users) => new DynamicClientProxy(_clients.Users(users)); } } \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.SignalR.Core/Hub.cs b/src/Microsoft.AspNetCore.SignalR.Core/Hub.cs index 63a36fe92a..544c6bcee1 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/Hub.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/Hub.cs @@ -6,6 +6,9 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR { + /// + /// A base class for a SignalR hub. + /// public abstract class Hub : IDisposable { private bool _disposed; @@ -13,6 +16,9 @@ namespace Microsoft.AspNetCore.SignalR private HubCallerContext _context; private IGroupManager _groups; + /// + /// Gets or sets an object that can be used to invoke methods on the clients connected to this hub. + /// public IHubCallerClients Clients { get @@ -27,6 +33,9 @@ namespace Microsoft.AspNetCore.SignalR } } + /// + /// Gets or sets the hub caller context. + /// public HubCallerContext Context { get @@ -41,6 +50,9 @@ namespace Microsoft.AspNetCore.SignalR } } + /// + /// Gets or sets the group manager. + /// public IGroupManager Groups { get @@ -55,20 +67,34 @@ namespace Microsoft.AspNetCore.SignalR } } + /// + /// Called when a new connection is established with the hub. + /// + /// A that represents the asynchronous connect. public virtual Task OnConnectedAsync() { return Task.CompletedTask; } + /// + /// Called when a connection with the hub is terminated. + /// + /// A that represents the asynchronous disconnect. public virtual Task OnDisconnectedAsync(Exception exception) { return Task.CompletedTask; } + /// + /// Releases all resources currently used by this instance. + /// + /// true if this method is being invoked by the method, + /// otherwise false. protected virtual void Dispose(bool disposing) { } + /// public void Dispose() { if (_disposed) diff --git a/src/Microsoft.AspNetCore.SignalR.Core/HubCallerContext.cs b/src/Microsoft.AspNetCore.SignalR.Core/HubCallerContext.cs index 64d62c859b..b0a30b3820 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/HubCallerContext.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/HubCallerContext.cs @@ -8,20 +8,44 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.SignalR { + /// + /// A context abstraction for accessing information about the hub caller connection. + /// public abstract class HubCallerContext { + /// + /// Gets the connection ID. + /// public abstract string ConnectionId { get; } + /// + /// Gets the user identifier. + /// public abstract string UserIdentifier { get; } + /// + /// Gets the user. + /// public abstract ClaimsPrincipal User { get; } + /// + /// Gets a key/value collection that can be used to share data within the scope of this connection. + /// public abstract IDictionary Items { get; } + /// + /// Gets the collection of HTTP features available on the connection. + /// public abstract IFeatureCollection Features { get; } + /// + /// Gets a that notifies when the connection is aborted. + /// public abstract CancellationToken ConnectionAborted { get; } + /// + /// Aborts the connection. + /// public abstract void Abort(); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionContext.cs b/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionContext.cs index 711cdd4f97..a446ab3f26 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionContext.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionContext.cs @@ -34,6 +34,12 @@ namespace Microsoft.AspNetCore.SignalR private long _lastSendTimestamp = Stopwatch.GetTimestamp(); private ReadOnlyMemory _cachedPingMessage; + /// + /// Initializes a new instance of the class. + /// + /// The underlying . + /// The keep alive interval. + /// The logger factory. public HubConnectionContext(ConnectionContext connectionContext, TimeSpan keepAliveInterval, ILoggerFactory loggerFactory) { _connectionContext = connectionContext; @@ -42,21 +48,42 @@ namespace Microsoft.AspNetCore.SignalR _keepAliveDuration = (int)keepAliveInterval.TotalMilliseconds * (Stopwatch.Frequency / 1000); } + /// + /// Gets a that notifies when the connection is aborted. + /// public virtual CancellationToken ConnectionAborted { get; } + /// + /// Gets the ID for this connection. + /// public virtual string ConnectionId => _connectionContext.ConnectionId; + /// + /// Gets the user for this connection. + /// public virtual ClaimsPrincipal User => Features.Get()?.User; + /// + /// Gets the collection of features available on this connection. + /// public virtual IFeatureCollection Features => _connectionContext.Features; + /// + /// Gets a key/value collection that can be used to share data within the scope of this connection. + /// public virtual IDictionary Items => _connectionContext.Items; // Used by HubConnectionHandler internal PipeReader Input => _connectionContext.Transport.Input; + /// + /// Gets or sets the user identifier for this connection. + /// public string UserIdentifier { get; set; } + /// + /// Gets the protocol used by this connection. + /// public virtual IHubProtocol Protocol { get; internal set; } internal ExceptionDispatchInfo AbortException { get; private set; } @@ -261,6 +288,9 @@ namespace Microsoft.AspNetCore.SignalR } } + /// + /// Aborts the connection. + /// public virtual void Abort() { // If we already triggered the token then noop, this isn't thread safe but it's good enough diff --git a/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionHandler.cs b/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionHandler.cs index 668016c25e..abc0f999f5 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionHandler.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/HubConnectionHandler.cs @@ -13,6 +13,9 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.SignalR { + /// + /// Handles incoming connections and implements the SignalR Hub Protocol. + /// public class HubConnectionHandler : ConnectionHandler where THub : Hub { private readonly HubLifetimeManager _lifetimeManager; @@ -25,6 +28,17 @@ namespace Microsoft.AspNetCore.SignalR private readonly HubDispatcher _dispatcher; private readonly bool _enableDetailedErrors; + /// + /// Initializes a new instance of the class. + /// + /// The hub lifetime manager. + /// The protocol resolver used to resolve the protocols between client and server. + /// The global options used to initialize hubs. + /// Hub specific options used to initialize hubs. These options override the global options. + /// The logger factory. + /// The user ID provider used to get the user ID from a hub connection. + /// The hub dispatcher used to dispatch incoming messages to hubs. + /// This class is typically created via dependency injection. public HubConnectionHandler(HubLifetimeManager lifetimeManager, IHubProtocolResolver protocolResolver, IOptions globalHubOptions, @@ -45,6 +59,7 @@ namespace Microsoft.AspNetCore.SignalR _enableDetailedErrors = _hubOptions.EnableDetailedErrors ?? _globalHubOptions.EnableDetailedErrors ?? false; } + /// public override async Task OnConnectedAsync(ConnectionContext connection) { // We check to see if HubOptions are set because those take precedence over global hub options. diff --git a/src/Microsoft.AspNetCore.SignalR.Core/HubLifetimeManager.cs b/src/Microsoft.AspNetCore.SignalR.Core/HubLifetimeManager.cs index b2a7698941..3022dd6286 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/HubLifetimeManager.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/HubLifetimeManager.cs @@ -7,35 +7,133 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR { + /// + /// A lifetime manager abstraction for instances. + /// public abstract class HubLifetimeManager where THub : Hub { // Called by the framework and not something we'd cancel, so it doesn't take a cancellation token + /// + /// Called when a connection is started. + /// + /// The connection. + /// A that represents the asynchronous connect. public abstract Task OnConnectedAsync(HubConnectionContext connection); // Called by the framework and not something we'd cancel, so it doesn't take a cancellation token + /// + /// Called when a connection is finished. + /// + /// The connection. + /// A that represents the asynchronous disconnect. public abstract Task OnDisconnectedAsync(HubConnectionContext connection); + /// + /// Sends an invocation message to all hub connections. + /// + /// The invocation method name. + /// The invocation arguments. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendAllAsync(string methodName, object[] args, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to all hub connections excluding the specified connections. + /// + /// The invocation method name. + /// The invocation arguments. + /// A collection of connection IDs to exclude. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendAllExceptAsync(string methodName, object[] args, IReadOnlyList excludedConnectionIds, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to the specified connection. + /// + /// The connection ID. + /// The invocation method name. + /// The invocation arguments. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendConnectionAsync(string connectionId, string methodName, object[] args, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to the specified connections. + /// + /// The connection IDs. + /// The invocation method name. + /// The invocation arguments. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendConnectionsAsync(IReadOnlyList connectionIds, string methodName, object[] args, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to the specified group. + /// + /// The group name. + /// The invocation method name. + /// The invocation arguments. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendGroupAsync(string groupName, string methodName, object[] args, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to the specified groups. + /// + /// The group names. + /// The invocation method name. + /// The invocation arguments. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendGroupsAsync(IReadOnlyList groupNames, string methodName, object[] args, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to the specified group excluding the specified connections. + /// + /// The group name. + /// The invocation method name. + /// The invocation arguments. + /// A collection of connection IDs to exclude. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendGroupExceptAsync(string groupName, string methodName, object[] args, IReadOnlyList excludedConnectionIds, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to the specified user. + /// + /// The user ID. + /// The invocation method name. + /// The invocation arguments. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendUserAsync(string userId, string methodName, object[] args, CancellationToken cancellationToken = default); + /// + /// Sends an invocation message to the specified users. + /// + /// The user IDs. + /// The invocation method name. + /// The invocation arguments. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous send. public abstract Task SendUsersAsync(IReadOnlyList userIds, string methodName, object[] args, CancellationToken cancellationToken = default); + /// + /// Adds a connection to the specified group. + /// + /// The connection ID to add to a group. + /// The group name. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous add. public abstract Task AddToGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default); + /// + /// Removes a connection from the specified group. + /// + /// The connection ID to remove from a group. + /// The group name. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous remove. public abstract Task RemoveFromGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default); } - } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/HubMethodNameAttribute.cs b/src/Microsoft.AspNetCore.SignalR.Core/HubMethodNameAttribute.cs index 1d51df2314..7aa54a510a 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/HubMethodNameAttribute.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/HubMethodNameAttribute.cs @@ -5,11 +5,21 @@ using System; namespace Microsoft.AspNetCore.SignalR { + /// + /// Customizes the name of a hub method. + /// [AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = true)] public class HubMethodNameAttribute : Attribute { + /// + /// The customized name of the hub method. + /// public string Name { get; } + /// + /// Initializes a new instance of class. + /// + /// The customized name of the hub method. public HubMethodNameAttribute(string name) { Name = name; diff --git a/src/Microsoft.AspNetCore.SignalR.Core/HubOptions.cs b/src/Microsoft.AspNetCore.SignalR.Core/HubOptions.cs index 83d1a70e1a..92816897ad 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/HubOptions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/HubOptions.cs @@ -6,18 +6,35 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.SignalR { + /// + /// Options used to configure hub instances. + /// public class HubOptions { // HandshakeTimeout and KeepAliveInterval are set to null here to help identify when // local hub options have been set. Global default values are set in HubOptionsSetup. // SupportedProtocols being null is the true default value, and it represents support // for all available protocols. + + /// + /// Gets or sets the interval used by the server to timeout incoming handshake requests by clients. + /// public TimeSpan? HandshakeTimeout { get; set; } = null; + /// + /// Gets or sets the interval used by the server to send keep alive pings to connected clients. + /// public TimeSpan? KeepAliveInterval { get; set; } = null; + /// + /// Gets or sets a collection of supported hub protocol names. + /// public IList SupportedProtocols { get; set; } = null; + /// + /// Gets or sets a value indicating whether detailed error messages are sent to the client. + /// Detailed error messages include details from exceptions thrown on the server. + /// public bool? EnableDetailedErrors { get; set; } = null; } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/HubOptions`T.cs b/src/Microsoft.AspNetCore.SignalR.Core/HubOptions`T.cs index 95ddcf0790..c98d40545c 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/HubOptions`T.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/HubOptions`T.cs @@ -3,5 +3,9 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// Options used to configure the specified hub type instances. These options override globally set options. + /// + /// The hub type to configure. public class HubOptions : HubOptions where THub : Hub { } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/Hub`T.cs b/src/Microsoft.AspNetCore.SignalR.Core/Hub`T.cs index 5463b7c35e..f091b0c200 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/Hub`T.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/Hub`T.cs @@ -5,10 +5,17 @@ using Microsoft.AspNetCore.SignalR.Internal; namespace Microsoft.AspNetCore.SignalR { + /// + /// A base class for a strongly typed SignalR hub. + /// + /// The type of client. public abstract class Hub : Hub where T : class { private IHubCallerClients _clients; + /// + /// Gets or sets a that can be used to invoke methods on the clients connected to this hub. + /// public new IHubCallerClients Clients { get diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IClientProxy.cs b/src/Microsoft.AspNetCore.SignalR.Core/IClientProxy.cs index 8baec45f19..e93ead6ec3 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IClientProxy.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IClientProxy.cs @@ -6,6 +6,9 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR { + /// + /// A proxy abstraction for invoking hub methods. + /// public interface IClientProxy { // client proxy method is called SendCoreAsync instead of SendAsync so that arrays of references @@ -19,7 +22,7 @@ namespace Microsoft.AspNetCore.SignalR /// Name of the method to invoke. /// A collection of arguments to pass to the client. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents when the data has been sent to the client. + /// A that represents the asynchronous invoke. Task SendCoreAsync(string method, object[] args, CancellationToken cancellationToken = default); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IGroupManager.cs b/src/Microsoft.AspNetCore.SignalR.Core/IGroupManager.cs index 93086570d2..4ec3f32090 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IGroupManager.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IGroupManager.cs @@ -6,9 +6,27 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.SignalR { + /// + /// A manager abstraction for adding and removing connections from groups. + /// public interface IGroupManager { + /// + /// Adds a connection to the specified group. + /// + /// The connection ID to add to a group. + /// The group name. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous add. Task AddToGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default); + + /// + /// Removes a connection from the specified group. + /// + /// The connection ID to remove from a group. + /// The group name. + /// The token to monitor for cancellation requests. The default value is . + /// A that represents the asynchronous remove. Task RemoveFromGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubActivator.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubActivator.cs index c4bdc2a6a4..aa0dcc435a 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubActivator.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubActivator.cs @@ -5,9 +5,22 @@ using System; namespace Microsoft.AspNetCore.SignalR { + /// + /// A activator abstraction. + /// + /// The hub type. public interface IHubActivator where THub : Hub { + /// + /// Creates a hub. + /// + /// The created hub. THub Create(); + + /// + /// Releases the specified hub. + /// + /// The hub to release. void Release(THub hub); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients.cs index 0bc7adb0aa..f0d77941bd 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients.cs @@ -3,5 +3,8 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// A clients caller abstraction for a hub. + /// public interface IHubCallerClients : IHubCallerClients { } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients`T.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients`T.cs index edd3ab8c80..d57906e9f9 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients`T.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubCallerClients`T.cs @@ -3,12 +3,26 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// An abstraction that provides access to client connections, including the one that sent the current invocation. + /// + /// The client caller type. public interface IHubCallerClients : IHubClients { + /// + /// Gets a caller to the connection which triggered the current invocation. + /// T Caller { get; } + /// + /// Gets a caller to all connections except the one which triggered the current invocation. + /// T Others { get; } + /// + /// Gets a caller to all connections in the specified group, except the one which triggered the current invocation. + /// + /// A client caller. T OthersInGroup(string groupName); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubClients.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubClients.cs index 47a3cc05f3..31ae2f5692 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubClients.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubClients.cs @@ -5,5 +5,8 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.SignalR { + /// + /// An abstraction that provides access to client connections. + /// public interface IHubClients : IHubClients { } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubClientsExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubClientsExtensions.cs index 0d19846948..18f8c02205 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubClientsExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubClientsExtensions.cs @@ -5,86 +5,96 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.SignalR { + /// + /// Extension methods for . + /// public static class IHubClientsExtensions { /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connection. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1) { return hubClients.AllExcept(new [] { excludedConnectionId1 }); } /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. /// The second connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1, string excludedConnectionId2) { return hubClients.AllExcept(new [] { excludedConnectionId1, excludedConnectionId2 }); } /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3) { return hubClients.AllExcept(new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3 }); } /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. /// The fourth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4) { return hubClients.AllExcept(new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4 }); } /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. /// The fourth connection to exclude. /// The fifth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5) { return hubClients.AllExcept(new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5 }); } /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. /// The fourth connection to exclude. /// The fifth connection to exclude. /// The sixth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5, string excludedConnectionId6) { return hubClients.AllExcept(new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5, excludedConnectionId6 }); } /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. @@ -92,15 +102,16 @@ namespace Microsoft.AspNetCore.SignalR /// The fifth connection to exclude. /// The sixth connection to exclude. /// The seventh connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5, string excludedConnectionId6, string excludedConnectionId7) { return hubClients.AllExcept(new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5, excludedConnectionId6, excludedConnectionId7 }); } /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. @@ -109,90 +120,97 @@ namespace Microsoft.AspNetCore.SignalR /// The sixth connection to exclude. /// The seventh connection to exclude. /// The eighth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T AllExcept(this IHubClients hubClients, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5, string excludedConnectionId6, string excludedConnectionId7, string excludedConnectionId8) { return hubClients.AllExcept(new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5, excludedConnectionId6, excludedConnectionId7, excludedConnectionId8 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1) { return hubClients.Clients(new [] { connection1 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. /// The second connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1, string connection2) { return hubClients.Clients(new [] { connection1, connection2 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. /// The second connection to include. /// The third connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1, string connection2, string connection3) { return hubClients.Clients(new [] { connection1, connection2, connection3 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. /// The second connection to include. /// The third connection to include. /// The fourth connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1, string connection2, string connection3, string connection4) { return hubClients.Clients(new [] { connection1, connection2, connection3, connection4 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. /// The second connection to include. /// The third connection to include. /// The fourth connection to include. /// The fifth connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1, string connection2, string connection3, string connection4, string connection5) { return hubClients.Clients(new [] { connection1, connection2, connection3, connection4, connection5 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. /// The second connection to include. /// The third connection to include. /// The fourth connection to include. /// The fifth connection to include. /// The sixth connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1, string connection2, string connection3, string connection4, string connection5, string connection6) { return hubClients.Clients(new [] { connection1, connection2, connection3, connection4, connection5, connection6 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. /// The second connection to include. /// The third connection to include. @@ -200,15 +218,16 @@ namespace Microsoft.AspNetCore.SignalR /// The fifth connection to include. /// The sixth connection to include. /// The seventh connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1, string connection2, string connection3, string connection4, string connection5, string connection6, string connection7) { return hubClients.Clients(new [] { connection1, connection2, connection3, connection4, connection5, connection6, connection7 }); } /// + /// Gets a that can be used to invoke methods on the specified connections. /// - /// + /// The abstraction that provides access to connections. /// The first connection to include. /// The second connection to include. /// The third connection to include. @@ -217,90 +236,97 @@ namespace Microsoft.AspNetCore.SignalR /// The sixth connection to include. /// The seventh connection to include. /// The eighth connection to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Clients(this IHubClients hubClients, string connection1, string connection2, string connection3, string connection4, string connection5, string connection6, string connection7, string connection8) { return hubClients.Clients(new [] { connection1, connection2, connection3, connection4, connection5, connection6, connection7, connection8 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1) { return hubClients.Groups(new [] { group1 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. /// The second group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1, string group2) { return hubClients.Groups(new [] { group1, group2 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. /// The second group to include. /// The third group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1, string group2, string group3) { return hubClients.Groups(new [] { group1, group2, group3 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. /// The second group to include. /// The third group to include. /// The fourth group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1, string group2, string group3, string group4) { return hubClients.Groups(new [] { group1, group2, group3, group4 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. /// The second group to include. /// The third group to include. /// The fourth group to include. /// The fifth group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1, string group2, string group3, string group4, string group5) { return hubClients.Groups(new [] { group1, group2, group3, group4, group5 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. /// The second group to include. /// The third group to include. /// The fourth group to include. /// The fifth group to include. /// The sixth group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1, string group2, string group3, string group4, string group5, string group6) { return hubClients.Groups(new [] { group1, group2, group3, group4, group5, group6 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. /// The second group to include. /// The third group to include. @@ -308,15 +334,16 @@ namespace Microsoft.AspNetCore.SignalR /// The fifth group to include. /// The sixth group to include. /// The seventh group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1, string group2, string group3, string group4, string group5, string group6, string group7) { return hubClients.Groups(new [] { group1, group2, group3, group4, group5, group6, group7 }); } /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. /// - /// + /// The abstraction that provides access to connections. /// The first group to include. /// The second group to include. /// The third group to include. @@ -325,97 +352,104 @@ namespace Microsoft.AspNetCore.SignalR /// The sixth group to include. /// The seventh group to include. /// The eighth group to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Groups(this IHubClients hubClients, string group1, string group2, string group3, string group4, string group5, string group6, string group7, string group8) { return hubClients.Groups(new [] { group1, group2, group3, group4, group5, group6, group7, group8 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. /// The second connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1, string excludedConnectionId2) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1, excludedConnectionId2 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. /// The fourth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. /// The fourth connection to exclude. /// The fifth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. /// The fourth connection to exclude. /// The fifth connection to exclude. /// The sixth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5, string excludedConnectionId6) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5, excludedConnectionId6 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. @@ -423,16 +457,17 @@ namespace Microsoft.AspNetCore.SignalR /// The fifth connection to exclude. /// The sixth connection to exclude. /// The seventh connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5, string excludedConnectionId6, string excludedConnectionId7) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5, excludedConnectionId6, excludedConnectionId7 }); } /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. /// - /// - /// + /// The abstraction that provides access to connections. + /// The group name. /// The first connection to exclude. /// The second connection to exclude. /// The third connection to exclude. @@ -441,90 +476,97 @@ namespace Microsoft.AspNetCore.SignalR /// The sixth connection to exclude. /// The seventh connection to exclude. /// The eighth connection to exclude. - /// + /// A representing the methods that can be invoked on the clients. public static T GroupExcept(this IHubClients hubClients, string groupName, string excludedConnectionId1, string excludedConnectionId2, string excludedConnectionId3, string excludedConnectionId4, string excludedConnectionId5, string excludedConnectionId6, string excludedConnectionId7, string excludedConnectionId8) { return hubClients.GroupExcept(groupName, new [] { excludedConnectionId1, excludedConnectionId2, excludedConnectionId3, excludedConnectionId4, excludedConnectionId5, excludedConnectionId6, excludedConnectionId7, excludedConnectionId8 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1) { return hubClients.Users(new [] { user1 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. /// The second user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1, string user2) { return hubClients.Users(new [] { user1, user2 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. /// The second user to include. /// The third user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1, string user2, string user3) { return hubClients.Users(new [] { user1, user2, user3 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. /// The second user to include. /// The third user to include. /// The fourth user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1, string user2, string user3, string user4) { return hubClients.Users(new [] { user1, user2, user3, user4 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. /// The second user to include. /// The third user to include. /// The fourth user to include. /// The fifth user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1, string user2, string user3, string user4, string user5) { return hubClients.Users(new [] { user1, user2, user3, user4, user5 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. /// The second user to include. /// The third user to include. /// The fourth user to include. /// The fifth user to include. /// The sixth user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1, string user2, string user3, string user4, string user5, string user6) { return hubClients.Users(new [] { user1, user2, user3, user4, user5, user6 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. /// The second user to include. /// The third user to include. @@ -532,15 +574,16 @@ namespace Microsoft.AspNetCore.SignalR /// The fifth user to include. /// The sixth user to include. /// The seventh user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1, string user2, string user3, string user4, string user5, string user6, string user7) { return hubClients.Users(new [] { user1, user2, user3, user4, user5, user6, user7 }); } /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. /// - /// + /// The abstraction that provides access to connections. /// The first user to include. /// The second user to include. /// The third user to include. @@ -549,7 +592,7 @@ namespace Microsoft.AspNetCore.SignalR /// The sixth user to include. /// The seventh user to include. /// The eighth user to include. - /// + /// A representing the methods that can be invoked on the clients. public static T Users(this IHubClients hubClients, string user1, string user2, string user3, string user4, string user5, string user6, string user7, string user8) { return hubClients.Users(new [] { user1, user2, user3, user4, user5, user6, user7, user8 }); diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubClients`T.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubClients`T.cs index 76e9bb12f1..3b165f14de 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubClients`T.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubClients`T.cs @@ -5,24 +5,73 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.SignalR { + /// + /// An abstraction that provides access to client connections. + /// + /// The client invoker type. public interface IHubClients { + /// + /// Gets a that can be used to invoke methods on all clients connected to the hub. + /// + /// A client caller. T All { get; } + /// + /// Gets a that can be used to invoke methods on all clients connected to the hub excluding the specified client connections. + /// + /// A collection of connection IDs to exclude. + /// A client caller. T AllExcept(IReadOnlyList excludedConnectionIds); + /// + /// Gets a that can be used to invoke methods on the specified client connection. + /// + /// The connection ID. + /// A client caller. T Client(string connectionId); + /// + /// Gets a that can be used to invoke methods on the specified client connections. + /// + /// The connection IDs. + /// A client caller. T Clients(IReadOnlyList connectionIds); + /// + /// Gets a that can be used to invoke methods on all connections in the specified group. + /// + /// The group name. + /// A client caller. T Group(string groupName); + /// + /// Gets a that can be used to invoke methods on all connections in all of the specified groups. + /// + /// The group names. + /// A client caller. T Groups(IReadOnlyList groupNames); + /// + /// Gets a that can be used to invoke methods on all connections in the specified group excluding the specified connections. + /// + /// The group name. + /// A collection of connection IDs to exclude. + /// A client caller. T GroupExcept(string groupName, IReadOnlyList excludedConnectionIds); + /// + /// Gets a that can be used to invoke methods on all connections associated with the specified user. + /// + /// The user ID. + /// A client caller. T User(string userId); + /// + /// Gets a that can be used to invoke methods on all connections associated with all of the specified users. + /// + /// The user IDs. + /// A client caller. T Users(IReadOnlyList userIds); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubContext.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubContext.cs index 2c92da730c..b7a0a4348f 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubContext.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubContext.cs @@ -3,10 +3,19 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// A context abstraction for a hub. + /// public interface IHubContext where THub : Hub { + /// + /// Gets a that can be used to invoke methods on clients connected to the hub. + /// IHubClients Clients { get; } + /// + /// Gets a that can be used to add and remove connections to named groups. + /// IGroupManager Groups { get; } } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubContext`T.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubContext`T.cs index 305e8bed3d..650fe127e3 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubContext`T.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubContext`T.cs @@ -3,12 +3,21 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// A context abstraction for a hub. + /// public interface IHubContext where THub : Hub where T : class { + /// + /// Gets a that can be used to invoke methods on clients connected to the hub. + /// IHubClients Clients { get; } + /// + /// Gets a that can be used to add and remove connections to named groups. + /// IGroupManager Groups { get; } } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IHubProtocolResolver.cs b/src/Microsoft.AspNetCore.SignalR.Core/IHubProtocolResolver.cs index 5444720d4f..b457c6e29b 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IHubProtocolResolver.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IHubProtocolResolver.cs @@ -6,9 +6,22 @@ using Microsoft.AspNetCore.SignalR.Protocol; namespace Microsoft.AspNetCore.SignalR { + /// + /// A resolver abstraction for working with instances. + /// public interface IHubProtocolResolver { + /// + /// Gets a collection of all available hub protocols. + /// IReadOnlyList AllProtocols { get; } + + /// + /// Gets the hub protocol with the specified name, if it is allowed by the specified list of supported protocols. + /// + /// The protocol name. + /// A collection of supported protocols. + /// A matching or null if no matching protocol was found. IHubProtocol GetProtocol(string protocolName, IReadOnlyList supportedProtocols); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/ISignalRServerBuilder.cs b/src/Microsoft.AspNetCore.SignalR.Core/ISignalRServerBuilder.cs index f3ad4235a2..ab8f380b4a 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/ISignalRServerBuilder.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/ISignalRServerBuilder.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// A builder abstraction for configuring SignalR servers. + /// public interface ISignalRServerBuilder : ISignalRBuilder { } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/IUserIdProvider.cs b/src/Microsoft.AspNetCore.SignalR.Core/IUserIdProvider.cs index c2ff572a09..0053705598 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/IUserIdProvider.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/IUserIdProvider.cs @@ -3,8 +3,17 @@ namespace Microsoft.AspNetCore.SignalR { + /// + /// A provider abstraction for configuring the "User ID" for a connection. + /// + /// is used by to invoke connections associated with a user. public interface IUserIdProvider { + /// + /// Gets the user ID for the specified connection. + /// + /// The connection get get the user ID for. + /// The user ID for the specified connection. string GetUserId(HubConnectionContext connection); } } \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.SignalR.Core/Internal/DefaultHubCallerContext.cs b/src/Microsoft.AspNetCore.SignalR.Core/Internal/DefaultHubCallerContext.cs index ead0dc6f9e..1d3b93b232 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/Internal/DefaultHubCallerContext.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/Internal/DefaultHubCallerContext.cs @@ -10,6 +10,9 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.SignalR.Internal { + /// + /// A context for accessing information about the hub caller from their connection. + /// public class DefaultHubCallerContext : HubCallerContext { private readonly HubConnectionContext _connection; @@ -19,18 +22,25 @@ namespace Microsoft.AspNetCore.SignalR.Internal _connection = connection; } + /// public override string ConnectionId => _connection.ConnectionId; + /// public override string UserIdentifier => _connection.UserIdentifier; + /// public override ClaimsPrincipal User => _connection.User; + /// public override IDictionary Items => _connection.Items; + /// public override IFeatureCollection Features => _connection.Features; + /// public override CancellationToken ConnectionAborted => _connection.ConnectionAborted; + /// public override void Abort() => _connection.Abort(); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Core/SerializedHubMessage.cs b/src/Microsoft.AspNetCore.SignalR.Core/SerializedHubMessage.cs index be46ed61e8..99a969a3a9 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/SerializedHubMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/SerializedHubMessage.cs @@ -8,7 +8,6 @@ using Microsoft.AspNetCore.SignalR.Protocol; namespace Microsoft.AspNetCore.SignalR { /// - /// This class is designed to support the framework. The API is subject to breaking changes. /// Represents a serialization cache for a single message. /// public class SerializedHubMessage @@ -18,8 +17,15 @@ namespace Microsoft.AspNetCore.SignalR private IList _cachedItems; private readonly object _lock = new object(); + /// + /// Gets the hub message for the serialization cache. + /// public HubMessage Message { get; } + /// + /// Initializes a new instance of the class. + /// + /// A collection of already serialized messages to cache. public SerializedHubMessage(IReadOnlyList messages) { // A lock isn't needed here because nobody has access to this type until the constructor finishes. @@ -30,11 +36,20 @@ namespace Microsoft.AspNetCore.SignalR } } + /// + /// Initializes a new instance of the class. + /// + /// The hub message for the cache. This will be serialized with an in to get the message's serialized representation. public SerializedHubMessage(HubMessage message) { Message = message; } + /// + /// Gets the serialized representation of the using the specified . + /// + /// The protocol used to create the serialized representation. + /// The serialized representation of the . public ReadOnlyMemory GetSerializedMessage(IHubProtocol protocol) { lock (_lock) diff --git a/src/Microsoft.AspNetCore.SignalR.Core/SerializedMessage.cs b/src/Microsoft.AspNetCore.SignalR.Core/SerializedMessage.cs index cf13afcaa3..5f3b8a351b 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/SerializedMessage.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/SerializedMessage.cs @@ -5,11 +5,26 @@ using System; namespace Microsoft.AspNetCore.SignalR { + /// + /// Represents a serialized message. + /// public readonly struct SerializedMessage { + /// + /// Gets the protocol of the serialized message. + /// public string ProtocolName { get; } + + /// + /// Gets the serialized representation of the message. + /// public ReadOnlyMemory Serialized { get; } + /// + /// Initializes a new instance of the class. + /// + /// The protocol of the serialized message. + /// The serialized representation of the message. public SerializedMessage(string protocolName, ReadOnlyMemory serialized) { ProtocolName = protocolName; diff --git a/src/Microsoft.AspNetCore.SignalR.Core/SignalRConnectionBuilderExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Core/SignalRConnectionBuilderExtensions.cs index 8645d2aeff..2e8f076af8 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/SignalRConnectionBuilderExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/SignalRConnectionBuilderExtensions.cs @@ -8,8 +8,17 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.SignalR { + /// + /// Extension methods for . + /// public static class SignalRConnectionBuilderExtensions { + /// + /// Configure the connection to host the specified type. + /// + /// The type to host on the connection. + /// The connection to configure. + /// The same instance of the for chaining. public static IConnectionBuilder UseHub(this IConnectionBuilder connectionBuilder) where THub : Hub { var marker = connectionBuilder.ApplicationServices.GetService(typeof(SignalRMarkerService)); diff --git a/src/Microsoft.AspNetCore.SignalR.Core/SignalRDependencyInjectionExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Core/SignalRDependencyInjectionExtensions.cs index 0705ec933d..5240748836 100644 --- a/src/Microsoft.AspNetCore.SignalR.Core/SignalRDependencyInjectionExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Core/SignalRDependencyInjectionExtensions.cs @@ -6,8 +6,17 @@ using Microsoft.AspNetCore.SignalR.Internal; namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods for . + /// public static class SignalRDependencyInjectionExtensions { + /// + /// Adds the minimum essential SignalR services to the specified . Additional services + /// must be added separately using the returned from this method. + /// + /// The to add services to. + /// An that can be used to further configure the SignalR services. public static ISignalRServerBuilder AddSignalRCore(this IServiceCollection services) { services.AddSingleton(); diff --git a/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonHubProtocolOptions.cs b/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonHubProtocolOptions.cs index adcbf22721..cd978a52eb 100644 --- a/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonHubProtocolOptions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonHubProtocolOptions.cs @@ -6,8 +6,14 @@ using Newtonsoft.Json; namespace Microsoft.AspNetCore.SignalR { + /// + /// Options used to configure a instance. + /// public class JsonHubProtocolOptions { + /// + /// Gets or sets the settings used to serialize invocation arguments and return values. + /// public JsonSerializerSettings PayloadSerializerSettings { get; set; } = JsonHubProtocol.CreateDefaultSerializerSettings(); } } diff --git a/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonProtocolDependencyInjectionExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonProtocolDependencyInjectionExtensions.cs index 94567d4a74..8b4c40f33a 100644 --- a/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonProtocolDependencyInjectionExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Protocols.Json/JsonProtocolDependencyInjectionExtensions.cs @@ -6,6 +6,9 @@ using Microsoft.Extensions.DependencyInjection.Extensions; namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods for . + /// public static class JsonProtocolDependencyInjectionExtensions { /// diff --git a/src/Microsoft.AspNetCore.SignalR.Protocols.Json/Protocol/JsonHubProtocol.cs b/src/Microsoft.AspNetCore.SignalR.Protocols.Json/Protocol/JsonHubProtocol.cs index 4c471386a7..e2464bbbe4 100644 --- a/src/Microsoft.AspNetCore.SignalR.Protocols.Json/Protocol/JsonHubProtocol.cs +++ b/src/Microsoft.AspNetCore.SignalR.Protocols.Json/Protocol/JsonHubProtocol.cs @@ -16,6 +16,9 @@ using Newtonsoft.Json.Serialization; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// Implements the SignalR Hub Protocol using JSON. + /// public class JsonHubProtocol : IHubProtocol { private const string ResultPropertyName = "result"; @@ -30,29 +33,43 @@ namespace Microsoft.AspNetCore.SignalR.Protocol private static readonly string ProtocolName = "json"; private static readonly int ProtocolVersion = 1; - // ONLY to be used for application payloads (args, return values, etc.) + /// + /// Gets the serializer used to serialize invocation arguments and return values. + /// public JsonSerializer PayloadSerializer { get; } + /// + /// Initializes a new instance of the class. + /// public JsonHubProtocol() : this(Options.Create(new JsonHubProtocolOptions())) { } + /// + /// Initializes a new instance of the class. + /// + /// The options used to initialize the protocol. public JsonHubProtocol(IOptions options) { PayloadSerializer = JsonSerializer.Create(options.Value.PayloadSerializerSettings); } + /// public string Name => ProtocolName; + /// public int Version => ProtocolVersion; + /// public TransferFormat TransferFormat => TransferFormat.Text; + /// public bool IsVersionSupported(int version) { return version == Version; } + /// public bool TryParseMessage(ref ReadOnlySequence input, IInvocationBinder binder, out HubMessage message) { if (!TextMessageParser.TryParseMessage(ref input, out var payload)) @@ -75,12 +92,14 @@ namespace Microsoft.AspNetCore.SignalR.Protocol return message != null; } + /// public void WriteMessage(HubMessage message, IBufferWriter output) { WriteMessageCore(message, output); TextMessageFormatter.WriteRecordSeparator(output); } + /// public ReadOnlyMemory GetMessageBytes(HubMessage message) { return HubProtocolExtensions.GetMessageBytes(this, message); diff --git a/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/MessagePackProtocolDependencyInjectionExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/MessagePackProtocolDependencyInjectionExtensions.cs index 861ec06173..ce13329cc7 100644 --- a/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/MessagePackProtocolDependencyInjectionExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/MessagePackProtocolDependencyInjectionExtensions.cs @@ -8,6 +8,9 @@ using Microsoft.Extensions.DependencyInjection.Extensions; namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods for . + /// public static class MessagePackProtocolDependencyInjectionExtensions { /// diff --git a/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/Protocol/MessagePackHubProtocol.cs b/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/Protocol/MessagePackHubProtocol.cs index 02a8065def..0b693605bf 100644 --- a/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/Protocol/MessagePackHubProtocol.cs +++ b/src/Microsoft.AspNetCore.SignalR.Protocols.MessagePack/Protocol/MessagePackHubProtocol.cs @@ -16,6 +16,9 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.SignalR.Protocol { + /// + /// Implements the SignalR Hub Protocol using MessagePack. + /// public class MessagePackHubProtocol : IHubProtocol { private const int ErrorResult = 1; @@ -27,16 +30,26 @@ namespace Microsoft.AspNetCore.SignalR.Protocol private static readonly string ProtocolName = "messagepack"; private static readonly int ProtocolVersion = 1; + /// public string Name => ProtocolName; + /// public int Version => ProtocolVersion; + /// public TransferFormat TransferFormat => TransferFormat.Binary; + /// + /// Initializes a new instance of the class. + /// public MessagePackHubProtocol() : this(Options.Create(new MessagePackHubProtocolOptions())) { } + /// + /// Initializes a new instance of the class. + /// + /// The options used to initialize the protocol. public MessagePackHubProtocol(IOptions options) { var msgPackOptions = options.Value; @@ -67,11 +80,13 @@ namespace Microsoft.AspNetCore.SignalR.Protocol _resolver = SignalRResolver.Instance; } + /// public bool IsVersionSupported(int version) { return version == Version; } + /// public bool TryParseMessage(ref ReadOnlySequence input, IInvocationBinder binder, out HubMessage message) { if (!BinaryMessageParser.TryParseMessage(ref input, out var payload)) @@ -283,6 +298,7 @@ namespace Microsoft.AspNetCore.SignalR.Protocol return destination; } + /// public void WriteMessage(HubMessage message, IBufferWriter output) { var writer = MemoryBufferWriter.Get(); @@ -302,6 +318,7 @@ namespace Microsoft.AspNetCore.SignalR.Protocol } } + /// public ReadOnlyMemory GetMessageBytes(HubMessage message) { var writer = MemoryBufferWriter.Get(); diff --git a/src/Microsoft.AspNetCore.SignalR.Redis/RedisDependencyInjectionExtensions.cs b/src/Microsoft.AspNetCore.SignalR.Redis/RedisDependencyInjectionExtensions.cs index b8290ce5ed..61f240fd72 100644 --- a/src/Microsoft.AspNetCore.SignalR.Redis/RedisDependencyInjectionExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Redis/RedisDependencyInjectionExtensions.cs @@ -8,13 +8,27 @@ using StackExchange.Redis; namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods for configuring Redis-based scale-out for a SignalR Server in an . + /// public static class RedisDependencyInjectionExtensions { + /// + /// Adds scale-out to a , using a shared Redis server. + /// + /// The . + /// The same instance of the for chaining. public static ISignalRServerBuilder AddRedis(this ISignalRServerBuilder builder) { return AddRedis(builder, o => { }); } + /// + /// Adds scale-out to a , using a shared Redis server. + /// + /// The . + /// The connection string used to connect to the Redis server. + /// The same instance of the for chaining. public static ISignalRServerBuilder AddRedis(this ISignalRServerBuilder builder, string redisConnectionString) { return AddRedis(builder, o => @@ -23,6 +37,12 @@ namespace Microsoft.Extensions.DependencyInjection }); } + /// + /// Adds scale-out to a , using a shared Redis server. + /// + /// The . + /// A callback to configure the Redis options. + /// The same instance of the for chaining. public static ISignalRServerBuilder AddRedis(this ISignalRServerBuilder builder, Action configure) { builder.Services.Configure(configure); @@ -30,6 +50,13 @@ namespace Microsoft.Extensions.DependencyInjection return builder; } + /// + /// Adds scale-out to a , using a shared Redis server. + /// + /// The . + /// The connection string used to connect to the Redis server. + /// A callback to configure the Redis options. + /// The same instance of the for chaining. public static ISignalRServerBuilder AddRedis(this ISignalRServerBuilder builder, string redisConnectionString, Action configure) { return AddRedis(builder, o => diff --git a/src/Microsoft.AspNetCore.SignalR.Redis/RedisOptions.cs b/src/Microsoft.AspNetCore.SignalR.Redis/RedisOptions.cs index b8f95e0e91..17d5890cf8 100644 --- a/src/Microsoft.AspNetCore.SignalR.Redis/RedisOptions.cs +++ b/src/Microsoft.AspNetCore.SignalR.Redis/RedisOptions.cs @@ -9,14 +9,23 @@ using StackExchange.Redis; namespace Microsoft.AspNetCore.SignalR.Redis { + /// + /// Options used to configure . + /// public class RedisOptions { + /// + /// Gets or sets configuration options exposed by StackExchange.Redis. + /// public ConfigurationOptions Configuration { get; set; } = new ConfigurationOptions { // Enable reconnecting by default AbortOnConnectFail = false }; + /// + /// Gets or sets the Redis connection factory. + /// public Func> ConnectionFactory { get; set; } internal async Task ConnectAsync(TextWriter log) diff --git a/src/Microsoft.AspNetCore.SignalR/GetHttpContextExtensions.cs b/src/Microsoft.AspNetCore.SignalR/GetHttpContextExtensions.cs index f2a076b7f9..9d36c4967a 100644 --- a/src/Microsoft.AspNetCore.SignalR/GetHttpContextExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR/GetHttpContextExtensions.cs @@ -7,8 +7,16 @@ using Microsoft.AspNetCore.Http.Connections.Features; namespace Microsoft.AspNetCore.SignalR { + /// + /// Extension methods for accessing from a hub context. + /// public static class GetHttpContextExtensions { + /// + /// Gets from the specified connection, or null if the connection is not associated with an HTTP request. + /// + /// The connection. + /// The for the connection, or null if the connection is not associated with an HTTP request. public static HttpContext GetHttpContext(this HubCallerContext connection) { if (connection == null) @@ -18,6 +26,11 @@ namespace Microsoft.AspNetCore.SignalR return connection.Features.Get()?.HttpContext; } + /// + /// Gets from the specified connection, or null if the connection is not associated with an HTTP request. + /// + /// The connection. + /// The for the connection, or null if the connection is not associated with an HTTP request. public static HttpContext GetHttpContext(this HubConnectionContext connection) { if (connection == null) diff --git a/src/Microsoft.AspNetCore.SignalR/HubRouteBuilder.cs b/src/Microsoft.AspNetCore.SignalR/HubRouteBuilder.cs index 573bfec620..06f945bbb0 100644 --- a/src/Microsoft.AspNetCore.SignalR/HubRouteBuilder.cs +++ b/src/Microsoft.AspNetCore.SignalR/HubRouteBuilder.cs @@ -9,20 +9,38 @@ using Microsoft.AspNetCore.Http.Connections; namespace Microsoft.AspNetCore.SignalR { + /// + /// Maps incoming requests to types. + /// public class HubRouteBuilder { private readonly ConnectionsRouteBuilder _routes; + /// + /// Initializes a new instance of the class. + /// + /// The routes builder. public HubRouteBuilder(ConnectionsRouteBuilder routes) { _routes = routes; } + /// + /// Maps incoming requests with the specified path to the specified type. + /// + /// The type to map requests to. + /// The request path. public void MapHub(PathString path) where THub : Hub { MapHub(path, configureOptions: null); } + /// + /// Maps incoming requests with the specified path to the specified type. + /// + /// The type to map requests to. + /// The request path. + /// A callback to configure dispatcher options. public void MapHub(PathString path, Action configureOptions) where THub : Hub { // find auth attributes diff --git a/src/Microsoft.AspNetCore.SignalR/SignalRAppBuilderExtensions.cs b/src/Microsoft.AspNetCore.SignalR/SignalRAppBuilderExtensions.cs index 441e4e2467..c7f5afa84e 100644 --- a/src/Microsoft.AspNetCore.SignalR/SignalRAppBuilderExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR/SignalRAppBuilderExtensions.cs @@ -6,8 +6,17 @@ using Microsoft.AspNetCore.SignalR; namespace Microsoft.AspNetCore.Builder { + /// + /// Extension methods for . + /// public static class SignalRAppBuilderExtensions { + /// + /// Adds SignalR to the request execution pipeline. + /// + /// The . + /// A callback to configure hub routes. + /// The same instance of the for chaining. public static IApplicationBuilder UseSignalR(this IApplicationBuilder app, Action configure) { app.UseConnections(routes => diff --git a/src/Microsoft.AspNetCore.SignalR/SignalRDependencyInjectionExtensions.cs b/src/Microsoft.AspNetCore.SignalR/SignalRDependencyInjectionExtensions.cs index 77caeec93a..a521bea32c 100644 --- a/src/Microsoft.AspNetCore.SignalR/SignalRDependencyInjectionExtensions.cs +++ b/src/Microsoft.AspNetCore.SignalR/SignalRDependencyInjectionExtensions.cs @@ -8,8 +8,18 @@ using Microsoft.Extensions.Options; namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods for setting up SignalR services in an . + /// public static class SignalRDependencyInjectionExtensions { + /// + /// Adds hub specific options to an . + /// + /// The hub type to configure. + /// The . + /// A callback to configure the hub options. + /// The same instance of the for chaining. public static ISignalRServerBuilder AddHubOptions(this ISignalRServerBuilder signalrBuilder, Action> options) where THub : Hub { signalrBuilder.Services.AddSingleton>, HubOptionsSetup>(); @@ -17,6 +27,11 @@ namespace Microsoft.Extensions.DependencyInjection return signalrBuilder; } + /// + /// Adds SignalR services to the specified . + /// + /// The to add services to. + /// An that can be used to further configure the SignalR services. public static ISignalRServerBuilder AddSignalR(this IServiceCollection services) { services.AddConnections(); @@ -24,6 +39,12 @@ namespace Microsoft.Extensions.DependencyInjection return services.AddSignalRCore(); } + /// + /// Adds SignalR services to the specified . + /// + /// The to add services to. + /// An to configure the provided . + /// An that can be used to further configure the SignalR services. public static ISignalRServerBuilder AddSignalR(this IServiceCollection services, Action options) { return services.Configure(options)