Compartir a través de


Configuración de SignalR en ASP.NET Core

En este artículo se describe la configuración de SignalR en ASP.NET Core.

Para obtener una guía de BlazorSignalR, que se agregue a la guía de este artículo o la reemplace, consulta la guía de ASP.NET Core BlazorSignalR.

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON 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.JsonJsonSerializerOptions 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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON puede configurarse en el servidor utilizando el AddJsonProtocol método de extensión, que puede agregarse después AddSignalR en tu método Startup.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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON puede configurarse en el servidor utilizando el AddJsonProtocol método de extensión, que puede agregarse después AddSignalR en tu método Startup.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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON 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.JsonJsonSerializerOptions 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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON 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.JsonJsonSerializerOptions 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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON 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.JsonJsonSerializerOptions 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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON 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.JsonJsonSerializerOptions 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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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

Opciones de serialización JSON/MessagePack

ASP.NET Core SignalR admite dos protocolos para codificar mensajes: JSON y MessagePack. Cada protocolo tiene opciones de configuración de serialización.

La serialización JSON 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.JsonJsonSerializerOptions 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 (withUrlen 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 (accessTokenFactoryen 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 (oncloseen 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 cookies 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úrate de copiar la configuración que deseas mantener del controlador proporcionado, de lo contrario, las opciones configuradas (como cookies 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