Freigeben über

.NET Aspire Azure Azure SignalR Service Einbindung

Beinhaltet:Hosting-Integration enthalten Nur Hosting-Integration — Client Integration nicht enthaltenClient Integration nicht enthalten

Azure SignalR Service ist ein vollständig verwalteter Echtzeitnachrichtendienst, der das Hinzufügen von Echtzeitwebfunktionen zu Ihren Anwendungen vereinfacht. Mit der .NET AspireAzureAzure SignalR Service-Integration können Sie ganz einfach Ihre .NET Anwendungen bereitstellen, konfigurieren und mit AzureAzure SignalR Service Instanzen verbinden.

In diesem Artikel wird beschrieben, wie Sie AzureAzure SignalR Service in Ihre .NET Aspire-Anwendungen integrieren. Dabei wird sowohl die Hosting- als auch die Clientintegration abgedeckt.

Integration von Hosting

Die .NET AspireAzureAzure SignalR Service Ressourcen für die Hostingintegration sind AzureSignalR die folgenden Typen:

  • AzureSignalRResource: Stellt eine AzureAzure SignalR Service Ressource dar, einschließlich Verbindungsinformationen zur zugrunde liegenden Azure Ressource.
  • AzureSignalREmulatorResource: Stellt einen Emulator für AzureAzure SignalR Service dar, der die lokale Entwicklung und das Testen ermöglicht, ohne dass ein Azure-Abonnement erforderlich ist.

Um auf die Hostingtypen und APIs zuzugreifen, mit denen diese Ressourcen im verteilten Anwendungs-Generator dargestellt werden, installieren Sie das 📦Aspire.Hosting.Azure.SignalR NuGet-Paket in Ihrem App-Hostprojekt.

dotnet add package Aspire.Hosting.Azure.SignalR

Weitere Informationen finden Sie unter dotnet add package oder Verwalten von Paketabhängigkeiten in .NET Anwendungen.

Hinzufügen einer AzureAzure SignalR Service-Ressource

Rufen Sie die Azure Methode auf, um Ihrem App-Hostprojekt eine Azure SignalR ServiceAddAzureSignalR Ressource hinzuzufügen:

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...

Im vorherigen Beispiel:

  • Eine AzureAzure SignalR Service Ressource mit dem Namen signalr wird hinzugefügt.
  • Die signalr Ressource wird vom api Projekt referenziert.
  • Das api-Projekt verweist auf das webapp-Projekt.

Diese Architektur ermöglicht es dem webapp Projekt, mit dem api Projekt zu kommunizieren, was wiederum mit der AzureAzure SignalR Service Ressource kommuniziert.

Wichtig

Das implizite Aufrufen AddAzureSignalR ermöglicht Azure die Bereitstellungsunterstützung. Stellen Sie sicher, dass Ihr App-Host mit dem entsprechenden Azure Abonnement und Standort konfiguriert ist. Weitere Informationen finden Sie unter Lokale Bereitstellung: Konfiguration.

Durch Bereitstellung generierter Bicep

Wenn Sie eine AzureAzure SignalR Service Ressource hinzufügen, generiert .NET Aspire die Bereitstellungsinfrastruktur mit Hilfe von Bicep. Die generierte Bicep enthält Standardwerte für Standort-, SKU- und Rollenzuweisungen:

@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

Das generierte Bicep-Skript dient als Ausgangspunkt und kann weiter angepasst werden.

Bereitstellungsinfrastruktur anpassen

Alle .NET AspireAzure Ressourcen sind Unterklassen des AzureProvisioningResource Typs. Durch Bereitstellung einer Fluent-API wird es ermöglicht, die generierte Bicep-Datei anzupassen, indem die Azure-Ressourcen mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API konfiguriert werden.

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");
    });

Der vorherige Code:

Verbindung mit einer vorhandenen AzureAzure SignalR Service herstellen

Möglicherweise verfügen Sie über eine vorhandene AzureAzure SignalR Service, mit der Sie eine Verbindung herstellen möchten. Sie können einen Aufruf verketten, um anzumerken, dass Ihr AzureSignalRResource eine vorhandene Ressource ist.

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...

Wichtig

Wenn Sie die Methoden RunAsExisting, PublishAsExisting oder AsExisting aufrufen, um mit Ressourcen zu arbeiten, die bereits in Ihrem Azure Abonnement vorhanden sind, müssen Sie Ihrem App-Host bestimmte Konfigurationswerte hinzufügen, um sicherzustellen, dass .NET Aspire diese finden kann. Zu den erforderlichen Konfigurationswerten gehören SubscriptionId, AllowResourceGroupCreation, ResourceGroup und Location. Wenn Sie sie nicht festlegen, werden Fehler „Fehlende Konfiguration“ im .NET.NET Aspire-Dashboard angezeigt. Weitere Informationen zum Festlegen dieser Informationen finden Sie unter "Konfiguration".

Weitere Informationen zum Behandeln von AzureSignalR Ressourcen als vorhandene Ressourcen finden Sie unter Verwenden vorhandener Azure Ressourcen.

Hinweis

Alternativ können Sie dem Host der App anstelle einer AzureAzure SignalR Service-Ressource eine Verbindungszeichenfolge hinzufügen. Dieser Ansatz ist schwach typiert und funktioniert nicht mit Rollenzuweisungen oder Infrastrukturanpassungen. Weitere Informationen finden Sie unter Hinzufügen vorhandener Azure Ressourcen mit Verbindungszeichenfolgen.

Hinzufügen einer AzureAzure SignalR Service Emulatorressource

Der AzureAzure SignalR ServiceEmulator ist ein lokales Entwicklungs- und Testtool, das das Verhalten von AzureAzure SignalR Service emuliert. Dieser Emulator unterstützt nur den Serverlosen Modus, der bei Verwendung des Emulators eine bestimmte Konfiguration erfordert.

Um den Emulator zu verwenden, verketten Sie einen Aufruf der RunAsEmulator(IResourceBuilder<AzureSignalRResource>, Action<IResourceBuilder<AzureSignalREmulatorResource>>) Methode:

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...

Im vorherigen Beispiel konfiguriert die Methode die RunAsEmulatorAzureAzure SignalR Service Ressource so, dass sie als Emulator ausgeführt wird. Der Emulator basiert auf dem mcr.microsoft.com/signalr/signalr-emulator:latest Containerimage. Der Emulator wird gestartet, wenn der App-Host ausgeführt wird und beendet wird, wenn der App-Host beendet wird.

Azure Azure SignalR Service Modi

Während der AzureAzure SignalR Service Emulator nur den Serverless-Modus unterstützt, kann die AzureAzure SignalR Service Ressource so konfiguriert werden, dass sie einen der folgenden Modi verwendet:

  • AzureSignalRServiceMode.Default
  • AzureSignalRServiceMode.Serverless

Der Standardmodus ist die Standardkonfiguration für AzureAzure SignalR Service. Jeder Modus verfügt über einen eigenen Satz von Features und Einschränkungen. Weitere Informationen finden Sie unter AzureAzure SignalR Service Modi.

Wichtig

Der AzureAzure SignalR Service Emulator funktioniert nur im Serverlosen Modus, und die AddNamedAzureSignalR Methode unterstützt keinen Serverless-Modus .

Hub-Host-Integration

Es gibt keine offizielle .NET AspireAzureSignalRClient-Integration. Es gibt jedoch eingeschränkte Unterstützung für ähnliche Erfahrungen. In diesen Szenarien fungiert der AzureAzure SignalR Service als Proxy zwischen dem Server (auf dem der Hub oder Hub<T> gehostet wird) und dem Client (wo der SignalR Client gehostet wird). Der AzureAzure SignalR Service Datenverkehr zwischen dem Server und dem Client wird weitergeleitet, sodass die Echtzeitkommunikation möglich ist.

Wichtig

Es ist wichtig, klar zwischen .NET Aspire Client-Integrationen und dem .NETSignalR Client zu unterscheiden. SignalR macht Hubs verfügbar, die als serverseitiges Konzept fungieren, und SignalR Clients stellen eine Verbindung zu diesen Hubs her. Die .NET Projekte, die SignalR Hubs hosten, sind wo Sie sich mit .NET Aspire integrieren. Der SignalR Client ist eine separate Bibliothek, die eine Verbindung mit diesen Hubs in einem anderen Projekt herstellt.

Es stehen zwei Pakete zur Verfügung, wobei jede auf spezifische Szenarien eingeht, wie z. B. die Verwaltung der Clientverbindung mit AzureAzure SignalR Service sowie das Herstellen der Verbindung zur AzureAzure SignalR Service-Ressource. Um zu beginnen, installieren Sie Microsoft📦.Azure.SignalR NuGet-Paket im Projekt, das Ihren SignalR Hub hostet.

dotnet add package Microsoft.Azure.SignalR

Benanntes AzureAzure SignalR Service im Standardmodus konfigurieren

Im Standardmodus muss sich Ihr verbrauchendes Projekt auf eine benannte AzureAzure SignalR Service Ressource verlassen. Betrachten Sie das folgende Diagramm, das die Architektur im AzureAzure SignalR ServiceStandardmodus veranschaulicht:

AzureAzure SignalR Service: Standardmodusdiagramm.

Weitere Informationen zum Standardmodus finden Sie unter AzureAzure SignalR Service: Standardmodus.

In Ihrem SignalR-Hubhostprojekt konfigurieren Sie AzureAzure SignalR Service durch das Verketten von Aufrufen an .AddSignalR().AddNamedAzureSignalR("name").

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Die AddNamedAzureSignalR Methode konfiguriert das Projekt so, dass die Ressource AzureAzure SignalR Service mit dem Namen signalr verwendet wird. Die Verbindungszeichenfolge wird aus dem Konfigurationsschlüssel ConnectionStrings:signalrgelesen, und zusätzliche Einstellungen werden aus dem Azure:SignalR:signalr Konfigurationsabschnitt geladen.

Hinweis

Wenn Sie den AzureSignalR Emulator verwenden, können Sie die AddNamedAzureSignalR Methode nicht verwenden.

Konfigurieren AzureAzure SignalR Service im Serverlosen Modus

Wenn der App-Host den AzureSignalR Emulator verwendet, müssen Sie auch das 📦 NuGet-Paket installieren.

dotnet add package Microsoft.Azure.SignalR.Management

Azure SignalRDer Serverless-Modus erfordert keine Ausführung eines Hubservers. Das AzureAzure SignalR Service ist für die Aufrechterhaltung von Clientverbindungen verantwortlich. Darüber hinaus können Sie in diesem Modus keine herkömmlichen SignalR Hubs wie Hub, Hub<T> oder IHubContext<THub> verwenden. Konfigurieren Sie stattdessen einen upstream-Endpunkt, der normalerweise ein Azure Funktionstrigger SignalR ist. Betrachten Sie das folgende Diagramm, das die Architektur im AzureAzure SignalR ServiceServerlosen Modus veranschaulicht:

AzureAzure SignalR Service: Serverloses Modusdiagramm.

Weitere Informationen zum Serverless-Modus finden Sie unter AzureAzure SignalR Service: Serverless Mode.

Registrieren Sie in einem Projekt, das mit dem AzureAzure SignalR Service kommuniziert, die entsprechenden Dienste, indem Sie AddSignalR aufrufen, dann die ServiceManager mit der signalr-Verbindungszeichenfolge registrieren und einen /negotiate-Endpunkt hinzufügen.

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

Der vorangehende Code konfiguriert die AzureAzure SignalR Service-Klasse mit der ServiceManagerBuilder-Klasse, ruft jedoch weder AddSignalR noch MapHub auf. Diese beiden Erweiterungen sind im Serverless-Modus nicht erforderlich. Die Verbindungszeichenfolge wird aus dem Konfigurationsschlüssel ConnectionStrings:signalrgelesen. Bei Verwendung des Emulators ist nur der HTTP-Endpunkt verfügbar. Innerhalb der App können Sie die ServiceManager-Instanz verwenden, um eine ServiceHubContext zu erstellen. Dies ServiceHubContext wird verwendet, um Nachrichten zu übertragen und Verbindungen mit Clients zu verwalten.

Der /negotiate-Endpunkt ist erforderlich, um eine Verbindung zwischen dem verbindenden Client und dem AzureAzure SignalR Service herzustellen. Die ServiceHubContext wird durch die ServiceManager.CreateHubContextAsync Methode erstellt, die den Hubnamen als Parameter nimmt. Die NegotiateAsync-Methode wird aufgerufen, um die Verbindung mit dem AzureAzure SignalR Service auszuhandeln. Dabei wird ein Zugriffstoken und die URL für den Client zurückgegeben, um die Verbindung herzustellen.

Weitere Informationen finden Sie unter Use AzureSignalR Management SDK.

Siehe auch