C ASP.NET Core SignalR

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

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.

Configurer les options de serveur

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

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 :

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

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

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.

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.

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

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 :

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

var connection = new signalR.HubConnectionBuilder()
  .withUrl("/chatHub")
  .withServerTimeout(60000)
  .withKeepAliveInterval(30000)
  .build();

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par 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, 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();

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.

Configurer les options de serveur

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

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 :

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

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

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.

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

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 :

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par 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, 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();

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.

Configurer les options de serveur

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

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 :

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

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

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.

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

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 :

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par 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 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();

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.

Configurer les options de serveur

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

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 :

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

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

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.

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.

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

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 :

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par 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 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();

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.

Configurer les options de serveur

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

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 :

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

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

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.

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.

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

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 :

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par 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 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();

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.

Configurer les options de serveur

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

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 :

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

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

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.

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.

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

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 :

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par 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 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();

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.

Configurer les options de serveur

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

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 :

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

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

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.

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.

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

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 :

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par 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();

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.

Configurer les options de serveur

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

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 :

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

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

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.

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.

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

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 :

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 :

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

• Bien démarrer avec ASP.NET Core SignalR
• Utiliser des hubs dans ASP.NET Core SignalR
• Client JavaScript SignalRASP.NET Core
• Client .NET ASP.NET Core SignalR
• Utiliser le protocole hub MessagePack dans SignalR pour ASP.NET Core
• Plateformes prises en charge SignalR par ASP.NET Core