Aspire Azure Web PubSub samverkan

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

Azure Web PubSub är en fullständigt hanterad meddelandetjänst i realtid som gör att du kan skapa webbprogram i realtid med hjälp av WebSockets och publicera prenumerationsmönster. Med integreringen AspireAzureWeb PubSub kan du ansluta till AzureWeb PubSub instanser från dina .NET program.

Integrering av värdtjänster

Hostingintegration AspireAzure Web PubSub modellerar Web PubSub resurserna som följande typer:

• AzureWebPubSubResource: Representerar en AzureWeb PubSub resurs, inklusive anslutningsinformation till den underliggande Azure resursen.
• AzureWebPubSubHubResource: Representerar en resurs för Web PubSub hubbinställningar som innehåller inställningarna för en hubb. Du kan till exempel ange om hubben tillåter anonyma anslutningar eller lägger till händelsehanterare i hubben.

Om du vill komma åt dessa typer och API:er för att uttrycka dem i ditt AppHost-projekt installerar du 📦Aspire. Hosting.Azure. NuGet-paketet WebPubSub :

dotnet add package Aspire.Hosting.Azure.WebPubSub

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

För mer information, se dotnet add package eller hantera paketberoenden i .NET applikationer.

Lägga till en AzureWeb PubSub resurs

Om du vill lägga till en AzureWeb PubSub resurs i ditt AppHost-projekt anropar AddAzureWebPubSub du metoden med ett namn:

var builder = DistributedApplication.CreateBuilder(args);

var webPubSub = builder.AddAzureWebPubSub("web-pubsub");

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

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

Föregående kod lägger till en AzureWeb PubSub resurs med namnet web-pubsub till AppHost-projektet. Metoden WithReference skickar anslutningsinformationen till ExampleProject-projektet.

Lägga till en AzureWeb PubSub hubbresurs

När du lägger till en AzureWeb PubSub resurs kan du också lägga till en underordnad hubbresurs. Hubbresursen är en logisk gruppering av anslutningar och händelsehanterare. Om du vill lägga till en AzureWeb PubSub hubbresurs i ditt AppHost-projekt kedjar du ett anrop till metoden AddHub som tillhandahåller en resurs och ett hubbnamn:

var builder = DistributedApplication.CreateBuilder(args);

var worker = builder.AddProject<Projects.WorkerService>("worker")
                    .WithExternalHttpEndpoints();

var webPubSub = builder.AddAzureWebPubSub("web-pubsub");
var messagesHub = webPubSub.AddHub(name: "messages", hubName: "messageHub");

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

Föregående kod lägger till en AzureWeb PubSub hubbresurs med namnet messages och hubbnamnet messageHub , som möjliggör tillägg av händelsehanterare. Om du vill lägga till en händelsehanterare anropar du AddEventHandler:

var builder = DistributedApplication.CreateBuilder(args);

var worker = builder.AddProject<Projects.WorkerService>("worker")
                    .WithExternalHttpEndpoints();

var webPubSub = builder.AddAzureWebPubSub("web-pubsub");
var messagesHub = webPubSub.AddHub(name: "messages", hubName: "messageHub");

messagesHub.AddEventHandler(
    $"{worker.GetEndpoint("https")}/eventhandler/",
    systemEvents: ["connected"]);

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

Föregående kod lägger till ett arbetstjänstprojekt med namnet worker med en extern HTTP-slutpunkt. Hubben med namnet messages resurs läggs till i resursen web-pubsub och en händelsehanterare läggs till i den messagesHub resursen. Händelsehanterar-URL:en är inställd på arbetstjänstens externa HTTP-slutpunkt. För mer information, se AzureWeb PubSub händelsehanterare.

Ansluta till en befintlig AzureWeb PubSub-instans

Du kan ha en befintlig AzureWeb PubSub tjänst som du vill ansluta till. Du kan kedja en anropning för att annotera att din AzureWebPubSubResource är en befintlig resurs:

var builder = DistributedApplication.CreateBuilder(args);

var existingPubSubName = builder.AddParameter("existingPubSubName");
var existingPubSubResourceGroup = builder.AddParameter("existingPubSubResourceGroup");

var webPubSub = builder.AddAzureWebPubSub("web-pubsub")
                       .AsExisting(existingPubSubName, existingPubSubResourceGroup);

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

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

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

Konfigurationsgenererad Bicep

När du publicerar din app Aspire genererar etablerings-API:er Bicep tillsammans med manifestfilen. Bicep är ett domänspecifikt språk för att definiera Azure resurser. Mer information finns i Bicep Overview.

När du lägger till en AzureWeb PubSub resurs genereras följande Bicep:

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

param sku string = 'Free_F1'

param capacity int = 1

param messages_url_0 string

resource web_pubsub 'Microsoft.SignalRService/webPubSub@2024-03-01' = {
  name: take('webpubsub-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: sku
    capacity: capacity
  }
  tags: {
    'aspire-resource-name': 'web-pubsub'
  }
}

resource messages 'Microsoft.SignalRService/webPubSub/hubs@2024-03-01' = {
  name: 'messages'
  properties: {
    eventHandlers: [
      {
        urlTemplate: messages_url_0
        userEventPattern: '*'
        systemEvents: [
          'connected'
        ]
      }
    ]
  }
  parent: web_pubsub
}

output endpoint string = 'https://${web_pubsub.properties.hostName}'

output name string = web_pubsub.name

Tidigare Bicep är en modul som tillhandahåller en AzureWeb PubSub 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 web_pubsub_outputs_name string

param principalType string

param principalId string

resource web_pubsub 'Microsoft.SignalRService/webPubSub@2024-03-01' existing = {
  name: web_pubsub_outputs_name
}

resource web_pubsub_WebPubSubServiceOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(web_pubsub.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '12cf5a90-567b-43ae-8102-96cf46c7d9b4'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '12cf5a90-567b-43ae-8102-96cf46c7d9b4')
    principalType: principalType
  }
  scope: web_pubsub
}

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. Den här typen möjliggör anpassning av den genererade Bicep genom att tillhandahålla ett flytande API för konfigurering av Azure-resurser med hjälp av ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-APIet. Du kan till exempel konfigurera kind, consistencyPolicy, locationsoch mycket mer. I följande exempel visas hur du anpassar AzureAzure Cosmos DB resursen:

builder.AddAzureWebPubSub("web-pubsub")
    .ConfigureInfrastructure(infra =>
    {
        var webPubSubService = infra.GetProvisionableResources()
                                    .OfType<WebPubSubService>()
                                    .Single();

        webPubSubService.Sku.Name = "Standard_S1";
        webPubSubService.Sku.Capacity = 5;
        webPubSubService.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 WebPubSubService resursen har hämtats.
  • Det WebPubSubService.Sku objektet har sina namn- och kapacitetsegenskaper inställda på Standard_S1 respektive 5.
  • En tagg läggs till i den Web PubSub resursen med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa Web PubSub resursen. Mer information finns i Azure.Provisioning.WebPubSub. För mer information, se Azure.Provisioning anpassning.

Client integration

Klientintegrering AspireAzureWeb PubSub används för att ansluta till en AzureWeb PubSub-tjänst med hjälp av WebPubSubServiceClient. Kom igång med klientintegrering av AspireAzureWeb PubSub-tjänsten genom att installera 📦Aspire.Azure. Messaging.WebPubSub NuGet-paket i programmet.

dotnet add package Aspire.Azure.Messaging.WebPubSub

<PackageReference Include="Aspire.Azure.Messaging.WebPubSub"
                  Version="*" />

Web PubSub klienttyper som stöds

Följande Web PubSub klienttyper stöds av biblioteket:

Lägg till Web PubSub klient

I den Program.cs filen för ditt klientkrävande projekt anropar du AddAzureWebPubSubServiceClient-tilläggsmetoden för att registrera en WebPubSubServiceClient för användning via containern för beroendeinmatning. Metoden tar en parameter för anslutningsnamn:

builder.AddAzureWebPubSubServiceClient(
    connectionName: "web-pubsub");

När du har lagt till WebPubSubServiceClient, kan du hämta klientinstansen genom beroendeinjektion. Om du till exempel vill hämta datakällobjektet från en exempeltjänst definierar du det som en konstruktorparameter och kontrollerar att klassen ExampleService är registrerad med containern för beroendeinmatning:

public class ExampleService(WebPubSubServiceClient client)
{
    // Use client...
}

Mer information finns i:

• sv-SE: Azure. För .Messaging.WebPubSub-dokumentation, se för exempel på hur du använder WebPubSubServiceClient.
• Beroendeinjektion i .NET för mer information om beroendeinjektion.

Lägg till kodad Web PubSub-klient

Det kan finnas situationer där du vill registrera flera WebPubSubServiceClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade Web PubSub klienter anropar du metoden AddKeyedAzureWebPubSubServiceClient:

builder.AddKeyedAzureWebPubSubServiceClient(name: "messages");
builder.AddKeyedAzureWebPubSubServiceClient(name: "commands");

Sedan kan du hämta klientinstanserna med hjälp av dependency injection. Om du till exempel vill hämta klienterna från en tjänst:

public class ExampleService(
    [KeyedService("messages")] WebPubSubServiceClient messagesClient,
    [KeyedService("commands")] WebPubSubServiceClient commandsClient)
{
    // Use clients...
}

Om du vill registrera en enskild WebPubSubServiceClient-instans med ett specifikt anslutningsnamn finns det en överbelastning som använder anslutningsnamnet som tjänstnyckel. Anropa AddKeyedAzureWebPubSubServiceClient metoden. Den här metoden registrerar klienten som en singleton-tjänst i beroendeinjektionscontainern.

builder.AddKeyedAzureWebPubSubServiceClient(connectionName: "web-pubsub");

Mer information finns i Nyckelade tjänster i .NET.

Konfiguration

Aspire Azure Web PubSub-biblioteket innehåller flera alternativ för att konfigurera AzureWeb PubSub-anslutningen baserat på kraven och konventionerna i projektet. Antingen en Endpoint eller en ConnectionString måste anges.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar AddAzureWebPubSubServiceClient:

builder.AddAzureWebPubSubServiceClient(
    "web-pubsub",
    settings => settings.HubName = "your_hub_name");

Anslutningsinformationen hämtas från avsnittet ConnectionStrings konfiguration. Två anslutningsformat stöds:

• Tjänstslutpunkt (rekommenderas): Använder tjänstslutpunkten med DefaultAzureCredential.

  {
    "ConnectionStrings": {
      "web-pubsub": "https://{account_name}.webpubsub.azure.com"
    }
  }
  

• Anslutningssträng: Innehåller en åtkomstnyckel.

  {
    "ConnectionStrings": {
      "web-pubsub": "Endpoint=https://{account_name}.webpubsub.azure.com;AccessKey={account_key}"
    }
  }
  

Använda konfigurationsprovidrar

Biblioteket stöder Microsoft.Extensions.Configuration. Den läser in inställningar från konfigurationen med hjälp av Aspire:Azure:Messaging:WebPubSub-nyckeln:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "WebPubSub": {
          "DisableHealthChecks": true,
          "HubName": "your_hub_name"
        }
      }
    }
  }
}

Det fullständiga AzureOpenAI klientintegreringsschemat JSON finns i Aspire.Azure. Messaging.WebPubSub/ConfigurationSchema.json.

Använda namngiven konfiguration

Integreringen AspireAzureWeb PubSub stöder namngiven konfiguration, vilket gör att du kan konfigurera flera instanser av samma resurstyp med olika inställningar. Den namngivna konfigurationen använder anslutningsnamnet som en nyckel under huvudkonfigurationsavsnittet.

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "WebPubSub": {
          "webpubsub1": {
            "HubName": "hub1",
            "DisableHealthChecks": true
          },
          "webpubsub2": {
            "HubName": "hub2",
            "DisableHealthChecks": false
          }
        }
      }
    }
  }
}

I det här exemplet kan anslutningsnamnen webpubsub1 och webpubsub2 användas när du anropar AddAzureWebPubSubServiceClient:

builder.AddAzureWebPubSubServiceClient("webpubsub1");
builder.AddAzureWebPubSubServiceClient("webpubsub2");

Den namngivna konfigurationen har företräde framför konfigurationen på den översta nivån. Om båda anges åsidosätter inställningarna från den namngivna konfigurationen inställningarna på den översta nivån.

Använd inline-delegater

Du kan konfigurera inställningar direkt.

builder.AddAzureWebPubSubServiceClient(
    "web-pubsub",
    settings => settings.DisableHealthChecks = true);

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Aspire Azure Web PubSub-integreringen använder följande loggkategorier:

• Azure
• Azure.Core
• Azure.Identity
• Azure.Messaging.WebPubSub

Spårning

Integreringen AspireAzureWeb PubSub genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• Azure.Messaging.WebPubSub.*

Mått

Den AspireAzureWeb PubSub integreringen stöder för närvarande inte mått som standard på grund av begränsningar med Azure SDK för .NET. Om detta ändras i framtiden uppdateras det här avsnittet för att återspegla dessa ändringar.

Se även

• Azure Web PubSub
• Aspire Integrationer
• Aspire GitHub Repo