integratie van AspireAzureWeb PubSub

Inclusief: —&— Client integratie

Azure Web PubSub is een volledig beheerde realtime berichtenservice waarmee u realtime webtoepassingen kunt bouwen met behulp van WebSockets en patronen voor publiceren/abonneren. Met de AspireAzureWeb PubSub integratie kunt u vanuit uw Azure toepassingen verbinding maken met Web PubSub.NET exemplaren.

Hostingintegratie

De AspireAzure Web PubSub hostingintegratie modelleert de Web PubSub resources als de volgende typen:

• AzureWebPubSubResource: Vertegenwoordigt een AzureWeb PubSub resource, inclusief verbindingsgegevens met de onderliggende Azure resource.
• AzureWebPubSubHubResource: Vertegenwoordigt een Web PubSub hubinstellingenresource, die de instellingen voor een hub bevat. U kunt bijvoorbeeld opgeven of de hub anonieme verbindingen toestaat of gebeurtenis-handlers toevoegt aan de hub.

Als u toegang wilt krijgen tot deze typen en API's voor het uitdrukken ervan in uw AppHost-project , installeert u het 📦Aspire. Hosting.Azure. WebPubSub NuGet-pakket:

dotnet add package Aspire.Hosting.Azure.WebPubSub

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Een AzureWeb PubSub-resource toevoegen

Als u een AzureWeb PubSub resource wilt toevoegen aan uw AppHost-project, roept u de AddAzureWebPubSub methode aan die een naam oplevert:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Met de voorgaande code wordt een AzureWeb PubSub resource met de naam web-pubsub toegevoegd aan het AppHost-project. De methode WithReference geeft de verbindingsgegevens door aan het ExampleProject-project.

Azure Web PubSub Een hubresource toevoegen

Wanneer u een AzureWeb PubSub bron toevoegt, kunt u ook een kinderhubbron toevoegen. De hubresource is een logische groepering van verbindingen en gebeurtenis-handlers. Als u een AzureWeb PubSub hubresource wilt toevoegen aan uw AppHost-project, koppelt u een aanroep aan de AddHub methode op basis van een resource en hubnaam:

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

Met de voorgaande code wordt een AzureWeb PubSub hubresource met de naam messages en een hubnaam toegevoegd messageHub , waarmee gebeurtenis-handlers kunnen worden toegevoegd. Als u een gebeurtenis-handler wilt toevoegen, roept u het AddEventHandlervolgende aan:

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

Met de voorgaande code wordt een werkserviceproject met de naam worker toegevoegd met een extern HTTP-eindpunt. De hub met de naam messages resource wordt toegevoegd aan de web-pubsub resource en er wordt een gebeurtenis-handler toegevoegd aan de messagesHub resource. De URL van de gebeurtenis-handler is ingesteld op het externe HTTP-eindpunt van de werkersdienst. Voor meer informatie, zie AzureWeb PubSub gebeurtenishandlers.

Verbinding maken met een bestaand AzureWeb PubSub exemplaar

Mogelijk hebt u een bestaande AzureWeb PubSub-service waarmee u verbinding wilt maken. U kunt een aanroep aaneenschakelen om aan te geven dat uw AzureWebPubSubResource een bestaande resource is.

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

Zie Azurevoor meer informatie over het behandelen van Web PubSubAzure bronnen als bestaande.

Provisioning-gegenereerde Bicep

Wanneer u uw app publiceert, Aspire genereren de inrichtings-API's Bicep naast het manifestbestand. Bicep is een domeinspecifieke taal voor het definiëren van Azure resources. Zie Bicep Overview voor meer informatie.

Wanneer u een AzureWeb PubSub resource toevoegt, wordt de volgende Bicep gegenereerd:

@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

De bovengenoemde Bicep is een module die een AzureWeb PubSub bron inricht. Daarnaast worden roltoewijzingen gemaakt voor de Azure resource in een afzonderlijke module:

@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
}

De gegenereerde Bicep is een beginpunt en wordt beïnvloed door wijzigingen aan de voorzieningsinfrastructuur in C#. Aanpassingen aan het Bicep-bestand zullen direct overschreven worden, dus breng wijzigingen aan via de C#-inrichtings-API's zodat ze weerspiegeld worden in de gegenereerde bestanden.

Voorzieningsinfrastructuur personaliseren

Alle AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen door een vloeiende API te bieden waarmee u de Azure-resources kunt configureren, met behulp van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. U kunt bijvoorbeeld de kind, consistencyPolicy, locationsen meer configureren. In het volgende voorbeeld ziet u hoe u de AzureAzure Cosmos DB-resource aanpast:

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

De voorgaande code:

• Koppelt een aanroep naar de ConfigureInfrastructure-API:
  • De parameter infra is een exemplaar van het AzureResourceInfrastructure type.
  • De voorzienbare resources worden opgehaald door middel van de GetProvisionableResources() methode.
  • De enkele resource WebPubSubService wordt opgehaald.
  • Voor het WebPubSubService.Sku object zijn respectievelijk de naam- en capaciteitseigenschappen ingesteld op Standard_S1 en 5, respectievelijk.
  • Er wordt een tag toegevoegd aan de Web PubSub resource met een sleutel van ExampleKey en een waarde van Example value.

Er zijn nog veel meer configuratieopties beschikbaar om de Web PubSub resource aan te passen. Zie Azure.Provisioning.WebPubSub voor meer informatie. Zie Azure.Provisioning aanpassingvoor meer informatie.

integratie Client

De AspireAzureWeb PubSub clientintegratie wordt gebruikt om verbinding te maken met een AzureWeb PubSub service met behulp van de WebPubSubServiceClient. Om aan de slag te gaan met de AspireAzureWeb PubSub serviceclientintegratie, installeer het 📦Aspire.Azure.Messaging.WebPubSub NuGet-pakket in de toepassing.

dotnet add package Aspire.Azure.Messaging.WebPubSub

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

Ondersteunde Web PubSub clienttypen

De volgende Web PubSub clienttypen worden ondersteund door de bibliotheek:

Web PubSub-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddAzureWebPubSubServiceClient extensiemethode aan om een WebPubSubServiceClient te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een parameter voor de verbindingsnaam:

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

Nadat u de WebPubSubServiceClienthebt toegevoegd, kunt u de clientinstantie ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld uw gegevensbronobject wilt ophalen uit een voorbeeldservice, definieert u het als een constructorparameter en zorgt u ervoor dat de klasse ExampleService is geregistreerd bij de container voor afhankelijkheidsinjectie:

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

Zie voor meer informatie:

• Azure. Messaging.WebPubSub-documentatie voor voorbeelden van hoe je de WebPubSubServiceClient kunt gebruiken.
• Afhankelijkheidsinjectie in .NET voor meer informatie over afhankelijkheidsinjectie.

Keyed Web PubSub-client toevoegen

Er kunnen situaties zijn waarin u meerdere WebPubSubServiceClient exemplaren met verschillende verbindingsnamen wilt registreren. Om kliënten met sleutel Web PubSub te registreren, roept u de methode AddKeyedAzureWebPubSubServiceClient op.

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

Vervolgens kunt u de clientexemplaren ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld om de clients op te halen uit een service:

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

Als u één WebPubSubServiceClient exemplaar wilt registreren met een specifieke verbindingsnaam, is er een overbelasting die gebruikmaakt van de verbindingsnaam als de servicesleutel. Roep de AddKeyedAzureWebPubSubServiceClient methode aan. Met deze methode wordt de client geregistreerd als een singleton-service in de container voor afhankelijkheidsinjectie.

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

Zie Keyed-services in .NETvoor meer informatie.

Configuratie

De AspireAzureWeb PubSub-bibliotheek biedt meerdere opties voor het configureren van de AzureWeb PubSub verbinding op basis van de vereisten en conventies van uw project. Of een Endpoint of een ConnectionString moet worden opgegeven.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van AddAzureWebPubSubServiceClient:

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

De verbindingsgegevens worden opgehaald uit de ConnectionStrings configuratiesectie. Er worden twee verbindingsindelingen ondersteund:

• Service-eindpunt (aanbevolen): maakt gebruik van het service-eindpunt met DefaultAzureCredential.

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

• Verbindingsreeks: bevat een toegangssleutel.

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

Configuratieproviders gebruiken

De bibliotheek ondersteunt Microsoft.Extensions.Configuration. Er worden instellingen uit de configuratie geladen met behulp van de Aspire:Azure:Messaging:WebPubSub sleutel:

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

Voor het volledige AzureOpenAI client integratieschema JSON, zie Aspire.Azure.Messaging.WebPubSub/ConfigurationSchema.json.

Benoemde configuratie gebruiken

De AspireAzureWeb PubSub integratie ondersteunt benoemde configuratie, waarmee u meerdere exemplaren van hetzelfde resourcetype met verschillende instellingen kunt configureren. De benoemde configuratie maakt gebruik van de verbindingsnaam als een sleutel in het hoofdgedeelte van de configuratie.

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

In dit voorbeeld kunnen de webpubsub1 en webpubsub2 verbindingsnamen worden gebruikt wanneer AddAzureWebPubSubServiceClient wordt aangeroepen:

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

Benoemde configuratie heeft voorrang op de configuratie op het hoogste niveau. Als beide zijn opgegeven, overschrijven de instellingen van de benoemde configuratie de instellingen op het hoogste niveau.

Gebruik inline-delegaten

U kunt instellingen inline configureren:

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

Waarneembaarheid en telemetrie

Aspire Integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrische gegevens in, die ook wel de pijlers van waarneembaarheid worden genoemd. Zie het overzicht van integratieobserveerbaarheid en telemetrie voor meer informatie over integratieobserveerbaarheid en telemetrieAspire. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De AspireAzureWeb PubSub-integratie maakt gebruik van de volgende logboekcategorieën:

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

Opsporing

De integratie van AspireAzureWeb PubSub verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• Azure.Messaging.WebPubSub.*

Statistieken

De AspireAzureWeb PubSub integratie biedt momenteel geen ondersteuning voor metrische gegevens vanwege beperkingen met de Azure SDK voor .NET. Als deze wijzigingen in de toekomst worden gewijzigd, wordt deze sectie bijgewerkt om deze wijzigingen weer te geven.

Zie ook

• Azure Web PubSub
• Aspire Integraties
• Aspire GitHub Repo