C ASP.NET Core SignalR

Cet article traite de la configuration SignalR ASP.NET Core.

Pour obtenir des conseils sur BlazorSignalR, en complément ou en remplacement des instructions de cet article, consultez Conseils sur BlazorSignalR ASP.NET Core.

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol. AddJsonProtocol peut être ajouté après AddSignalR ou Startup.ConfigureServices. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerOptions sur cet objet est un objet System.Text.JsonJsonSerializerOptions qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs retournées. Pour plus d’informations, consultez la documentation de System.Text.Json.

Par exemple, pour configurer le sérialiseur de manière à ne pas modifier la casse des noms de propriétés, plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Program.cs :

builder.Services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Basculer vers Newtonsoft.Json

Si vous avez besoin de fonctionnalités de Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, consultez Basculer vers Newtonsoft.Json.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
ClientTimeoutInterval 30 secondes Le serveur considère que le client est déconnecté s’il n’a pas reçu de message (y compris keep-alive) au cours de cet intervalle. Cela peut prendre plus de temps que cet intervalle de délai d’attente pour que le client soit marqué déconnecté en raison son implémentation. La valeur recommandée est le double de la valeur KeepAliveInterval.
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.
StreamBufferCapacity 10 Nombre maximal d’éléments pouvant être mis en mémoire tampon pour les flux de chargement client. Si cette limite est atteinte, le traitement des appels est bloqué jusqu’à ce que le serveur traite les éléments de flux.
MaximumReceiveMessageSize 32 Ko Taille maximale d’un message hub entrant unique. L’augmentation de la valeur peut accroître le risque d’attaques par déni de service (DoS).
MaximumParallelInvocationsPerClient 1 Nombre maximal de méthodes hub que chaque client peut appeler en parallèle avant la mise en file d’attente.
DisableImplicitFromServicesParameters false Les arguments de la méthode hub sont résolus à partir de l’injection de dépendances si possible.

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Program.cs.

 builder.Services.AddSignalR(hubOptions =>
 {
     hubOptions.EnableDetailedErrors = true;
     hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
 });

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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();

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 64 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au serveur de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
TransportMaxBufferSize 64 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au serveur de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.
MinimumProtocolVersion 0 Spécifiez la version minimale du protocole de négociation. Cela permet de limiter les clients aux versions plus récentes.
CloseOnAuthenticationExpiration false Définissez cette option pour activer le suivi d’expiration de l’authentification qui ferme les connexions à l’expiration d’un jeton.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Au lieu d’une valeur LogLevel, vous pouvez également fournir une valeur string représentant un nom de niveau journal. Cela est utile lors de la configuration de la journalisation SignalR dans des environnements où vous n’avez pas accès aux constantes LogLevel.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

Le tableau suivant répertorie les niveaux de journal disponibles. La valeur que vous fournissez pour configureLogging définit le niveau de journal minimal qui sera journalisé. Les messages enregistrés à ce niveau, ou les niveaux répertoriés après celui-ci dans la table, seront consignés.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info ou information LogLevel.Information
warn ou warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Remarque

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Dans cette version du client Java, Websockets est le seul transport disponible.

Dans le client Java, le transport est sélectionné avec la méthode withTransport sur le HttpHubConnectionBuilder. Le client Java utilise par défaut le transport WebSockets.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Notes

Le client Java SignalR ne prend pas encore en charge le transport de secours.

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Options supplémentaires pour configurer le comportement de délai d’expiration et keep-alive :

Option Valeur par défaut Description
WithServerTimeout 30 secondes (30 000 millisecondes) Délai d’attente pour l’activité du serveur, défini directement sur HubConnectionBuilder. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur de l’intervalle keep-alive (WithKeepAliveInterval) du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur, disponible sur l’objet HubConnection lui-même. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
WithKeepAliveInterval 15 secondes Détermine l’intervalle auquel le client envoie des messages ping et est défini directement sur HubConnectionBuilder. Ce paramètre permet au serveur de détecter les déconnexions matérielles, par exemple lorsqu’un client débranche son ordinateur du réseau. L’envoi d’un message à partir du client réinitialise le minuteur au début de l’intervalle. Si le client n’a pas envoyé de message dans le ClientTimeoutInterval défini sur le serveur, le serveur considère le client déconnecté.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

L’exemple suivant montre des valeurs qui sont deux fois plus élevées que les valeurs par défaut :

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();

Configurer la reconnexion avec état

La reconnexion avec état de SignalR réduit le temps d’arrêt perçu des clients en cas de déconnexion temporaire de leur connexion réseau, par exemple lors du basculement de connexions réseau ou d’une brève perte temporaire d’accès.

La reconnexion avec état permet cela en :

  • Mettant temporairement en mémoire tampon des données sur le serveur et le client.
  • Accusant réception des messages reçus (procédure « ACK-ing ») par le serveur et le client.
  • Reconnaissant lorsqu’une connexion est active et en relisant des messages qui ont pu être envoyés pendant l’arrêt de la connexion.

La reconnexion avec état est disponible dans ASP.NET Core 8.0 et versions ultérieures.

Optez pour la reconnexion avec état au point de terminaison du hub de serveur et au client :

  • Mettez à jour la configuration du point de terminaison du hub de serveur pour activer l’option AllowStatefulReconnects :

    app.MapHub<MyHub>("/hubName", options =>
    {
        options.AllowStatefulReconnects = true;
    });
    

    Si vous le souhaitez, la taille maximale de la mémoire tampon en octets autorisée par le serveur peut être définie globalement ou pour un hub spécifique avec l’option StatefulReconnectBufferSize :

    Option StatefulReconnectBufferSize définie globalement :

    builder.AddSignalR(o => o.StatefulReconnectBufferSize = 1000);
    

    Option StatefulReconnectBufferSize définie pour un hub spécifique :

    builder.AddSignalR().AddHubOptions<MyHub>(o => o.StatefulReconnectBufferSize = 1000);
    

    L’option StatefulReconnectBufferSize est facultative avec une valeur par défaut de 100 000 octets.

  • Mettez à jour le code client JavaScript ou TypeScript pour activer l’option withStatefulReconnect :

    const builder = new signalR.HubConnectionBuilder()
      .withUrl("/hubname")
      .withStatefulReconnect({ bufferSize: 1000 });  // Optional, defaults to 100,000
    const connection = builder.build();
    

    L’option bufferSize est facultative avec une valeur par défaut de 100 000 octets.

  • Mettez à jour le code client .NET pour activer l’option WithStatefulReconnect :

      var builder = new HubConnectionBuilder()
          .WithUrl("<hub url>")
          .WithStatefulReconnect();
      builder.Services.Configure<HubConnectionOptions>(o => o.StatefulReconnectBufferSize = 1000);
      var hubConnection = builder.Build();
    

    L’option StatefulReconnectBufferSize est facultative avec une valeur par défaut de 100 000 octets.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.
ApplicationMaxBufferSize 1 Mo Nombre maximal d’octets reçus du serveur que le client met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au client de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
TransportMaxBufferSize 1 Mo Nombre maximal d’octets envoyés par l’application utilisateur que le client met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au client de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à 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();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à 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();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol, qui peut être ajoutée après AddSignalR dans votre méthode Startup.ConfigureServices. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerSettings sur cet objet est un objet JsonSerializerSettings Json.NET qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs renvoyées. Pour plus d’informations, voir la documentation sur Json.NET.

Par exemple, pour configurer le sérialiseur de manière à utiliser les noms de propriétés « PascalCase », plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Startup.ConfigureServices :

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Startup.ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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;
        });
    });
}

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 32 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon. L’augmentation de cette valeur permet au serveur de recevoir des messages plus volumineux, mais peut avoir un impact négatif sur la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
TransportMaxBufferSize 32 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon. L’augmentation de cette valeur permet au serveur d’envoyer des messages plus volumineux, mais peut avoir un impact négatif sur la consommation de mémoire.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Notes

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Des options supplémentaires pour configurer le délai d’expiration et le comportement keep-alive sont disponibles sur l’objet HubConnection lui-même :

Option Valeur par défaut Description
ServerTimeout 30 secondes (30 000 millisecondes) Délai d’expiration d’activité du serveur. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur KeepAliveInterval du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol, qui peut être ajoutée après AddSignalR dans votre méthode Startup.ConfigureServices. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerSettings sur cet objet est un objet JsonSerializerSettings Json.NET qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs renvoyées. Pour plus d’informations, voir la documentation sur Json.NET.

Par exemple, pour configurer le sérialiseur de manière à utiliser les noms de propriétés « PascalCase », plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Startup.ConfigureServices :

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
ClientTimeoutInterval 30 secondes Le serveur considère que le client est déconnecté s’il n’a pas reçu de message (y compris keep-alive) au cours de cet intervalle. Cela peut prendre plus de temps que cet intervalle de délai d’attente pour que le client soit marqué déconnecté en raison son implémentation. La valeur recommandée est le double de la valeur KeepAliveInterval.
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Startup.ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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;
        });
    });
}

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 32 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon. L’augmentation de cette valeur permet au serveur de recevoir des messages plus volumineux, mais peut avoir un impact négatif sur la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
TransportMaxBufferSize 32 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon. L’augmentation de cette valeur permet au serveur d’envoyer des messages plus volumineux, mais peut avoir un impact négatif sur la consommation de mémoire.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Notes

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Dans cette version du client Java, Websockets est le seul transport disponible.

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Des options supplémentaires pour configurer le délai d’expiration et le comportement keep-alive sont disponibles sur l’objet HubConnection lui-même :

Option Valeur par défaut Description
ServerTimeout 30 secondes (30 000 millisecondes) Délai d’expiration d’activité du serveur. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur KeepAliveInterval du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Détermine l’intervalle auquel le client envoie des messages ping. L’envoi d’un message à partir du client réinitialise le minuteur au début de l’intervalle. Si le client n’a pas envoyé de message dans le ClientTimeoutInterval défini sur le serveur, le serveur considère le client déconnecté.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol. AddJsonProtocol peut être ajouté après AddSignalR ou Startup.ConfigureServices. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerOptions sur cet objet est un objet System.Text.JsonJsonSerializerOptions qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs retournées. Pour plus d’informations, consultez la documentation de System.Text.Json.

Par exemple, pour configurer le sérialiseur de manière à ne pas modifier la casse des noms de propriétés, plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Startup.ConfigureServices :

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Basculer vers Newtonsoft.Json

Si vous avez besoin de fonctionnalités de Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, consultez Basculer vers Newtonsoft.Json.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
ClientTimeoutInterval 30 secondes Le serveur considère que le client est déconnecté s’il n’a pas reçu de message (y compris keep-alive) au cours de cet intervalle. Cela peut prendre plus de temps que cet intervalle de délai d’attente pour que le client soit marqué déconnecté en raison son implémentation. La valeur recommandée est le double de la valeur KeepAliveInterval.
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.
StreamBufferCapacity 10 Nombre maximal d’éléments pouvant être mis en mémoire tampon pour les flux de chargement client. Si cette limite est atteinte, le traitement des appels est bloqué jusqu’à ce que le serveur traite les éléments de flux.
MaximumReceiveMessageSize 32 Ko Taille maximale d’un message hub entrant unique. L’augmentation de la valeur peut augmenter le risque d’attaques par déni de service (DoS).

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Startup.ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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;
        });
    });
}

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 32 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au serveur de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
TransportMaxBufferSize 32 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au serveur de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Au lieu d’une valeur LogLevel, vous pouvez également fournir une valeur string représentant un nom de niveau journal. Cela est utile lors de la configuration de la journalisation SignalR dans des environnements où vous n’avez pas accès aux constantes LogLevel.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

Le tableau suivant répertorie les niveaux de journal disponibles. La valeur que vous fournissez pour configureLogging définit le niveau de journal minimal qui sera journalisé. Les messages enregistrés à ce niveau, ou les niveaux répertoriés après celui-ci dans la table, seront consignés.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info ou information LogLevel.Information
warn ou warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Remarque

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Dans cette version du client Java, Websockets est le seul transport disponible.

Dans le client Java, le transport est sélectionné avec la méthode withTransport sur le HttpHubConnectionBuilder. Le client Java utilise par défaut le transport WebSockets.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Notes

Le client Java SignalR ne prend pas encore en charge le transport de secours.

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Des options supplémentaires pour configurer le délai d’expiration et le comportement keep-alive sont disponibles sur l’objet HubConnection lui-même :

Option Valeur par défaut Description
ServerTimeout 30 secondes (30 000 millisecondes) Délai d’expiration d’activité du serveur. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur KeepAliveInterval du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Détermine l’intervalle auquel le client envoie des messages ping. L’envoi d’un message à partir du client réinitialise le minuteur au début de l’intervalle. Si le client n’a pas envoyé de message dans le ClientTimeoutInterval défini sur le serveur, le serveur considère le client déconnecté.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol. AddJsonProtocol peut être ajouté après AddSignalR ou Startup.ConfigureServices. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerOptions sur cet objet est un objet System.Text.JsonJsonSerializerOptions qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs retournées. Pour plus d’informations, consultez la documentation de System.Text.Json.

Par exemple, pour configurer le sérialiseur de manière à ne pas modifier la casse des noms de propriétés, plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Startup.ConfigureServices :

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Basculer vers Newtonsoft.Json

Si vous avez besoin de fonctionnalités de Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, consultez Basculer vers Newtonsoft.Json.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
ClientTimeoutInterval 30 secondes Le serveur considère que le client est déconnecté s’il n’a pas reçu de message (y compris keep-alive) au cours de cet intervalle. Cela peut prendre plus de temps que cet intervalle de délai d’attente pour que le client soit marqué déconnecté en raison son implémentation. La valeur recommandée est le double de la valeur KeepAliveInterval.
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.
StreamBufferCapacity 10 Nombre maximal d’éléments pouvant être mis en mémoire tampon pour les flux de chargement client. Si cette limite est atteinte, le traitement des appels est bloqué jusqu’à ce que le serveur traite les éléments de flux.
MaximumReceiveMessageSize 32 Ko Taille maximale d’un message hub entrant unique. L’augmentation de la valeur peut augmenter le risque d’attaques par déni de service (DoS).

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Startup.ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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;
        });
    });
}

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 32 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au serveur de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
TransportMaxBufferSize 32 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au serveur de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.
MinimumProtocolVersion 0 Spécifiez la version minimale du protocole de négociation. Cela permet de limiter les clients aux versions plus récentes.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Au lieu d’une valeur LogLevel, vous pouvez également fournir une valeur string représentant un nom de niveau journal. Cela est utile lors de la configuration de la journalisation SignalR dans des environnements où vous n’avez pas accès aux constantes LogLevel.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

Le tableau suivant répertorie les niveaux de journal disponibles. La valeur que vous fournissez pour configureLogging définit le niveau de journal minimal qui sera journalisé. Les messages enregistrés à ce niveau, ou les niveaux répertoriés après celui-ci dans la table, seront consignés.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info ou information LogLevel.Information
warn ou warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Remarque

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Dans cette version du client Java, Websockets est le seul transport disponible.

Dans le client Java, le transport est sélectionné avec la méthode withTransport sur le HttpHubConnectionBuilder. Le client Java utilise par défaut le transport WebSockets.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Notes

Le client Java SignalR ne prend pas encore en charge le transport de secours.

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Des options supplémentaires pour configurer le délai d’expiration et le comportement keep-alive sont disponibles sur l’objet HubConnection lui-même :

Option Valeur par défaut Description
ServerTimeout 30 secondes (30 000 millisecondes) Délai d’expiration d’activité du serveur. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur KeepAliveInterval du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Détermine l’intervalle auquel le client envoie des messages ping. L’envoi d’un message à partir du client réinitialise le minuteur au début de l’intervalle. Si le client n’a pas envoyé de message dans le ClientTimeoutInterval défini sur le serveur, le serveur considère le client déconnecté.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol. AddJsonProtocol peut être ajouté après AddSignalR ou Startup.ConfigureServices. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerOptions sur cet objet est un objet System.Text.JsonJsonSerializerOptions qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs retournées. Pour plus d’informations, consultez la documentation de System.Text.Json.

Par exemple, pour configurer le sérialiseur de manière à ne pas modifier la casse des noms de propriétés, plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Startup.ConfigureServices :

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Basculer vers Newtonsoft.Json

Si vous avez besoin de fonctionnalités de Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, consultez Basculer vers Newtonsoft.Json.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
ClientTimeoutInterval 30 secondes Le serveur considère que le client est déconnecté s’il n’a pas reçu de message (y compris keep-alive) au cours de cet intervalle. Cela peut prendre plus de temps que cet intervalle de délai d’attente pour que le client soit marqué déconnecté en raison son implémentation. La valeur recommandée est le double de la valeur KeepAliveInterval.
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.
StreamBufferCapacity 10 Nombre maximal d’éléments pouvant être mis en mémoire tampon pour les flux de chargement client. Si cette limite est atteinte, le traitement des appels est bloqué jusqu’à ce que le serveur traite les éléments de flux.
MaximumReceiveMessageSize 32 Ko Taille maximale d’un message hub entrant unique. L’augmentation de la valeur peut augmenter le risque d’attaques par déni de service (DoS).
MaximumParallelInvocationsPerClient 1 Nombre maximal de méthodes hub que chaque client peut appeler en parallèle avant la mise en file d’attente.

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Startup.ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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;
        });
    });
}

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 32 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au serveur de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
TransportMaxBufferSize 32 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au serveur de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.
MinimumProtocolVersion 0 Spécifiez la version minimale du protocole de négociation. Cela permet de limiter les clients aux versions plus récentes.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Au lieu d’une valeur LogLevel, vous pouvez également fournir une valeur string représentant un nom de niveau journal. Cela est utile lors de la configuration de la journalisation SignalR dans des environnements où vous n’avez pas accès aux constantes LogLevel.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

Le tableau suivant répertorie les niveaux de journal disponibles. La valeur que vous fournissez pour configureLogging définit le niveau de journal minimal qui sera journalisé. Les messages enregistrés à ce niveau, ou les niveaux répertoriés après celui-ci dans la table, seront consignés.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info ou information LogLevel.Information
warn ou warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Remarque

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Dans cette version du client Java, Websockets est le seul transport disponible.

Dans le client Java, le transport est sélectionné avec la méthode withTransport sur le HttpHubConnectionBuilder. Le client Java utilise par défaut le transport WebSockets.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Notes

Le client Java SignalR ne prend pas encore en charge le transport de secours.

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Des options supplémentaires pour configurer le délai d’expiration et le comportement keep-alive sont disponibles sur l’objet HubConnection lui-même :

Option Valeur par défaut Description
ServerTimeout 30 secondes (30 000 millisecondes) Délai d’expiration d’activité du serveur. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur KeepAliveInterval du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Détermine l’intervalle auquel le client envoie des messages ping. L’envoi d’un message à partir du client réinitialise le minuteur au début de l’intervalle. Si le client n’a pas envoyé de message dans le ClientTimeoutInterval défini sur le serveur, le serveur considère le client déconnecté.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à 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();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à 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();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol. AddJsonProtocol peut être ajouté après AddSignalR ou Program.cs. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerOptions sur cet objet est un objet System.Text.JsonJsonSerializerOptions qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs retournées. Pour plus d’informations, consultez la documentation de System.Text.Json.

Par exemple, pour configurer le sérialiseur de manière à ne pas modifier la casse des noms de propriétés, plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Program.cs :

builder.Services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Basculer vers Newtonsoft.Json

Si vous avez besoin de fonctionnalités de Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, consultez Basculer vers Newtonsoft.Json.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
ClientTimeoutInterval 30 secondes Le serveur considère que le client est déconnecté s’il n’a pas reçu de message (y compris keep-alive) au cours de cet intervalle. Cela peut prendre plus de temps que cet intervalle de délai d’attente pour que le client soit marqué déconnecté en raison son implémentation. La valeur recommandée est le double de la valeur KeepAliveInterval.
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.
StreamBufferCapacity 10 Nombre maximal d’éléments pouvant être mis en mémoire tampon pour les flux de chargement client. Si cette limite est atteinte, le traitement des appels est bloqué jusqu’à ce que le serveur traite les éléments de flux.
MaximumReceiveMessageSize 32 Ko Taille maximale d’un message hub entrant unique. L’augmentation de la valeur peut augmenter le risque d’attaques par déni de service (DoS).
MaximumParallelInvocationsPerClient 1 Nombre maximal de méthodes hub que chaque client peut appeler en parallèle avant la mise en file d’attente.

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Program.cs.

builder.Services.AddSignalR(hubOptions =>
{
    hubOptions.EnableDetailedErrors = true;
    hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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();

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 64 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au serveur de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
TransportMaxBufferSize 64 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au serveur de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.
MinimumProtocolVersion 0 Spécifiez la version minimale du protocole de négociation. Cela permet de limiter les clients aux versions plus récentes.
CloseOnAuthenticationExpiration false Définissez cette option pour activer le suivi d’expiration de l’authentification qui ferme les connexions à l’expiration d’un jeton.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Au lieu d’une valeur LogLevel, vous pouvez également fournir une valeur string représentant un nom de niveau journal. Cela est utile lors de la configuration de la journalisation SignalR dans des environnements où vous n’avez pas accès aux constantes LogLevel.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

Le tableau suivant répertorie les niveaux de journal disponibles. La valeur que vous fournissez pour configureLogging définit le niveau de journal minimal qui sera journalisé. Les messages enregistrés à ce niveau, ou les niveaux répertoriés après celui-ci dans la table, seront consignés.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info ou information LogLevel.Information
warn ou warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Remarque

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Dans cette version du client Java, Websockets est le seul transport disponible.

Dans le client Java, le transport est sélectionné avec la méthode withTransport sur le HttpHubConnectionBuilder. Le client Java utilise par défaut le transport WebSockets.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Notes

Le client Java SignalR ne prend pas encore en charge le transport de secours.

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Des options supplémentaires pour configurer le délai d’expiration et le comportement keep-alive sont disponibles sur l’objet HubConnection lui-même :

Option Valeur par défaut Description
ServerTimeout 30 secondes (30 000 millisecondes) Délai d’expiration d’activité du serveur. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur KeepAliveInterval du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Détermine l’intervalle auquel le client envoie des messages ping. L’envoi d’un message à partir du client réinitialise le minuteur au début de l’intervalle. Si le client n’a pas envoyé de message dans le ClientTimeoutInterval défini sur le serveur, le serveur considère le client déconnecté.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.
ApplicationMaxBufferSize 1 Mo Nombre maximal d’octets reçus du serveur que le client met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au client de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
TransportMaxBufferSize 1 Mo Nombre maximal d’octets envoyés par l’application utilisateur que le client met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au client de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à 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();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à 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();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires

Options de sérialisation JSON/MessagePack

ASP.NET Core SignalR prend en charge deux protocoles pour l’encodage des messages : JSON et MessagePack. Chaque protocole a des options de configuration de sérialisation.

La sérialisation JSON peut être configurée sur le serveur à l’aide de la méthode d’extension AddJsonProtocol. AddJsonProtocol peut être ajouté après AddSignalR ou Startup.ConfigureServices. La méthode AddJsonProtocol accepte un délégué qui reçoit un objet options. La propriété PayloadSerializerOptions sur cet objet est un objet System.Text.JsonJsonSerializerOptions qui peut être utilisé pour configurer la sérialisation des arguments et des valeurs retournées. Pour plus d’informations, consultez la documentation de System.Text.Json.

Par exemple, pour configurer le sérialiseur de manière à ne pas modifier la casse des noms de propriétés, plutôt que les noms en casse mixte par défaut, utilisez le code suivant dans Program.cs :

builder.Services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Dans le client .NET, la même méthode d’extension AddJsonProtocol existe sur HubConnectionBuilder. L’espace de noms Microsoft.Extensions.DependencyInjection doit être importé pour résoudre la méthode d’extension :

// 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();

Remarque

Il n’est pas possible de configurer la sérialisation JSON dans le client JavaScript pour l’instant.

Basculer vers Newtonsoft.Json

Si vous avez besoin de fonctionnalités de Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, consultez Basculer vers Newtonsoft.Json.

Options de sérialisation MessagePack

La sérialisation MessagePack peut être configurée en fournissant un délégué à l’appel AddMessagePackProtocol. Pour plus d’informations, consultez MessagePack dans SignalR.

Notes

Pour le moment, il n’est pas possible de configurer la sérialisation MessagePack dans le client JavaScript.

Configurer les options de serveur

Le tableau suivant décrit les options de configuration des hubs SignalR :

Option Valeur par défaut Description
ClientTimeoutInterval 30 secondes Le serveur considère que le client est déconnecté s’il n’a pas reçu de message (y compris keep-alive) au cours de cet intervalle. Cela peut prendre plus de temps que cet intervalle de délai d’attente pour que le client soit marqué déconnecté en raison son implémentation. La valeur recommandée est le double de la valeur KeepAliveInterval.
HandshakeTimeout 15 secondes Si le client n’envoie pas de message initial d’établissement d'une liaison pendant cet intervalle de temps, la connexion est fermée. Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Si le serveur n’a pas envoyé de message dans cet intervalle, un message ping est envoyé automatiquement pour maintenir la connexion ouverte. Lors de la modification de KeepAliveInterval, modifiez le paramètre ServerTimeout ou serverTimeoutInMilliseconds sur le client. La valeur ServerTimeout ou serverTimeoutInMilliseconds recommandée est le double de la valeur KeepAliveInterval.
SupportedProtocols Tous les protocoles installés Protocoles pris en charge par ce hub. Par défaut, tous les protocoles inscrits sur le serveur sont autorisés. Des protocoles spécifiques peuvent être supprimés de cette liste pour les désactiver pour des hubs individuels.
EnableDetailedErrors false Si true, des messages d’exception détaillés sont renvoyés aux clients lorsqu’une exception est levée dans une méthode hub. La valeur par défaut est false, car ces messages d’exception peuvent contenir des informations sensibles.
StreamBufferCapacity 10 Nombre maximal d’éléments pouvant être mis en mémoire tampon pour les flux de chargement client. Si cette limite est atteinte, le traitement des appels est bloqué jusqu’à ce que le serveur traite les éléments de flux.
MaximumReceiveMessageSize 32 Ko Taille maximale d’un message hub entrant unique. L’augmentation de la valeur peut augmenter le risque d’attaques par déni de service (DoS).
MaximumParallelInvocationsPerClient 1 Nombre maximal de méthodes hub que chaque client peut appeler en parallèle avant la mise en file d’attente.
DisableImplicitFromServicesParameters false Les arguments de la méthode hub seront résolus à partir de l’injection de dépendances si possible.

Les options peuvent être configurées pour tous les hubs en fournissant un délégué d’options à l’appel AddSignalR dans Program.cs.

 builder.Services.AddSignalR(hubOptions =>
 {
     hubOptions.EnableDetailedErrors = true;
     hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
 });

Les options d’un hub unique remplacent les options globales fournies dans AddSignalR et peuvent être configurées à l’aide de AddHubOptions :

builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Options de configuration HTTP avancées

Utilisez HttpConnectionDispatcherOptions pour configurer les paramètres avancés liés aux transports et à la gestion des mémoires tampons. Ces options sont configurées en passant un délégué à MapHub dans 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();

Le tableau suivant décrit les options de configuration des options HTTP avancées de ASP.NET Core SignalR :

Option Valeur par défaut Description
ApplicationMaxBufferSize 64 Ko Nombre maximal d’octets reçus du client que le serveur met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au serveur de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
TransportMaxBufferSize 64 Ko Nombre maximal d’octets envoyés par l’application que le serveur met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au serveur de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.
AuthorizationData Données collectées automatiquement à partir des attributs Authorize appliqués à la classe hub. Liste des objets IAuthorizeData utilisés pour déterminer si un client est autorisé à se connecter au hub.
Transports Tous les transports sont activés. Un enum d’indicateurs binaires de valeurs HttpTransportType pouvant restreindre les transports qu’un client peut utiliser pour se connecter.
LongPolling Voir ci-dessous. Options supplémentaires spécifiques au transport d’interrogation longue.
WebSockets Voir ci-dessous. Options supplémentaires spécifiques au transport WebSockets.
MinimumProtocolVersion 0 Spécifiez la version minimale du protocole de négociation. Cela permet de limiter les clients aux versions plus récentes.
CloseOnAuthenticationExpiration false Définissez cette option pour activer le suivi d’expiration de l’authentification qui ferme les connexions à l’expiration d’un jeton.

Le transport d’interrogation longue a des options supplémentaires qui peuvent être configurées à l’aide de la propriété LongPolling :

Option Valeur par défaut Description
PollTimeout 90 secondes Durée maximale pendant laquelle le serveur attend qu’un message soit envoyé au client avant de mettre fin à une seule demande d’interrogation. La diminution de cette valeur entraîne l’émission plus fréquente de nouvelles demandes d’interrogation par le client.

Le transport WebSocket a des options supplémentaires qui peuvent être configurées à l’aide de la propriété WebSockets :

Option Valeur par défaut Description
CloseTimeout 5 secondes Une fois le serveur fermé, si le client ne parvient pas à se fermer pendant cet intervalle de temps, la connexion est terminée.
SubProtocolSelector null Délégué qui peut être utilisé pour définir l’en-tête Sec-WebSocket-Protocol sur une valeur personnalisée. Le délégué reçoit les valeurs demandées par le client en tant qu’entrée et est censé renvoyer la valeur souhaitée.

Configurer les options du client

Les options du client peuvent être configurées sur le type HubConnectionBuilder (disponible dans les clients .NET et JavaScript). Elles sont également disponibles dans le client Java, mais la sous-classe HttpHubConnectionBuilder contient les options de configuration du générateur, ainsi que sur le HubConnection lui-même.

Configuration de la journalisation

La journalisation est configurée dans le client .NET à l’aide de la méthode ConfigureLogging. Les fournisseurs et filtres de journalisation peuvent être inscrits de la même manière que sur le serveur. Pour plus d’informations, consultez la documentation Journalisation dans ASP.NET Core.

Notes

Pour inscrire des fournisseurs de journalisation, vous devez installer les packages nécessaires. Pour obtenir la liste complète, consultez la section Fournisseurs de journalisation intégrés de la documentation.

Par exemple, pour activer la journalisation console, installez le package NuGet Microsoft.Extensions.Logging.Console. Appelez la méthode d’extension AddConsole :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Dans le client JavaScript, une méthode configureLogging similaire existe. Fournissez une valeur LogLevel indiquant le niveau minimal de messages de journal à produire. Les journaux sont écrits dans la fenêtre de la console du navigateur.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Au lieu d’une valeur LogLevel, vous pouvez également fournir une valeur string représentant un nom de niveau journal. Cela est utile lors de la configuration de la journalisation SignalR dans des environnements où vous n’avez pas accès aux constantes LogLevel.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

Le tableau suivant répertorie les niveaux de journal disponibles. La valeur que vous fournissez pour configureLogging définit le niveau de journal minimal qui sera journalisé. Les messages enregistrés à ce niveau, ou les niveaux répertoriés après celui-ci dans la table, seront consignés.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info ou information LogLevel.Information
warn ou warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Remarque

Pour désactiver entièrement la journalisation, spécifiez signalR.LogLevel.None dans la méthode configureLogging.

Pour plus d’informations sur la journalisation, consultez la documentation Diagnostics SignalR.

Le client Java SignalR utilise la bibliothèque SLF4J pour la journalisation. Il s'agit d'une API de journalisation de haut niveau qui permet aux utilisateurs de la bibliothèque de choisir leur propre implémentation de journalisation spécifique en introduisant une dépendance de journalisation spécifique. L'extrait de code suivant montre comment utiliser java.util.logging avec le client Java SignalR.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Si vous ne configurez pas la journalisation dans vos dépendances, SLF4J charge un journal de non-opération par défaut avec le message d'avertissement suivant :

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.

Cela peut être ignoré en toute sécurité.

Configurer les transports autorisés

Les transports utilisés par SignalR peuvent être configurés dans l’appel WithUrl (withUrl dans JavaScript). Un OR au niveau du bit des valeurs de HttpTransportType peut être utilisée pour restreindre le client à utiliser uniquement les transports spécifiés. Tous les transports sont activés par défaut.

Par exemple, pour désactiver le transport d’événements Server-Sent, mais autoriser les connexions WebSockets et d’interrogation longue :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Dans le client JavaScript, les transports sont configurés en définissant le champ transport sur l’objet options fourni à withUrl :

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Dans cette version du client Java, Websockets est le seul transport disponible.

Dans le client Java, le transport est sélectionné avec la méthode withTransport sur le HttpHubConnectionBuilder. Le client Java utilise par défaut le transport WebSockets.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Notes

Le client Java SignalR ne prend pas encore en charge le transport de secours.

Configurer l’authentification du porteur

Pour fournir des données d’authentification ainsi que des requêtes SignalR, utilisez l’option AccessTokenProvider (accessTokenFactory dans JavaScript) pour spécifier une fonction qui renvoie le jeton d’accès souhaité. Dans le client .NET, ce jeton d’accès est transmis en tant que jeton HTTP « Authentification du porteur » (à l’aide de l’en-tête Authorization avec un type de Bearer). Dans le client JavaScript, le jeton d’accès est utilisé comme jeton du porteur, sauf dans quelques cas où les API de navigateur limitent la possibilité d’appliquer des en-têtes (en particulier, dans les demandes d’événements Server-Sent et WebSockets). Dans ce cas, le jeton d’accès est fourni sous la forme d’une valeur de chaîne de requête access_token.

Dans le client .NET, l’option AccessTokenProvider peut être spécifiée à l’aide du délégué d’options dans WithUrl :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Dans le client JavaScript, le jeton d’accès est configuré en définissant le champ accessTokenFactory sur l’objet options dans 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();

Dans le client Java SignalR, vous pouvez configurer un jeton de porteur à utiliser pour l’authentification en fournissant une fabrique de jetons d’accès à HttpHubConnectionBuilder. Utilisez withAccessTokenFactory pour fournir une Single<String> RxJava. Avec un appel à Single.defer, vous pouvez écrire une logique pour produire des jetons d’accès pour votre client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Configurer les options de délai d’expiration et keep-alive

Des options supplémentaires pour configurer le délai d’expiration et le comportement keep-alive sont disponibles sur l’objet HubConnection lui-même :

Option Valeur par défaut Description
ServerTimeout 30 secondes (30 000 millisecondes) Délai d’expiration d’activité du serveur. Si le serveur n’a pas envoyé de message dans cet intervalle, le client considère que le serveur est déconnecté et déclenche l’événement Closed (onclose dans JavaScript). Cette valeur doit être suffisamment grande pour qu’un message ping soit envoyé à partir du serveur et reçu par le client dans l’intervalle de délai d’expiration. La valeur recommandée est un nombre d’au moins le double de la valeur KeepAliveInterval du serveur pour laisser aux pings le temps d’arriver.
HandshakeTimeout 15 secondes Délai d’expiration pour l’établissement d'une liaison initiale au serveur. Si le serveur n’envoie pas de réponse d’établissement d'une liaison pendant cet intervalle, le client annule l’établissement d'une liaison et déclenche l’événement Closed (onclose dans JavaScript). Il s’agit d’un paramètre avancé qui ne doit être modifié que si des erreurs de délai d’expiration d’établissement d'une liaison se produisent en raison d’une latence réseau importante. Pour plus d’informations sur le processus d’établissement d’une liaison, consultez la spécification du protocole Hub SignalR.
KeepAliveInterval 15 secondes Détermine l’intervalle auquel le client envoie des messages ping. L’envoi d’un message à partir du client réinitialise le minuteur au début de l’intervalle. Si le client n’a pas envoyé de message dans le ClientTimeoutInterval défini sur le serveur, le serveur considère le client déconnecté.

Dans le client .NET, les valeurs de délai d’expiration sont spécifiées en tant que valeurs TimeSpan.

Configurer des options supplémentaires

Des options supplémentaires peuvent être configurées dans la méthode WithUrl (withUrl dans JavaScript) sur HubConnectionBuilder ou sur les différentes API de configuration sur le HttpHubConnectionBuilder dans le client Java :

Option .NET Valeur par défaut Description
AccessTokenProvider null Fonction retournant une chaîne fournie en tant que jeton d’authentification du porteur dans les requêtes HTTP.
SkipNegotiation false Définissez cette valeur sur true pour ignorer l’étape de négociation. Pris en charge uniquement lorsque le transport WebSockets est le seul transport activé. Ce paramètre ne peut pas être activé lors de l’utilisation du service Azure SignalR.
ClientCertificates Vide Collection de certificats TLS à envoyer pour authentifier les requêtes.
Cookies Vide Collection de cookies HTTP à envoyer avec chaque requête HTTP.
Credentials Vide Informations d’identification à envoyer avec chaque requête HTTP.
CloseTimeout 5 secondes WebSockets uniquement. Durée maximale pendant laquelle le client attend après la fermeture pour que le serveur accepte la demande de fermeture. Si le serveur ne reconnaît pas la fermeture dans ce délai, le client se déconnecte.
Headers Vide Carte d’en-têtes HTTP supplémentaires à envoyer avec chaque requête HTTP.
HttpMessageHandlerFactory null Délégué qui peut être utilisé pour configurer ou remplacer le HttpMessageHandler utilisé pour envoyer des requêtes HTTP. Non utilisé pour les connexions WebSocket. Ce délégué doit renvoyer une valeur non nulle et il reçoit la valeur par défaut en tant que paramètre. Modifiez les paramètres de cette valeur par défaut et renvoyez-la, ou retournez une nouvelle instance HttpMessageHandler. Lorsque vous remplacez le gestionnaire, veillez à copier les paramètres que vous souhaitez conserver à partir du gestionnaire fourni. Sinon, les options configurées (telles que les cookies et les en-têtes) ne s’appliqueront pas au nouveau gestionnaire.
Proxy null Proxy HTTP à utiliser lors de l’envoi de requêtes HTTP.
UseDefaultCredentials false Définissez ce booléen pour envoyer les informations d’identification par défaut pour les requêtes HTTP et WebSockets. Cela permet d’utiliser l’authentification Windows.
WebSocketConfiguration null Délégué qui peut être utilisé pour configurer des options WebSocket supplémentaires. Reçoit une instance de ClientWebSocketOptions qui peut être utilisée pour configurer les options.
ApplicationMaxBufferSize 1 Mo Nombre maximal d’octets reçus du serveur que le client met en mémoire tampon avant d’appliquer une contre-pression. L’augmentation de cette valeur permet au client de recevoir plus rapidement des messages plus volumineux sans appliquer de contre-pression, mais peut augmenter la consommation de mémoire.
TransportMaxBufferSize 1 Mo Nombre maximal d’octets envoyés par l’application utilisateur que le client met en mémoire tampon avant d’observer la contre-pression. L’augmentation de cette valeur permet au client de mettre plus rapidement en mémoire tampon des messages plus volumineux sans attendre une contre-pression, mais peut augmenter la consommation de mémoire.

Dans le client .NET, ces options peuvent être modifiées par le délégué d’options fourni à 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();

Dans le client JavaScript, ces options peuvent être fournies dans un objet JavaScript fourni à 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();

Dans le client Java, ces options peuvent être configurées avec les méthodes sur le HttpHubConnectionBuilder retourné à partir de HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Ressources supplémentaires