Aspire Azure Azure SignalR Service samverkan

Inkluderar: Värdintegrering ingår Endast värdintegrering – integrering ingår inte

Azure SignalR Service är en fullständigt hanterad meddelandetjänst i realtid som förenklar tillägg av webbfunktioner i realtid i dina program. Med integreringen AspireAzureAzure SignalR Service kan du enkelt etablera, konfigurera och ansluta dina .NET program till AzureAzure SignalR Service instanser.

Den här artikeln beskriver hur du integrerar AzureAzure SignalR Service i dina Aspire program, som omfattar både värd- och klientintegrering.

Integrering av värdtjänster

Hostingintegreringsmodeller AspireAzureAzure SignalR ServiceAzureSignalR resurser som följande typer:

• AzureSignalRResource: Representerar en AzureAzure SignalR Service resurs, inklusive anslutningsinformation till den underliggande Azure resursen.
• AzureSignalREmulatorResource: Representerar en emulator för AzureAzure SignalR Service, som tillåter lokal utveckling och testning utan att Azure en prenumeration krävs.

Om du vill komma åt värdtyperna och API:erna för att uttrycka dessa resurser i den distribuerade programverktyget installerar du 📦Aspire. Hosting.Azure.SignalR NuGet-paket i ditt AppHost-projekt :

dotnet add package Aspire.Hosting.Azure.SignalR

<PackageReference Include="Aspire.Hosting.Azure.SignalR"
                  Version="*" />

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägga till en AzureAzure SignalR Service resurs

Om du vill lägga till en AzureAzure SignalR Service resurs i ditt AppHost-projekt anropar du AddAzureSignalR metoden:

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

I föregående exempel:

• En AzureAzure SignalR Service resurs med namnet signalr läggs till.
• Resursen signalr refereras av api projektet.
• Projektet api refereras av webapp projektet.

Med den här arkitekturen webapp kan projektet kommunicera med api projektet, som i sin tur kommunicerar med resursen AzureAzure SignalR Service .

Ansluta till en befintlig AzureAzure SignalR Service

Du kanske har en befintlig AzureAzure SignalR Service som du vill ansluta till. Du kan kedja en anropning för att annotera att din AzureSignalRResource är en befintlig resurs:

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

Mer information om hur du behandlar AzureSignalR resurser som befintliga resurser finns i Använd befintliga Azure resurser.

Lägga till en AzureAzure SignalR Service emulatorresurs

Emulatorn AzureAzure SignalR Service är ett lokalt utvecklings- och testverktyg som emulerar beteendet AzureAzure SignalR Serviceför . Den här emulatorn stöder endast serverlöst läge, vilket kräver en specifik konfiguration när du använder emulatorn.

Om du vill använda emulatorn kedjar du ett anrop till RunAsEmulator(IResourceBuilder<AzureSignalRResource>, Action<IResourceBuilder<AzureSignalREmulatorResource>>) metoden:

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

I föregående exempel RunAsEmulator konfigurerar metoden resursen så att den AzureAzure SignalR Service körs som en emulator. Emulatorn baseras på containeravbildningen mcr.microsoft.com/signalr/signalr-emulator:latest . Emulatorn startas när AppHost körs och stoppas när AppHost stoppas.

Azure Azure SignalR Service Lägen

Azure Azure SignalR Service Även om emulatorn endast stöder serverlöst läge kan resursen AzureAzure SignalR Service konfigureras att använda något av följande lägen:

• AzureSignalRServiceMode.Default
• AzureSignalRServiceMode.Serverless

Standardläget är standardkonfigurationen för AzureAzure SignalR Service. Varje läge har en egen uppsättning funktioner och begränsningar. För mer information, se AzureAzure SignalR Service lägesalternativ.

Konfigurationsgenererad Bicep

När du lägger till en AzureAzure SignalR Service resurs, genererar Aspire tillhandahållandeinfrastruktur med Bicep. Den genererade Bicep innehåller standardvärden för plats-, SKU- och rolltilldelningar:

@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: [
        '*'
      ]
    }
    disableLocalAuth: true
    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

Föregående Bicep är en modul som provisionerar en AzureAzure SignalR Service resurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

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

param signalr_outputs_name string

param principalType string

param principalId string

resource signalr 'Microsoft.SignalRService/signalR@2024-03-01' existing = {
  name: signalr_outputs_name
}

resource signalr_SignalRAppServer 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(signalr.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '420fcaa2-552c-430f-98ca-3264be4806c7'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '420fcaa2-552c-430f-98ca-3264be4806c7')
    principalType: principalType
  }
  scope: signalr
}

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa infrastruktur för provisionering

Alla AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Detta möjliggör anpassning av den genererade Bicep genom att tillhandahålla ett flytande API för att konfigurera resurserna Azure med hjälp av API:et 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");
    });

Föregående kod:

• Kedjar ett anrop till ConfigureInfrastructure-API:et:
  • Parametern infra är en instans av den AzureResourceInfrastructure typen.
  • De tillgängliga resurserna hämtas genom att anropa GetProvisionableResources()-metoden.
  • Den enda SignalRService resursen har hämtats.
  • Egenskapen SignalRService.Sku tilldelas ett namn på Premium_P1 och en kapacitet på 10.
  • Egenskapen SignalRService.PublicNetworkAccess är inställd på Enabled.
  • En tagg läggs till i tjänstresursen SignalR med nyckeln ExampleKey och värdet Example value.

Integrering av hubbvärd

Det finns ingen officiell AspireAzureSignalRklientintegrering. Det finns dock begränsat stöd för liknande upplevelser. I dessa scenarier AzureAzure SignalR Service fungerar som en proxy mellan servern (där Hub eller Hub<T> finns) och klienten (där SignalR klienten finns). Dirigerar AzureAzure SignalR Service trafik mellan servern och klienten, vilket möjliggör kommunikation i realtid.

Det finns två paket tillgängliga för, var och en med specifika scenarier som att hantera klientanslutningen till AzureAzure SignalR Serviceoch ansluta till resursen AzureAzure SignalR Service . Kom igång genom att 📦 installera Microsoft.Azure.SignalR NuGet-paket i projektet som är värd för din SignalR hubb.

dotnet add package Microsoft.Azure.SignalR

<PackageReference Include="Microsoft.Azure.SignalR"
                  Version="*" />

Konfigurera med namnet AzureAzure SignalR Service i standardläge

I standardläge måste ditt förbrukande projekt förlita sig på en namngiven AzureAzure SignalR Service resurs. Tänk på följande diagram som illustrerar arkitekturen AzureAzure SignalR Service för i standardläge :

Mer information om standardläge finns i AzureAzure SignalR Service: Standardläge.

I ditt hubbvärdsprojekt SignalR konfigurerar du AzureAzure SignalR Service genom att kedja anrop till .AddSignalR().AddNamedAzureSignalR("name"):

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Metoden AddNamedAzureSignalR konfigurerar projektet för att använda resursen AzureAzure SignalR Service med namnet signalr. Anslutningssträngen läses från konfigurationsnyckeln ConnectionStrings:signalroch ytterligare inställningar läses in från konfigurationsavsnittet Azure:SignalR:signalr .

Konfigurera AzureAzure SignalR Service i serverlöst läge

Om du använder AppHost med AzureSignalR emulatorn måste du också installera 📦 Microsoft..AzureSignalR. NuGet-hanteringspaket.

dotnet add package Microsoft.Azure.SignalR.Management

<PackageReference Include="Microsoft.Azure.SignalR.Management"
                  Version="*" />

Azure SignalR Serverlöst läge kräver inte att en hubbserver körs. Azure Azure SignalR Service Ansvarar för att underhålla klientanslutningar. I det här läget kan du dessutom inte använda traditionella SignalR hubbar, till exempel Hub, Hub<T>eller IHubContext<THub>. Konfigurera i stället en överordnad slutpunkt som vanligtvis är en Azure funktionsutlösareSignalR. Tänk på följande diagram som illustrerar arkitekturen AzureAzure SignalR Service i i serverlöst läge:

Mer information om serverlöst läge finns i AzureAzure SignalR Service: Serverlöst läge.

I ett projekt som är avsett att kommunicera med AzureAzure SignalR Serviceregistrerar du lämpliga tjänster genom att anropa AddSignalR och sedan registrera ServiceManager med hjälp av anslutningssträngen signalr och lägga till en /negotiate slutpunkt:

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

Föregående kod konfigurerar AzureAzure SignalR Service med hjälp av ServiceManagerBuilder-klassen, men anropar inte AddSignalR eller MapHub. Dessa två tillägg krävs inte i serverlöst läge. Anslutningssträngen läses från konfigurationsnyckeln ConnectionStrings:signalr. När du använder emulatorn är endast HTTP-slutpunkten tillgänglig. I appen kan du använda instansen ServiceManager för att skapa en ServiceHubContext. ServiceHubContext Används för att sända meddelanden och hantera anslutningar till klienter.

Slutpunkten /negotiate krävs för att upprätta en anslutning mellan den anslutande klienten och AzureAzure SignalR Service. ServiceHubContext Skapas med hjälp av ServiceManager.CreateHubContextAsync metoden, som tar hubbnamnet som en parameter. Metoden NegotiateAsync anropas för att förhandla anslutningen med AzureAzure SignalR Service, som returnerar en åtkomsttoken och URL:en för klienten att ansluta till.

Mer information finns i Använda AzureSignalR hanterings-SDK.

Se även

• Azure Azure SignalR Service översikt
• Skala ASP.NET CoreSignalR applikationer med AzureAzure SignalR Service
• översikt över AspireAzure integreringar
• Aspire Integrationer
• Aspire GitHub Repo