Configuración de SignalR en ASP.NET Core
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el método de extensión AddJsonProtocol. AddJsonProtocol
puede agregarse después de AddSignalR en Startup.ConfigureServices
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerOptions de ese objeto es un System.Text.Json
JsonSerializerOptions objeto que se puede utilizar para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación System.Text.Json.
Por ejemplo, para configurar el serializador para que no cambie el tipo de letra de los nombres de las propiedades, en lugar de las mayúsculas y minúsculas por defecto, utilice el siguiente código en Program.cs
:
builder.Services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Cambiar a Newtonsoft.Json
Si necesita características de Newtonsoft.Json
que no son compatibles con System.Text.Json
, consulte Cambiar a Newtonsoft.Json
.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ClientTimeoutInterval |
30 segundos | El servidor considera que el cliente está desconectado si no ha recibido ningún mensaje (incluido conexión persistente) en este intervalo. Podría tomar más tiempo que este intervalo de tiempo de espera para que el cliente sea marcado como desconectado debido a la forma en que esto se implementa. El valor recomendado es el doble KeepAliveInterval . |
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
StreamBufferCapacity |
10 |
Número máximo de elementos que pueden almacenarse en el búfer para flujos de carga de clientes. Si se alcanza este límite, se bloquea el procesamiento de las invocaciones hasta que el servidor procese los elementos del flujo. |
MaximumReceiveMessageSize |
32 KB | Tamaño máximo de un único mensaje hub entrante. Aumentar el valor puede aumentar el riesgo de ataques por denegación de servicio (DoS). |
MaximumParallelInvocationsPerClient |
1 | El número máximo de métodos del hub que cada cliente puede llamar en paralelo antes de ponerse en cola. |
DisableImplicitFromServicesParameters |
false |
Los argumentos del método hub se resuelven a partir de DI si es posible. |
Las opciones pueden configurarse para todos los hubs proporcionando un delegado de opciones a la AddSignalR
llamada en Program.cs
.
builder.Services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Program.cs
.
using Microsoft.AspNetCore.Http.Connections;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddSignalR();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
}
);
app.Run();
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
64 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al servidor recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
TransportMaxBufferSize |
64 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al servidor almacenar en el búfer mensajes más grandes más rápidamente sin esperar la contrapresión, pero puede aumentar el consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
MinimumProtocolVersion |
0 | Especifique la versión mínima del protocolo de negociación. Se utiliza para limitar los clientes a las versiones más recientes. |
CloseOnAuthenticationExpiration |
false | Establezca esta opción para activar el seguimiento de caducidad de autenticación, que cerrará las conexiones cuando caduque un token. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
En lugar de un valor LogLevel
, también puede proporcionar un valor string
que represente un nombre de nivel de registro. Esto es útil cuando se configura el registro SignalR en entornos en los que no se tiene acceso a las constantes LogLevel
.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
La siguiente tabla enumera los niveles de registro disponibles. El valor que proporcione establece configureLogging
el nivel mínimo de registro que se registrará. Se registrarán los mensajes registrados en este nivel o en los niveles indicados a continuación en la tabla.
String | LogLevel |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info o information |
LogLevel.Information |
warn o warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Nota:
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
En esta versión del cliente Java, websockets es el único transporte disponible.
En el cliente Java, el transporte se selecciona con el métodowithTransport
en el HttpHubConnectionBuilder
. El cliente Java utiliza por defecto el transporte WebSockets.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Nota:
El SignalR cliente Java aún no admite el transporte de reserva.
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente:
Opción | Valor predeterminado | Descripción |
---|---|---|
WithServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor y se establece directamente en HubConnectionBuilder. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número que al menos duplique el valor del intervalo de la conexión persistente (WithKeepAliveInterval ) del servidor para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor y está disponible en el HubConnection propio objeto. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
WithKeepAliveInterval |
15 segundos | Determina el intervalo en el que el cliente envía mensajes ping y se establece directamente en HubConnectionBuilder. Esta configuración permite al servidor detectar desconexiones físicas, como cuando un cliente desconecta su equipo de la red. El envío de cualquier mensaje desde el cliente reinicia el temporizador al inicio del intervalo. Si el cliente no ha enviado ningún mensaje en el conjunto ClientTimeoutInterval en el servidor, el servidor considera que el cliente está desconectado. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
El siguiente ejemplo muestra valores que duplican los valores por defecto:
var builder = new HubConnectionBuilder()
.WithUrl(Navigation.ToAbsoluteUri("/chathub"))
.WithServerTimeout(TimeSpan.FromSeconds(60))
.WithKeepAliveInterval(TimeSpan.FromSeconds(30))
.Build();
builder.On<string, string>("ReceiveMessage", (user, message) => ...
await builder.StartAsync();
Configuración de la reconexión con estado
La reconexión con estado de SignalR reduce el tiempo de inactividad percibido de los clientes que tienen una desconexión temporal en su conexión de red, como al cambiar las conexiones de red o una breve pérdida temporal de acceso.
La reconexión con estado lo consigue gracias a:
- Almacenamiento temporal en búfer de los datos en el servidor y el cliente.
- Confirmación de los mensajes recibidos (ACK-ing) tanto por el servidor como por el cliente.
- Reconocimiento de cuándo una conexión está activa y se reproducen mensajes que pueden haberse enviado mientras la conexión estaba inactiva.
La reconexión con estado está disponible en ASP.NET Core 8.0 y versiones posteriores.
Opte por la reconexión con estado tanto en el punto de conexión del centro de servidores como en el cliente:
Actualice la configuración del punto de conexión del centro de servidores para habilitar la opción
AllowStatefulReconnects
:app.MapHub<MyHub>("/hubName", options => { options.AllowStatefulReconnects = true; });
Opcionalmente, el tamaño máximo del búfer en bytes permitido por el servidor se puede establecer globalmente o para un centro específico con la opción
StatefulReconnectBufferSize
:La opción
StatefulReconnectBufferSize
establecida globalmente:builder.AddSignalR(o => o.StatefulReconnectBufferSize = 1000);
La opción
StatefulReconnectBufferSize
establecida para un centro específico:builder.AddSignalR().AddHubOptions<MyHub>(o => o.StatefulReconnectBufferSize = 1000);
La opción
StatefulReconnectBufferSize
es opcional con un valor predeterminado de 100 000 bytes.Actualice el código de cliente de JavaScript o TypeScript para habilitar la opción
withStatefulReconnect
:const builder = new signalR.HubConnectionBuilder() .withUrl("/hubname") .withStatefulReconnect({ bufferSize: 1000 }); // Optional, defaults to 100,000 const connection = builder.build();
La opción
bufferSize
es opcional con un valor predeterminado de 100 000 bytes.Actualice el código de cliente de .NET para habilitar la opción
WithStatefulReconnect
:var builder = new HubConnectionBuilder() .WithUrl("<hub url>") .WithStatefulReconnect(); builder.Services.Configure<HubConnectionOptions>(o => o.StatefulReconnectBufferSize = 1000); var hubConnection = builder.Build();
La opción
StatefulReconnectBufferSize
es opcional con un valor predeterminado de 100 000 bytes.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
ApplicationMaxBufferSize |
1 MB | El número máximo de bytes recibidos del servidor que el cliente almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al cliente recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
TransportMaxBufferSize |
1 MB | El número máximo de bytes enviados por la aplicación de usuario que el cliente almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al cliente almacenar en el búfer mensajes más grandes más rápidamente sin esperar a la contrapresión, pero puede aumentar el consumo de memoria. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Recursos adicionales
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el AddJsonProtocol método de extensión, que puede agregarse después AddSignalR en su métodoStartup.ConfigureServices
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerSettings de ese objeto es un objeto Json.NET JsonSerializerSettings
que puede utilizarse para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación de Json.NET.
Por ejemplo, para configurar el serializador para que utilice nombres de propiedades "PascalCase", en lugar de los nombres predeterminados en mayúsculas y minúsculas, utilice el siguiente código en Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
Las opciones pueden configurarse para todos los concentradores proporcionando un delegado de opciones a la AddSignalR
llamada en Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSignalR((configure) =>
{
var desiredTransports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
configure.MapHub<ChatHub>("/chathub", (options) =>
{
options.Transports = desiredTransports;
});
});
}
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
32 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer. Aumentar este valor permite que el servidor reciba mensajes de mayor tamaño, pero puede afectar negativamente al consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
TransportMaxBufferSize |
32 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer. Aumentar este valor permite al servidor enviar mensajes más grandes, pero puede afectar negativamente al consumo de memoria. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
Nota
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Existen opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente en el HubConnection
propio objeto:
Opción | Valor predeterminado | Descripción |
---|---|---|
ServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número al menos el doble del valor del servidor KeepAliveInterval para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Recursos adicionales
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el AddJsonProtocol método de extensión, que puede agregarse después AddSignalR en su métodoStartup.ConfigureServices
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerSettings de ese objeto es un objeto Json.NET JsonSerializerSettings
que puede utilizarse para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación de Json.NET.
Por ejemplo, para configurar el serializador para que utilice nombres de propiedades "PascalCase", en lugar de los nombres predeterminados en mayúsculas y minúsculas, utilice el siguiente código en Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ClientTimeoutInterval |
30 segundos | El servidor considera que el cliente está desconectado si no ha recibido ningún mensaje (incluido conexión persistente) en este intervalo. Podría tomar más tiempo que este intervalo de tiempo de espera para que el cliente sea marcado como desconectado debido a la forma en que esto se implementa. El valor recomendado es el doble KeepAliveInterval . |
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
Las opciones pueden configurarse para todos los concentradores proporcionando un delegado de opciones a la AddSignalR
llamada en Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSignalR((configure) =>
{
var desiredTransports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
configure.MapHub<ChatHub>("/chathub", (options) =>
{
options.Transports = desiredTransports;
});
});
}
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
32 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer. Aumentar este valor permite que el servidor reciba mensajes de mayor tamaño, pero puede afectar negativamente al consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
TransportMaxBufferSize |
32 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer. Aumentar este valor permite al servidor enviar mensajes más grandes, pero puede afectar negativamente al consumo de memoria. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
Nota
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
En esta versión del cliente Java, websockets es el único transporte disponible.
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Existen opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente en el HubConnection
propio objeto:
Opción | Valor predeterminado | Descripción |
---|---|---|
ServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número al menos el doble del valor del servidor KeepAliveInterval para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Determina el intervalo en el que el cliente envía mensajes ping. El envío de cualquier mensaje desde el cliente reinicia el temporizador al inicio del intervalo. Si el cliente no ha enviado ningún mensaje en el conjunto ClientTimeoutInterval en el servidor, el servidor considera que el cliente está desconectado. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Recursos adicionales
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el método de extensión AddJsonProtocol. AddJsonProtocol
puede agregarse después de AddSignalR en Startup.ConfigureServices
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerOptions de ese objeto es un System.Text.Json
JsonSerializerOptions objeto que se puede utilizar para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación System.Text.Json.
Por ejemplo, para configurar el serializador para que no cambie el tipo de letra de los nombres de las propiedades, en lugar de las mayúsculas y minúsculas por defecto, utilice el siguiente código en Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Cambiar a Newtonsoft.Json
Si necesita características de Newtonsoft.Json
que no son compatibles con System.Text.Json
, consulte Cambiar a Newtonsoft.Json
.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ClientTimeoutInterval |
30 segundos | El servidor considera que el cliente está desconectado si no ha recibido ningún mensaje (incluido conexión persistente) en este intervalo. Podría tomar más tiempo que este intervalo de tiempo de espera para que el cliente sea marcado como desconectado debido a la forma en que esto se implementa. El valor recomendado es el doble KeepAliveInterval . |
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
StreamBufferCapacity |
10 |
Número máximo de elementos que pueden almacenarse en el búfer para flujos de carga de clientes. Si se alcanza este límite, se bloquea el procesamiento de las invocaciones hasta que el servidor procese los elementos del flujo. |
MaximumReceiveMessageSize |
32 KB | Tamaño máximo de un único mensaje hub entrante. Aumentar el valor puede aumentar el riesgo de ataques por denegación de servicio (DoS). |
Las opciones pueden configurarse para todos los concentradores proporcionando un delegado de opciones a la AddSignalR
llamada en Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
});
});
}
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
32 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al servidor recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
TransportMaxBufferSize |
32 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al servidor almacenar en el búfer mensajes más grandes más rápidamente sin esperar la contrapresión, pero puede aumentar el consumo de memoria. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
En lugar de un valor LogLevel
, también puede proporcionar un valor string
que represente un nombre de nivel de registro. Esto es útil cuando se configura el registro SignalR en entornos en los que no se tiene acceso a las constantes LogLevel
.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
La siguiente tabla enumera los niveles de registro disponibles. El valor que proporcione establece configureLogging
el nivel mínimo de registro que se registrará. Se registrarán los mensajes registrados en este nivel o en los niveles indicados a continuación en la tabla.
String | LogLevel |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info o information |
LogLevel.Information |
warn o warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Nota:
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
En esta versión del cliente Java, websockets es el único transporte disponible.
En el cliente Java, el transporte se selecciona con el métodowithTransport
en el HttpHubConnectionBuilder
. El cliente Java utiliza por defecto el transporte WebSockets.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Nota:
El SignalR cliente Java aún no admite el transporte de reserva.
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Existen opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente en el HubConnection
propio objeto:
Opción | Valor predeterminado | Descripción |
---|---|---|
ServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número al menos el doble del valor del servidor KeepAliveInterval para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Determina el intervalo en el que el cliente envía mensajes ping. El envío de cualquier mensaje desde el cliente reinicia el temporizador al inicio del intervalo. Si el cliente no ha enviado ningún mensaje en el conjunto ClientTimeoutInterval en el servidor, el servidor considera que el cliente está desconectado. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Recursos adicionales
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el método de extensión AddJsonProtocol. AddJsonProtocol
puede agregarse después de AddSignalR en Startup.ConfigureServices
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerOptions de ese objeto es un System.Text.Json
JsonSerializerOptions objeto que se puede utilizar para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación System.Text.Json.
Por ejemplo, para configurar el serializador para que no cambie el tipo de letra de los nombres de las propiedades, en lugar de las mayúsculas y minúsculas por defecto, utilice el siguiente código en Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Cambiar a Newtonsoft.Json
Si necesita características de Newtonsoft.Json
que no son compatibles con System.Text.Json
, consulte Cambiar a Newtonsoft.Json
.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ClientTimeoutInterval |
30 segundos | El servidor considera que el cliente está desconectado si no ha recibido ningún mensaje (incluido conexión persistente) en este intervalo. Podría tomar más tiempo que este intervalo de tiempo de espera para que el cliente sea marcado como desconectado debido a la forma en que esto se implementa. El valor recomendado es el doble KeepAliveInterval . |
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
StreamBufferCapacity |
10 |
Número máximo de elementos que pueden almacenarse en el búfer para flujos de carga de clientes. Si se alcanza este límite, se bloquea el procesamiento de las invocaciones hasta que el servidor procese los elementos del flujo. |
MaximumReceiveMessageSize |
32 KB | Tamaño máximo de un único mensaje hub entrante. Aumentar el valor puede aumentar el riesgo de ataques por denegación de servicio (DoS). |
Las opciones pueden configurarse para todos los concentradores proporcionando un delegado de opciones a la AddSignalR
llamada en Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
});
});
}
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
32 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al servidor recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
TransportMaxBufferSize |
32 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al servidor almacenar en el búfer mensajes más grandes más rápidamente sin esperar la contrapresión, pero puede aumentar el consumo de memoria. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
MinimumProtocolVersion |
0 | Especifique la versión mínima del protocolo de negociación. Se utiliza para limitar los clientes a las versiones más recientes. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
En lugar de un valor LogLevel
, también puede proporcionar un valor string
que represente un nombre de nivel de registro. Esto es útil cuando se configura el registro SignalR en entornos en los que no se tiene acceso a las constantes LogLevel
.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
La siguiente tabla enumera los niveles de registro disponibles. El valor que proporcione establece configureLogging
el nivel mínimo de registro que se registrará. Se registrarán los mensajes registrados en este nivel o en los niveles indicados a continuación en la tabla.
String | LogLevel |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info o information |
LogLevel.Information |
warn o warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Nota:
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
En esta versión del cliente Java, websockets es el único transporte disponible.
En el cliente Java, el transporte se selecciona con el métodowithTransport
en el HttpHubConnectionBuilder
. El cliente Java utiliza por defecto el transporte WebSockets.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Nota:
El SignalR cliente Java aún no admite el transporte de reserva.
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Existen opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente en el HubConnection
propio objeto:
Opción | Valor predeterminado | Descripción |
---|---|---|
ServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número al menos el doble del valor del servidor KeepAliveInterval para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Determina el intervalo en el que el cliente envía mensajes ping. El envío de cualquier mensaje desde el cliente reinicia el temporizador al inicio del intervalo. Si el cliente no ha enviado ningún mensaje en el conjunto ClientTimeoutInterval en el servidor, el servidor considera que el cliente está desconectado. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Recursos adicionales
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el método de extensión AddJsonProtocol. AddJsonProtocol
puede agregarse después de AddSignalR en Startup.ConfigureServices
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerOptions de ese objeto es un System.Text.Json
JsonSerializerOptions objeto que se puede utilizar para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación System.Text.Json.
Por ejemplo, para configurar el serializador para que no cambie el tipo de letra de los nombres de las propiedades, en lugar de las mayúsculas y minúsculas por defecto, utilice el siguiente código en Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Cambiar a Newtonsoft.Json
Si necesita características de Newtonsoft.Json
que no son compatibles con System.Text.Json
, consulte Cambiar a Newtonsoft.Json
.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ClientTimeoutInterval |
30 segundos | El servidor considera que el cliente está desconectado si no ha recibido ningún mensaje (incluido conexión persistente) en este intervalo. Podría tomar más tiempo que este intervalo de tiempo de espera para que el cliente sea marcado como desconectado debido a la forma en que esto se implementa. El valor recomendado es el doble KeepAliveInterval . |
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
StreamBufferCapacity |
10 |
Número máximo de elementos que pueden almacenarse en el búfer para flujos de carga de clientes. Si se alcanza este límite, se bloquea el procesamiento de las invocaciones hasta que el servidor procese los elementos del flujo. |
MaximumReceiveMessageSize |
32 KB | Tamaño máximo de un único mensaje hub entrante. Aumentar el valor puede aumentar el riesgo de ataques por denegación de servicio (DoS). |
MaximumParallelInvocationsPerClient |
1 | El número máximo de métodos del hub que cada cliente puede llamar en paralelo antes de ponerse en cola. |
Las opciones pueden configurarse para todos los hubs proporcionando un delegado de opciones a la AddSignalR
llamada en Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
});
});
}
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
32 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al servidor recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
TransportMaxBufferSize |
32 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al servidor almacenar en el búfer mensajes más grandes más rápidamente sin esperar la contrapresión, pero puede aumentar el consumo de memoria. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
MinimumProtocolVersion |
0 | Especifique la versión mínima del protocolo de negociación. Se utiliza para limitar los clientes a las versiones más recientes. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
En lugar de un valor LogLevel
, también puede proporcionar un valor string
que represente un nombre de nivel de registro. Esto es útil cuando se configura el registro SignalR en entornos en los que no se tiene acceso a las constantes LogLevel
.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
La siguiente tabla enumera los niveles de registro disponibles. El valor que proporcione establece configureLogging
el nivel mínimo de registro que se registrará. Se registrarán los mensajes registrados en este nivel o en los niveles indicados a continuación en la tabla.
String | LogLevel |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info o information |
LogLevel.Information |
warn o warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Nota:
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
En esta versión del cliente Java, websockets es el único transporte disponible.
En el cliente Java, el transporte se selecciona con el métodowithTransport
en el HttpHubConnectionBuilder
. El cliente Java utiliza por defecto el transporte WebSockets.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Nota:
El SignalR cliente Java aún no admite el transporte de reserva.
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Existen opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente en el HubConnection
propio objeto:
Opción | Valor predeterminado | Descripción |
---|---|---|
ServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número al menos el doble del valor del servidor KeepAliveInterval para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Determina el intervalo en el que el cliente envía mensajes ping. El envío de cualquier mensaje desde el cliente reinicia el temporizador al inicio del intervalo. Si el cliente no ha enviado ningún mensaje en el conjunto ClientTimeoutInterval en el servidor, el servidor considera que el cliente está desconectado. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Recursos adicionales
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el método de extensión AddJsonProtocol. AddJsonProtocol
puede agregarse después de AddSignalR en Program.cs
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerOptions de ese objeto es un System.Text.Json
JsonSerializerOptions objeto que se puede utilizar para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación System.Text.Json.
Por ejemplo, para configurar el serializador para que no cambie el tipo de letra de los nombres de las propiedades, en lugar de las mayúsculas y minúsculas por defecto, utilice el siguiente código en Program.cs
:
builder.Services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Cambiar a Newtonsoft.Json
Si necesita características de Newtonsoft.Json
que no son compatibles con System.Text.Json
, consulte Cambiar a Newtonsoft.Json
.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ClientTimeoutInterval |
30 segundos | El servidor considera que el cliente está desconectado si no ha recibido ningún mensaje (incluido conexión persistente) en este intervalo. Podría tomar más tiempo que este intervalo de tiempo de espera para que el cliente sea marcado como desconectado debido a la forma en que esto se implementa. El valor recomendado es el doble KeepAliveInterval . |
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
StreamBufferCapacity |
10 |
Número máximo de elementos que pueden almacenarse en el búfer para flujos de carga de clientes. Si se alcanza este límite, se bloquea el procesamiento de las invocaciones hasta que el servidor procese los elementos del flujo. |
MaximumReceiveMessageSize |
32 KB | Tamaño máximo de un único mensaje hub entrante. Aumentar el valor puede aumentar el riesgo de ataques por denegación de servicio (DoS). |
MaximumParallelInvocationsPerClient |
1 | El número máximo de métodos del hub que cada cliente puede llamar en paralelo antes de ponerse en cola. |
Las opciones pueden configurarse para todos los hubs proporcionando un delegado de opciones a la AddSignalR
llamada en Program.cs
.
builder.Services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Program.cs
.
using Microsoft.AspNetCore.Http.Connections;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddSignalR();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
}
);
app.Run();
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
64 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al servidor recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
TransportMaxBufferSize |
64 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al servidor almacenar en el búfer mensajes más grandes más rápidamente sin esperar la contrapresión, pero puede aumentar el consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
MinimumProtocolVersion |
0 | Especifique la versión mínima del protocolo de negociación. Se utiliza para limitar los clientes a las versiones más recientes. |
CloseOnAuthenticationExpiration |
false | Establezca esta opción para activar el seguimiento de caducidad de autenticación, que cerrará las conexiones cuando caduque un token. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
En lugar de un valor LogLevel
, también puede proporcionar un valor string
que represente un nombre de nivel de registro. Esto es útil cuando se configura el registro SignalR en entornos en los que no se tiene acceso a las constantes LogLevel
.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
La siguiente tabla enumera los niveles de registro disponibles. El valor que proporcione establece configureLogging
el nivel mínimo de registro que se registrará. Se registrarán los mensajes registrados en este nivel o en los niveles indicados a continuación en la tabla.
String | LogLevel |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info o information |
LogLevel.Information |
warn o warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Nota:
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
En esta versión del cliente Java, websockets es el único transporte disponible.
En el cliente Java, el transporte se selecciona con el métodowithTransport
en el HttpHubConnectionBuilder
. El cliente Java utiliza por defecto el transporte WebSockets.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Nota:
El SignalR cliente Java aún no admite el transporte de reserva.
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Existen opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente en el HubConnection
propio objeto:
Opción | Valor predeterminado | Descripción |
---|---|---|
ServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número al menos el doble del valor del servidor KeepAliveInterval para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Determina el intervalo en el que el cliente envía mensajes ping. El envío de cualquier mensaje desde el cliente reinicia el temporizador al inicio del intervalo. Si el cliente no ha enviado ningún mensaje en el conjunto ClientTimeoutInterval en el servidor, el servidor considera que el cliente está desconectado. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
ApplicationMaxBufferSize |
1 MB | El número máximo de bytes recibidos del servidor que el cliente almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al cliente recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
TransportMaxBufferSize |
1 MB | El número máximo de bytes enviados por la aplicación de usuario que el cliente almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al cliente almacenar en el búfer mensajes más grandes más rápidamente sin esperar a la contrapresión, pero puede aumentar el consumo de memoria. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Recursos adicionales
JSOpciones de serialización ON/MessagePack
ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.
JSLa serialización ON puede configurarse en el servidor utilizando el método de extensión AddJsonProtocol. AddJsonProtocol
puede agregarse después de AddSignalR en Startup.ConfigureServices
. El método AddJsonProtocol
toma un delegado que recibe un options
objeto. La propiedad PayloadSerializerOptions de ese objeto es un System.Text.Json
JsonSerializerOptions objeto que se puede utilizar para configurar la serialización de argumentos y valores de retorno. Para más información, consulte la documentación System.Text.Json.
Por ejemplo, para configurar el serializador para que no cambie el tipo de letra de los nombres de las propiedades, en lugar de las mayúsculas y minúsculas por defecto, utilice el siguiente código en Program.cs
:
builder.Services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
En el cliente .NET, AddJsonProtocol
existe el mismo método de extensión en HubConnectionBuilder. El espacio de nombres Microsoft.Extensions.DependencyInjection
debe ser importado para resolver el método de extensión:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Nota:
En este momento no es posible configurar la serialización JSON en el cliente JavaScript.
Cambiar a Newtonsoft.Json
Si necesita características de Newtonsoft.Json
que no son compatibles con System.Text.Json
, consulte Cambiar a Newtonsoft.Json
.
Opciones de serialización de MessagePack
La serialización de MessagePack puede configurarse proporcionando un delegado a la llamada AddMessagePackProtocol. Consulte MessagePack en SignalR para obtener más detalles.
Nota
Por el momento no es posible configurar la serialización de MessagePack en el cliente JavaScript.
Configurar las opciones del servidor
En la tabla siguiente se describen las opciones para configurar los hubsSignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ClientTimeoutInterval |
30 segundos | El servidor considera que el cliente está desconectado si no ha recibido ningún mensaje (incluido conexión persistente) en este intervalo. Podría tomar más tiempo que este intervalo de tiempo de espera para que el cliente sea marcado como desconectado debido a la forma en que esto se implementa. El valor recomendado es el doble KeepAliveInterval . |
HandshakeTimeout |
15 segundos | Si el cliente no envía un mensaje inicial en este protocolo de enlace, la conexión se cierra. Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Si el servidor no ha enviado ningún mensaje en este intervalo, se envía automáticamente un mensaje ping para mantener la conexión abierta. Al cambiar KeepAliveInterval , cambie el ServerTimeout o serverTimeoutInMilliseconds ajuste en el cliente. El valor recomendado ServerTimeout oserverTimeoutInMilliseconds es el doble KeepAliveInterval . |
SupportedProtocols |
Todos los protocolos instalados | Protocolos admitidos por este hub. Por defecto, se permiten todos los protocolos registrados en el servidor. Los protocolos se pueden eliminar de esta lista para desactivar protocolos específicos para hubs individuales. |
EnableDetailedErrors |
false |
Si true , se devuelven mensajes de excepción detallados a los clientes cuando se lanza una excepción en un método hub. Por defecto es false porque estos mensajes de excepción pueden contener información confidencial. |
StreamBufferCapacity |
10 |
Número máximo de elementos que pueden almacenarse en el búfer para flujos de carga de clientes. Si se alcanza este límite, se bloquea el procesamiento de las invocaciones hasta que el servidor procese los elementos del flujo. |
MaximumReceiveMessageSize |
32 KB | Tamaño máximo de un único mensaje hub entrante. Aumentar el valor puede aumentar el riesgo de ataques por denegación de servicio (DoS). |
MaximumParallelInvocationsPerClient |
1 | El número máximo de métodos del hub que cada cliente puede llamar en paralelo antes de ponerse en cola. |
DisableImplicitFromServicesParameters |
false |
Los argumentos del método hub se resolverán a partir de DI si es posible. |
Las opciones pueden configurarse para todos los hubs proporcionando un delegado de opciones a la AddSignalR
llamada en Program.cs
.
builder.Services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
Las opciones para un único hub anulan las opciones globales proporcionadas en AddSignalR
y pueden configurarse mediante AddHubOptions:
builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Opciones avanzadas de configuración HTTP
Utilice HttpConnectionDispatcherOptions
para configurar opciones avanzadas relacionadas con los transportes y la administración de búferes de memoria. Estas opciones se configuran pasando un delegado a MapHub en Program.cs
.
using Microsoft.AspNetCore.Http.Connections;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddSignalR();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
}
);
app.Run();
La siguiente tabla describe las opciones para configurar las opciones HTTP avanzadas de ASP.NET Core SignalR:
Opción | Valor predeterminado | Descripción |
---|---|---|
ApplicationMaxBufferSize |
64 KB | El número máximo de bytes recibidos del cliente que el servidor almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al servidor recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
TransportMaxBufferSize |
64 KB | El número máximo de bytes enviados por la aplicación que el servidor almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al servidor almacenar en el búfer mensajes más grandes más rápidamente sin esperar la contrapresión, pero puede aumentar el consumo de memoria. |
AuthorizationData |
Datos recogidos automáticamente de los Authorize atributos aplicados a la clase Hub. |
Lista de IAuthorizeData objetos utilizados para determinar si un cliente está autorizado a conectarse al hub. |
Transports |
Todos los transportes están habilitados. | Enumeración de valores HttpTransportType que pueden restringir los transportes que un cliente puede utilizar para conectarse. |
LongPolling |
Véase a continuación. | Opciones adicionales específicas para el transporte de sondeo largo. |
WebSockets |
Véase a continuación. | Opciones adicionales específicas del transporte WebSockets. |
MinimumProtocolVersion |
0 | Especifique la versión mínima del protocolo de negociación. Se utiliza para limitar los clientes a las versiones más recientes. |
CloseOnAuthenticationExpiration |
false | Establezca esta opción para activar el seguimiento de caducidad de autenticación, que cerrará las conexiones cuando caduque un token. |
El transporte de sondeo largo tiene opciones adicionales que pueden configurarse utilizando la propiedad: LongPolling
Opción | Valor predeterminado | Descripción |
---|---|---|
PollTimeout |
90 segundos | La cantidad máxima de tiempo que el servidor espera para enviar un mensaje al cliente antes de finalizar una única solicitud de sondeo. La disminución de este valor hace que el cliente emita nuevas solicitudes de sondeo con mayor frecuencia. |
El transporte WebSocket tiene opciones adicionales que se pueden configurar utilizando la propiedad WebSockets
:
Opción | Valor predeterminado | Descripción |
---|---|---|
CloseTimeout |
5 segundos | Después de que el servidor se cierre, si el cliente no lo hace en este intervalo de tiempo, la conexión finaliza. |
SubProtocolSelector |
null |
Un delegado que se puede utilizar para establecer el encabezado Sec-WebSocket-Protocol a un valor personalizado. El delegado recibe los valores solicitados por el cliente como entrada y se espera que devuelva el valor deseado. |
Configuración de opciones de cliente
Las opciones del cliente pueden configurarse en el tipo HubConnectionBuilder
(disponible en los clientes .NET y JavaScript). También está disponible en el cliente Java, pero la subclase HttpHubConnectionBuilder
es la que contiene las opciones de configuración del constructor, así como en el mismo HubConnection
.
registro
El registro se configura en el cliente .NET mediante el método ConfigureLogging
. Los proveedores de registro y los filtros pueden registrarse del mismo modo que en el servidor. Consulte la documentación sobre Registro en ASP.NET Core para obtener más información.
Nota
Para registrar proveedores de registro, debe instalar los paquetes necesarios. Consulte la sección Proveedores de registro incorporados de la documentación para obtener una lista completa.
Por ejemplo, para activar el registro de la consola, instale el paquete NuGet Microsoft.Extensions.Logging.Console
. Llamar al método de ampliación AddConsole
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
En el cliente JavaScript existe un método similar configureLogging
. Proporcione un valor LogLevel
que indique el nivel mínimo de mensajes de registro a producir. Los registros se escriben en la ventana de la consola del explorador.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
En lugar de un valor LogLevel
, también puede proporcionar un valor string
que represente un nombre de nivel de registro. Esto es útil cuando se configura el registro SignalR en entornos en los que no se tiene acceso a las constantes LogLevel
.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
La siguiente tabla enumera los niveles de registro disponibles. El valor que proporcione establece configureLogging
el nivel mínimo de registro que se registrará. Se registrarán los mensajes registrados en este nivel o en los niveles indicados a continuación en la tabla.
String | LogLevel |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info o information |
LogLevel.Information |
warn o warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Nota:
Para desactivar completamente el registro, especifique signalR.LogLevel.None
en el método configureLogging
.
Para más información sobre el registro, consulte la SignalR Documentación de diagnósticos.
El SignalR cliente Java utiliza la biblioteca SLF4J para el registro. Se trata de una API de registro de alto nivel que permite a los usuarios de la biblioteca elegir su propia implementación de registro específica mediante la incorporación de una dependencia de registro específica. El siguiente fragmento de código muestra cómo utilizar java.util.logging
con el cliente Java SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Si no configura el registro en sus dependencias, SLF4J carga por defecto un registrador de no-operación con el siguiente mensaje de advertencia:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Esto se puede ignorar.
Configurar los transportes permitidos
Los transportes utilizados por SignalR se pueden configurar en la llamada WithUrl
(withUrl
en JavaScript). Se puede utilizar un bitwise-OR de los valores de HttpTransportType
para restringir el cliente para que solo utilice los transportes especificados. Todos los transportes están habilitados de forma predeterminada.
Por ejemplo, para deshabilitar el transporte Server-Sent Events, pero permitir conexiones WebSockets y Sondeo largo:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
En el cliente JavaScript, los transportes se configuran estableciendo el campo transport
en el objeto de opciones proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
En esta versión del cliente Java, websockets es el único transporte disponible.
En el cliente Java, el transporte se selecciona con el métodowithTransport
en el HttpHubConnectionBuilder
. El cliente Java utiliza por defecto el transporte WebSockets.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Nota:
El SignalR cliente Java aún no admite el transporte de reserva.
Configurar la autentificación de portador
Para proporcionar datos de autenticación junto con las solicitudes SignalR, utilice la opción AccessTokenProvider
(accessTokenFactory
en JavaScript) para especificar una función que devuelva el token de acceso deseado. En el cliente .NET, este token de acceso se pasa como un token HTTP "Autenticación de portador" (utilizando un encabezado Authorization
con un tipo de Bearer
). En el cliente JavaScript, el token de acceso se utiliza como token de portador, excepto en algunos casos en los que las API del navegador restringen la capacidad de aplicar encabezados (concretamente, en las solicitudes de eventos enviados por servidor y WebSockets). En estos casos, el token de acceso se proporciona como un valor de cadena de consulta access_token
.
En el cliente .NET, la opción AccessTokenProvider
puede especificarse utilizando el delegado de opciones en WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
En el cliente JavaScript, el token de acceso se configura estableciendo el campo accessTokenFactory
en el objeto opciones en withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
En el SignalR cliente Java, puede configurar un token de portador para utilizarlo en la autenticación proporcionando una fábrica de tokens de acceso al HttpHubConnectionBuilder. Usar withAccessTokenFactory para proporcionar una RxJava Cadena<Única>. Con una llamada a Single.defer, puede escribir lógica para producir tokens de acceso para su cliente.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Configurar las opciones de tiempo de espera y conexión persistente
Existen opciones adicionales para configurar el tiempo de espera y el comportamiento de la conexión persistente en el HubConnection
propio objeto:
Opción | Valor predeterminado | Descripción |
---|---|---|
ServerTimeout |
30 segundos (30 000 milisegundos) | Tiempo de espera para la actividad del servidor. Si el servidor no ha enviado un mensaje en este intervalo, el cliente considera que el servidor está desconectado y activa el evento Closed (onclose en JavaScript). Este valor debe ser lo suficientemente grande para que un mensaje ping sea enviado desde el servidor y recibido por el cliente dentro del intervalo de tiempo de espera. El valor recomendado es un número al menos el doble del valor del servidor KeepAliveInterval para dar tiempo a que lleguen los pings. |
HandshakeTimeout |
15 segundos | Tiempo de espera para el protocolo de enlace inicial del servidor. Si el servidor no envía una respuesta de protocolo de enlace en este intervalo, el cliente cancela el protocolo de enlace y desencadena el Closed evento (onclose en JavaScript). Se trata de una configuración avanzada que solo debería modificarse si se están produciendo errores de tiempo de espera de protocolo de enlace debido a una latencia de red grave. Para más detalles sobre el proceso de protocolo de enlace, consulte la SignalR Especificación del Protocolo de hub. |
KeepAliveInterval |
15 segundos | Determina el intervalo en el que el cliente envía mensajes ping. El envío de cualquier mensaje desde el cliente reinicia el temporizador al inicio del intervalo. Si el cliente no ha enviado ningún mensaje en el conjunto ClientTimeoutInterval en el servidor, el servidor considera que el cliente está desconectado. |
En el Cliente .NET, los valores de tiempo de espera se especifican como valores TimeSpan
.
Configuración de opciones adicionales
Pueden configurarse opciones adicionales en el método WithUrl
(withUrl
en JavaScript) en HubConnectionBuilder
o en las distintas API de configuración en el HttpHubConnectionBuilder
en el cliente Java:
Opción .NET | Valor predeterminado | Descripción |
---|---|---|
AccessTokenProvider |
null |
Función que devuelve una cadena que se proporciona como token de autenticación de portador en las peticiones HTTP. |
SkipNegotiation |
false |
Seleccione esta opción en true para omitir el paso de negociación. Solo se admite cuando el transporte WebSockets es el único transporte habilitado. Esta configuración no puede activarse cuando se utiliza el servicio SignalRAzure. |
ClientCertificates |
Vacío | Una colección de certificados TLS a enviar para autenticar peticiones. |
Cookies |
Vacío | Una colección de cookie HTTP para enviar con cada petición HTTP. |
Credentials |
Vacío | Credenciales a enviar con cada petición HTTP. |
CloseTimeout |
5 segundos | Solo WebSockets. La cantidad máxima de tiempo que el cliente espera después del cierre para que el servidor acuse recibo de la solicitud de cierre. Si el servidor no acusa recibo del cierre en ese tiempo, el cliente se desconecta. |
Headers |
Vacío | Un mapa de encabezados HTTP adicionales para enviar con cada solicitud HTTP. |
HttpMessageHandlerFactory |
null |
Un delegado que se puede utilizar para configurar o reemplazar el HttpMessageHandler utilizado para enviar solicitudes HTTP. No se utiliza para conexiones WebSocket. Este delegado debe devolver un valor no nulo, y recibe el valor por defecto como parámetro. Modifica la configuración de ese valor por defecto y lo devuelve, o devuelve una nueva instanciaHttpMessageHandler . Al reemplazar el controlador asegúrese de copiar la configuración que desea mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como Cookie y encabezados) no se aplicarán al nuevo controlador. |
Proxy |
null |
Un proxy HTTP a utilizar cuando se envían peticiones HTTP. |
UseDefaultCredentials |
false |
Establezca este booleano para enviar las credenciales por defecto para peticiones HTTP y WebSockets. Esto permite el uso de la autenticación de Windows. |
WebSocketConfiguration |
null |
Un delegado que se puede utilizar para configurar opciones adicionales de WebSocket. Recibe una instancia de ClientWebSocketOptions que se puede utilizar para configurar las opciones. |
ApplicationMaxBufferSize |
1 MB | El número máximo de bytes recibidos del servidor que el cliente almacena en búfer antes de aplicar contrapresión. Aumentar este valor permite al cliente recibir mensajes más grandes más rápidamente sin aplicar contrapresión, pero puede aumentar el consumo de memoria. |
TransportMaxBufferSize |
1 MB | El número máximo de bytes enviados por la aplicación de usuario que el cliente almacena en búfer antes de observar la contrapresión. Aumentar este valor permite al cliente almacenar en el búfer mensajes más grandes más rápidamente sin esperar a la contrapresión, pero puede aumentar el consumo de memoria. |
En el cliente .NET, estas opciones pueden modificarse mediante el delegado de opciones proporcionado a WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
En el Cliente JavaScript, estas opciones pueden proporcionarse en un objeto JavaScript proporcionado a withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
En el cliente Java, estas opciones pueden configurarse con los métodos en elHttpHubConnectionBuilder
devuelto de la función HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();