Delen via

integratie van .NET AspireAzureWeb PubSub

Inclusief:Hostingintegratie inbegrepen —&— Client integratie inbegrepenClient 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 .NET AspireAzureWeb PubSub integratie kunt u vanuit uw Azure toepassingen verbinding maken met Web PubSub.NET exemplaren.

Hostingintegratie

De .NET.NET AspireAzure Web PubSub hosting integratie modelleren 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 de bijbehorende API's binnen uw app-hostproject, installeer het 📦Aspire.Hosting.Azure.WebPubSub NuGet-pakket:

dotnet add package Aspire.Hosting.Azure.WebPubSub

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 app-hostproject, 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 app-hostproject. De methode WithReference geeft de verbindingsgegevens door aan het ExampleProject-project.

Belangrijk

Wanneer u AddAzureWebPubSubaanroept, wordt impliciet AddAzureProvisioning(IDistributedApplicationBuilder)aangeroepen. Hiermee wordt ondersteuning toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokale inrichting: Configuratievoor meer informatie.

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 app-hostproject, koppelt u een aanroep aan de AddHub methode die een resource- en hubnaam oplevert:

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.

Provisioning-gegenereerde Bicep

Wanneer u uw app publiceert, .NET.NET 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
  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 .NET 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:

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.

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.

Opmerking

Als alternatief voor het representeren van een Azure AI Search-resource, kunt u een verbindingsreeks toevoegen aan de app-host. Deze benadering is zwak getypt en werkt niet met roltoewijzingen of infrastructuuraanpassingen. Voor meer informatie, zie Bestaande Azure resources toevoegen met verbindingsreeksen.

integratie Client

De .NET 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 .NET AspireAzureWeb PubSub serviceclientintegratie, installeer het 📦Aspire.Azure.Messaging.WebPubSub NuGet-pakket in de toepassing.

dotnet add package Aspire.Azure.Messaging.WebPubSub

Ondersteunde Web PubSub clienttypen

De volgende Web PubSub clienttypen worden ondersteund door de bibliotheek:

Azure cliënttype opties klasse Azure .NET .NET Aspire-instellingenklasse
WebPubSubServiceClient WebPubSubServiceClientOptions AzureMessagingWebPubSubSettings

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

Hint

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Web PubSub resource in het app-hostproject. Zie Een AzureWeb PubSub-resource toevoegenvoor meer informatie.

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:

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

Belangrijk

Wanneer u sleutelservices gebruikt, wordt verwacht dat uw Web PubSub resource twee benoemde hubs heeft geconfigureerd, één voor de messages hub en één voor de 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 .NET 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.

Gebruik inline-delegaten

U kunt instellingen inline configureren:

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

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch configuraties in voor logging, tracing en metrics, die ook wel bekendstaan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. 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 .NET AspireAzureWeb PubSub-integratie maakt gebruik van de volgende logboekcategorieën:

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

Opsporing

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

  • Azure.Messaging.WebPubSub.*

Statistieken

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