Partager via

intégration de .NET AspireAzureAzure SignalR Service

Inclut :Intégration d’hébergement incluse intégration d’hébergement uniquement : Client intégration non incluseClient non incluse

Azure SignalR Service est un service de messagerie en temps réel entièrement géré qui simplifie l’ajout de fonctionnalités web en temps réel à vos applications. L’intégration .NET AspireAzureAzure SignalR Service vous permet d’approvisionner, de configurer et de connecter facilement vos applications .NET à des instances AzureAzure SignalR Service.

Cet article explique comment intégrer AzureAzure SignalR Service dans vos applications .NET Aspire, en couvrant à la fois l’hébergement et l’intégration côté client.

Intégration de l’hébergement

Les modèles d'intégration d'hébergement .NET AspireAzureAzure SignalR Service regroupent les ressources AzureSignalR sous les types suivants :

  • AzureSignalRResource: représente une ressource AzureAzure SignalR Service, y compris les informations de connexion à la ressource Azure sous-jacente.
  • AzureSignalREmulatorResource: représente un émulateur pour AzureAzure SignalR Service, autorisant le développement et le test locaux sans nécessiter d’abonnement Azure .

Pour accéder aux types d’hébergement et aux API pour exprimer ces ressources dans le constructeur d'applications distribuées, installez le package NuGet 📦Aspire.Hosting.Azure.SignalR dans votre projet d’hôte d’application :

dotnet add package Aspire.Hosting.Azure.SignalR

Pour plus d'informations, consultez dotnet add package ou Gérer les dépendances des packages dans les applications .NET.

Ajouter une ressource AzureAzure SignalR Service

Pour ajouter une AzureAzure SignalR Service ressource à votre projet hôte d’application, appelez la AddAzureSignalR méthode :

var builder = DistributedApplication.CreateBuilder(args);

var signalR = builder.AddAzureSignalR("signalr");

var api = builder.AddProject<Projects.ApiService>("api")
                 .WithReference(signalR)
                 .WaitFor(signalR);

builder.AddProject<Projects.WebApp>("webapp")
       .WithReference(api)
       .WaitFor(api);

// Continue configuring and run the app...

Dans l’exemple précédent :

  • Une AzureAzure SignalR Service ressource nommée signalr est ajoutée.
  • La signalr ressource est référencée par le api projet.
  • Le api projet est référencé par le webapp projet.

Cette architecture permet au webapp projet de communiquer avec le api projet, qui communique à son tour avec la AzureAzure SignalR Service ressource.

Importante

Le fait d'appeler AddAzureSignalR permet implicitement la prise en charge de l'approvisionnement par Azure. Vérifiez que votre hôte d’application est configuré avec l’abonnement et l’emplacement appropriés Azure . Pour plus d’informations, consultez Provisionnement local : Configuration.

Provisionnement généré par Bicep

Lorsque vous ajoutez une ressource, Azure génère une Azure SignalR Service.NET Aspire infrastructure d’approvisionnement à l’aide de Bicep. Le Bicep généré inclut les valeurs par défaut pour l’emplacement, la référence SKU et les attributions de rôles :

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource signalr 'Microsoft.SignalRService/signalR@2024-03-01' = {
  name: take('signalr-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    cors: {
      allowedOrigins: [
        '*'
      ]
    }
    features: [
      {
        flag: 'ServiceMode'
        value: 'Default'
      }
    ]
  }
  kind: 'SignalR'
  sku: {
    name: 'Free_F1'
    capacity: 1
  }
  tags: {
    'aspire-resource-name': 'signalr'
  }
}

output hostName string = signalr.properties.hostName

output name string = signalr.name

Le Bicep généré fournit un point de départ et peut être personnalisé plus loin.

Personnaliser l’infrastructure d’approvisionnement

Toutes les ressources .NET AspireAzure sont des sous-classes du type AzureProvisioningResource. Cela permet de personnaliser le Bicep généré en fournissant une API fluide pour configurer les Azure ressources à l'aide de l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>).

builder.AddAzureSignalR("signalr")
    .ConfigureInfrastructure(infra =>
    {
        var signalRService = infra.GetProvisionableResources()
                                  .OfType<SignalRService>()
                                  .Single();

        signalRService.Sku.Name = "Premium_P1";
        signalRService.Sku.Capacity = 10;
        signalRService.PublicNetworkAccess = "Enabled";
        signalRService.Tags.Add("ExampleKey", "Example value");
    });

Code précédent :

Se connecter à un AzureAzure SignalR Service existant

Vous pouvez avoir un AzureAzure SignalR Service existant auquel vous souhaitez vous connecter. Vous pouvez chaîner un appel pour annoter que votre AzureSignalRResource est une ressource existante :

var builder = DistributedApplication.CreateBuilder(args);

var existingSignalRName = builder.AddParameter("existingSignalRName");
var existingSignalRResourceGroup = builder.AddParameter("existingSignalRResourceGroup");

var signalr = builder.AddAzureSignalR("signalr")
                     .AsExisting(existingSignalRName, existingSignalRResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(signalr);

// After adding all resources, run the app...

Importante

Lorsque vous appelez les méthodes RunAsExisting, PublishAsExisting ou AsExisting pour travailler avec des ressources déjà présentes dans votre abonnement Azure, vous devez ajouter certaines valeurs de configuration à votre hôte d’application pour vous assurer que .NET Aspire peut les localiser. Les valeurs de configuration nécessaires incluent SubscriptionId, AllowResourceGroupCreation, ResourceGroup et Location. Si vous ne les définissez pas, les erreurs « Configuration manquante » apparaissent dans le .NET.NET Aspire tableau de bord. Pour plus d’informations sur la façon de les définir, consultez Configuration.

Pour plus d’informations sur le traitement des AzureSignalR ressources en tant que ressources existantes, consultez Utiliser des ressources existantesAzure.

Remarque

Vous pouvez également ajouter une chaîne de connexion à l’hôte de l’application au lieu de représenter une ressource AzureAzure SignalR Service. Cette approche est faiblement typée et ne fonctionne pas avec les attributions de rôles ou les personnalisations d’infrastructure. Pour plus d’informations, consultez Ajouter des ressources existantes Azure avec des chaînes de connexion.

Ajouter une ressource d’émulateur AzureAzure SignalR Service

L’émulateur AzureAzure SignalR Service est un outil de développement et de test local qui émule le comportement de AzureAzure SignalR Service. Cet émulateur prend uniquement en charge le mode serverless, ce qui nécessite une configuration spécifique lors de l’utilisation de l’émulateur.

Pour utiliser l’émulateur, chaînez un appel à la RunAsEmulator(IResourceBuilder<AzureSignalRResource>, Action<IResourceBuilder<AzureSignalREmulatorResource>>) méthode :

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var signalR = builder.AddAzureSignalR("signalr", AzureSignalRServiceMode.Serverless)
                     .RunAsEmulator();

builder.AddProject<Projects.ApiService>("apiService")
       .WithReference(signalR)
       .WaitFor(signalR);

// After adding all resources, run the app...

Dans l’exemple précédent, la RunAsEmulator méthode configure la AzureAzure SignalR Service ressource pour qu’elle s’exécute en tant qu’émulateur. L’émulateur est basé sur l’image de conteneur mcr.microsoft.com/signalr/signalr-emulator:latest. L’émulateur est démarré lorsque l’hôte de l’application est exécuté et est arrêté lorsque l’hôte de l’application est arrêté.

Azure Azure SignalR Service modes

Bien que l’émulateur AzureAzure SignalR Service prenne uniquement en charge le mode serverless , la AzureAzure SignalR Service ressource peut être configurée pour utiliser l’un des modes suivants :

  • AzureSignalRServiceMode.Default
  • AzureSignalRServiceMode.Serverless

Le mode par défaut est la configuration « par défaut » pour AzureAzure SignalR Service. Chaque mode a son propre ensemble de fonctionnalités et de limitations. Pour plus d’informations, consultez AzureAzure SignalR Service les modes.

Importante

L’émulateur AzureAzure SignalR Service fonctionne uniquement en mode Serverless et la méthode ne prend pas en charge le AddNamedAzureSignalR mode serverless .

Intégration d'un hub hôte

Il n’existe pas .NET Aspire officielle AzureSignalR du client. Toutefois, il existe un support limité pour des expériences similaires. Dans ces scénarios, le AzureAzure SignalR Service rôle de proxy entre le serveur (où le Hub ou Hub<T> sont hébergés) et le client (où le SignalR client est hébergé). Le AzureAzure SignalR Service trafic est acheminé entre le serveur et le client, ce qui permet une communication en temps réel.

Importante

Il est important de lever l’ambiguïté entre .NET Aspire les intégrations clientes et le .NETSignalR client. SignalR expose des hubs, qui agissent comme un concept côté serveur, et SignalR les clients se connectent à ces hubs. Les .NET projets qui hébergent SignalR des hubs, c'est là que vous vous intégrez avec .NET Aspire. Le SignalR client est une bibliothèque distincte qui se connecte à ces hubs, dans un autre projet.

Il existe deux paquets disponibles, chacun ayant pour but de répondre à des scénarios spécifiques tels que la gestion de la connexion du client à AzureAzure SignalR Service, et la connexion à la ressource AzureAzure SignalR Service. Pour commencer, installez 📦 Microsoft.Azure.SignalR Package NuGet dans le projet hébergeant votre SignalR hub.

dotnet add package Microsoft.Azure.SignalR

Configurer l'entité nommée AzureAzure SignalR Service en mode par défaut

En mode par défaut , votre projet consommateur doit s’appuyer sur une ressource nommée AzureAzure SignalR Service . Considérez le diagramme suivant qui illustre l’architecture du AzureAzure SignalR Service mode par défaut :

AzureAzure SignalR Service: diagramme du mode par défaut.

Pour plus d’informations sur le mode par défaut , consultez AzureAzure SignalR Service: Mode par défaut.

Dans votre SignalR projet hôte hub, configurez AzureAzure SignalR Service en chaînant des appels vers .AddSignalR().AddNamedAzureSignalR("name"):

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR()
                .AddNamedAzureSignalR("signalr");

var app = builder.Build();

app.MapHub<ChatHub>("/chat");

app.Run();

La AddNamedAzureSignalR méthode configure le projet pour utiliser la AzureAzure SignalR Service ressource nommée signalr. La chaîne de connexion est lue à partir de la clé ConnectionStrings:signalrde configuration et des paramètres supplémentaires sont chargés à partir de la Azure:SignalR:signalr section de configuration.

Remarque

Si vous utilisez l’émulateur AzureSignalR , vous ne pouvez pas utiliser la AddNamedAzureSignalR méthode.

Configurer AzureAzure SignalR Service en mode serverless

Si vous êtes un hôte d'application et que vous utilisez l'émulateurAzureSignalR, vous devez également installer le package NuGet de gestion de Microsoft📦.Azure.SignalR..

dotnet add package Microsoft.Azure.SignalR.Management

Azure SignalRLe mode serverless ne nécessite pas l’exécution d’un serveur hub. Azure Azure SignalR Service est responsable de la maintenance des connexions des clients. En outre, dans ce mode, vous ne pouvez pas utiliser les hubs traditionnels SignalR , tels que Hub, Hub<T>ou IHubContext<THub>. Au lieu de cela, configurez un point de terminaison en amont qui est généralement un Azure déclencheur de fonctionSignalR. Considérez le diagramme suivant qui illustre l’architecture du AzureAzure SignalR Service mode serverless :

AzureAzure SignalR Service: diagramme du mode serverless.

Pour plus d’informations sur le mode serverless , consultez AzureAzure SignalR Service: mode serverless.

Dans un projet destiné à communiquer avec le AzureAzure SignalR Service, inscrivez les services appropriés en appelant AddSignalR, puis en inscrivant ServiceManager avec la chaîne de connexion signalr et ajoutez un point de terminaison /negotiate.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
{
   return new ServiceManagerBuilder()
       .WithOptions(options =>
       {
           options.ConnectionString = builder.Configuration.GetConnectionString("signalr");
       })
       .BuildServiceManager();
});

var app = builder.Build();

app.MapPost("/negotiate", async (string? userId, ServiceManager sm, CancellationToken token) =>
{
    // The creation of the ServiceHubContext is expensive, so it's recommended to 
    // only create it once per named context / per app run if possible.
    var context = await sm.CreateHubContextAsync("messages", token);
    
    var negotiateResponse = await context.NegotiateAsync(new NegotiationOptions
    {
        UserId = userId
    }, token);
    
    // The JSON serializer options need to be set to ignore null values, otherwise the
    // response will contain null values for the properties that are not set.
    // The .NET SignalR client will not be able to parse the response if the null values are present.
    // For more information, see https://github.com/dotnet/aspnetcore/issues/60935.
    return Results.Json(negotiateResponse, new JsonSerializerOptions(JsonSerializerDefaults.Web)
    {
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
    });
});

app.Run();

Le code précédent configure la classe Azure avec Azure SignalR ServiceServiceManagerBuilder, mais n'appelle pas AddSignalR ou MapHub. Ces deux extensions ne sont pas requises avec le mode serverless . La chaîne de connexion est lue à partir de la clé ConnectionStrings:signalrde configuration . Lorsque vous utilisez l’émulateur, seul le point de terminaison HTTP est disponible. Dans l’application, vous pouvez utiliser l’instance ServiceManager pour créer un ServiceHubContext. ServiceHubContext est utilisé pour diffuser des messages et gérer les connexions aux clients.

Le /negotiate point de terminaison est requis pour établir une connexion entre le client de connexion et le AzureAzure SignalR Service. La création de ServiceHubContext se fait à l'aide de la méthode ServiceManager.CreateHubContextAsync, qui prend le nom du hub en tant que paramètre. La NegotiateAsync méthode est appelée pour négocier la connexion avec le AzureAzure SignalR Service, qui retourne un jeton d’accès et l’URL pour que le client se connecte.

Pour plus d’informations, consultez Utiliser le AzureSignalR Kit de développement logiciel (SDK) de gestion.

Voir aussi