.NET Aspire Azure Service Bus integrering

Artikel
02/27/2025

omfattar: Hosting-integration och Client integrering

Azure Service Bus är en fullständigt hanterad meddelandemäklare för företag med meddelandeköer och ämnen för publicering och prenumeration. Med integreringen .NET AspireAzure Service Bus kan du ansluta till Azure Service Bus instanser från .NET program.

Integrering av värdtjänster

.NET .NET Aspire Azure Service Bus som är värd för integrering modellerar de olika Service Bus-resurserna som följande typer:

AzureServiceBusResource: Representerar en Azure Service Bus resurs.
AzureServiceBusEmulatorResource: Representerar en Azure Service Bus emulator-resurs.

Om du vill komma åt dessa typer och API:er för att uttrycka dem, lägg till 📦Aspire.Hosting.Azure.ServiceBus NuGet-paketet i appens värdprojekt.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

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

Lägga till Azure Service Bus resurs

I värdprojektet för appen anropar du AddAzureServiceBus för att lägga till och returnera en Azure Service Bus resursbyggare.

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");

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

När du lägger till en AzureServiceBusResource i appvärden exponeras andra användbara API:er för att lägga till köer och ämnesområden. Med andra ord måste du lägga till en AzureServiceBusResource innan du lägger till någon av de andra Service Bus-resurserna.

Viktig

När du anropar AddAzureServiceBusanropas implicit AddAzureProvisioning– vilket ger stöd för att generera Azure resurser dynamiskt under appstarten. Appen måste konfigurera lämplig prenumeration och plats. Mer information finns i Configuration.

Genererad Bicep-konfiguration

Om du inte har använt Bicep tidigare är det ett domänspecifikt språk för att definiera Azure resurser. Med .NET.NET Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app genereras Bicep-filen tillsammans med manifestfilen. När du lägger till en Azure Service Bus resurs genereras följande Bicep:

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

param sku string = 'Standard'

param principalType string

param principalId string

resource service_bus 'Microsoft.ServiceBus/namespaces@2024-01-01' = {
  name: take('servicebus-${uniqueString(resourceGroup().id)}', 50)
  location: location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'service-bus'
  }
}

resource service_bus_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(service_bus.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: service_bus
}

output serviceBusEndpoint string = service_bus.properties.serviceBusEndpoint

Föregående Bicep är en modul som etablerar ett Azure Service Bus namnområde med följande standardvärden:

sku: SKU:n för Service Bus-namnområdet. Standardvärdet är Standard.
location: Platsen för Service Bus-namnområdet. Standardvärdet är resursgruppens plats.

Förutom Service Bus-namnområdet etablerar det även en Azure rollbaserad åtkomstkontroll (Azure RBAC) inbyggd roll för Azure Service Bus dataägare. Rollen tilldelas till Service Bus-namnområdets resursgrupp. För mer information, se Azure Service Bus Datansvarig.

Anpassa tillhandahållandeinfrastruktur

Alla .NET AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör att den genererade Bicep kan anpassas genom att tillhandahålla ett tydligt API för att konfigurera Azure-resurserna med hjälp av ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API:et. Du kan till exempel konfigurera sku:n, platsen med mera. I följande exempel visas hur du anpassar Azure Service Bus resursen:

builder.AddAzureServiceBus("service-bus")
    .ConfigureInfrastructure(infra =>
    {
        var serviceBusNamespace = infra.GetProvisionableResources()
                                       .OfType<ServiceBusNamespace>()
                                       .Single();

        serviceBusNamespace.Sku = new ServiceBusSku
        {
            Tier = ServiceBusSkuTier.Premium
        };
        serviceBusNamespace.Tags.Add("ExampleKey", "Example value");
    });

Föregående kod:

Kedjar ett anrop till ConfigureInfrastructure-API:et:
- Infraparametern är en instans av den AzureResourceInfrastructure typen.
- De tillgängliga resurserna hämtas genom att anropa GetProvisionableResources()-metoden.
- Den enstaka ServiceBusNamespace hämtas.
- Den ServiceBusNamespace.Sku som skapats med en ServiceBusSkuTier.Premium
- En tagg läggs till i Service Bus-namnområdet med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa Azure Service Bus resursen. Mer information finns i Azure.Provisioning.ServiceBus. Mer information finns i Azure. Anpassning av provisionering.

Ansluta till ett befintligt Azure Service Bus namnområde

Du kan ha ett befintligt Azure Service Bus namnområde som du vill ansluta till. I stället för att representera en ny Azure Service Bus resurs kan du lägga till en anslutningssträng till appvärden. Om du vill lägga till en anslutning till ett befintligt Azure Service Bus namnområde anropar du metoden AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddConnectionString("messaging");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(serviceBus);

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

Notera

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Anslutningssträngen konfigureras i appvärdens konfiguration, vanligtvis under Användarhemligheter, under avsnittet ConnectionStrings. Appvärden injekterar den här anslutningssträngen som en miljövariabel i alla resurser som är beroende, till exempel:

{
    "ConnectionStrings": {
        "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={key_name};SharedAccessKey={key_value};"
    }
}

Den beroende resursen kan komma åt den inmatade anslutningssträngen genom att anropa metoden GetConnectionString och skicka anslutningsnamnet som parameter, i det här fallet "messaging". API:et GetConnectionString är en förkortning för IConfiguration.GetSection("ConnectionStrings")[name].

Lägg till Azure Service Bus i kön

Om du vill lägga till en Azure Service Bus kö anropar du metoden AddServiceBusQueue på IResourceBuilder<AzureServiceBusResource>:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusQueue("queue");

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

När du anropar AddServiceBusQueue(IResourceBuilder<AzureServiceBusResource>, String, String)konfigurerar den dina Service Bus-resurser att ha en kö med namnet queue. Kön skapas i Service Bus-namnområdet som representeras av AzureServiceBusResource som du lade till tidigare. Mer information finns i Köer, ämnen och prenumerationer i Azure Service Bus.

Lägg till Azure Service Bus ämne och prenumeration

Om du vill lägga till ett Azure Service Bus ämne anropar du metoden AddServiceBusTopic på IResourceBuilder<AzureServiceBusResource>:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusTopic("topic");

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

När du anropar AddServiceBusTopic(IResourceBuilder<AzureServiceBusResource>, String, String)konfigureras dina Service Bus-resurser så att de har ett ämne med namnet topic. Ämnet skapas i Service Bus-namnområdet som representeras av AzureServiceBusResource som du lade till tidigare.

Om du vill lägga till en prenumeration för ämnet anropar du metoden AddServiceBusSubscription på IResourceBuilder<AzureServiceBusTopicResource> och konfigurerar den med hjälp av metoden WithProperties:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
var topic = serviceBus.AddServiceBusTopic("topic");
topic.AddServiceBusSubscription("sub1")
     .WithProperties(subscription =>
     {
         subscription.MaxDeliveryCount = 10;
         subscription.Rules.Add(
             new AzureServiceBusRule("app-prop-filter-1")
             {
                 CorrelationFilter = new()
                 {
                     ContentType = "application/text",
                     CorrelationId = "id1",
                     Subject = "subject1",
                     MessageId = "msgid1",
                     ReplyTo = "someQueue",
                     ReplyToSessionId = "sessionId",
                     SessionId = "session1",
                     SendTo = "xyz"
                 }
             });
     });

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

Föregående kod lägger inte bara till ett ämne och skapar och konfigurerar en prenumeration med namnet sub1 för ämnet. Prenumerationen har ett maximalt leveransantal på 10 och en regel med namnet app-prop-filter-1. Regeln är ett korrelationsfilter som filtrerar meddelanden baserat på egenskaperna ContentType, CorrelationId, Subject, MessageId, ReplyTo, ReplyToSessionId, SessionIdoch SendTo.

Mer information finns i Köer, ämnen och prenumerationer i Azure Service Bus.

Lägga till Azure Service Bus emulatorresurs

Om du vill lägga till en Azure Service Bus emulatorresurs genom att kedja ett anrop på en <IResourceBuilder<AzureServiceBusResource>> till RunAsEmulator-API:et:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsEmulator();

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

När du anropar RunAsEmulatorkonfigureras dina Service Bus-resurser att köras lokalt med hjälp av en emulator. Emulatorn i det här fallet är Azure Service Bus emulatorn. Azure Service Bus-emulatorn ger en kostnadsfri lokal miljö för att testa dina Azure Service Bus-appar och den är en perfekt följeslagare till .NET AspireAzure hosting-integration. Emulatorn är inte installerad, i stället är den tillgänglig för .NET.NET Aspire som en container. När du lägger till en container i appvärden, som du ser i föregående exempel med mcr.microsoft.com/azure-messaging/servicebus-emulator-avbildningen (och den tillhörande mcr.microsoft.com/azure-sql-edge avbildningen), skapas och startas containern när appvärden startar. Mer information finns i Livscykel för containerresurser.

Konfigurera Service Bus-emulatorkontainer

Det finns olika konfigurationer för containerresurser, till exempel kan du konfigurera containerns portar eller tillhandahålla en wholistic JSON konfiguration som åsidosätter allt.

Konfigurera Service Bus-emulatorns värdport för container

Som standard exponerar Service Bus-emulatorcontainern när den konfigureras av .NET.NET Aspireföljande slutpunkter:

Slutpunkt	Bild	Containerhamn	Värdport
`emulator`	`mcr.microsoft.com/azure-messaging/servicebus-emulator`	5672	dynamisk
`tcp`	`mcr.microsoft.com/azure-sql-edge`	1433	dynamisk

Porten som den lyssnar på är dynamisk som standard. När containern startar mappas porten till en slumpmässig port på värddatorn. För att konfigurera slutpunktsporten anropar kedjan containerresursverktyget som tillhandahålls av metoden RunAsEmulator och sedan WithHostPort(IResourceBuilder<AzureServiceBusEmulatorResource>, Nullable<Int32>) enligt följande exempel:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithHostPort(7777);
                         });

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

Föregående kod konfigurerar Service Bus-emulatorns befintliga emulator slutpunkt för att lyssna på port 7777. Service Bus-emulatorcontainerns port mappas till värdporten enligt följande tabell:

Slutpunktsnamn	Portmappning (`container:host`)
`emulator`	`5672:7777`

Konfigurera konfigurationen för Service Bus-emulatorcontainer JSON

Service Bus-emulatorns container körs med en standardfil config.json. Du kan åsidosätta den här filen helt eller uppdatera JSON konfigurationen med en JsonNode representation av konfigurationen.

Om du vill ange en anpassad JSON konfigurationsfil anropar du metoden WithConfigurationFile(IResourceBuilder<AzureServiceBusEmulatorResource>, String):

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfigurationFile(
                                 path: "./messaging/custom-config.json");
                         });

Föregående kod konfigurerar Service Bus-emulatorcontainern så att den använder en anpassad JSON konfigurationsfil som finns på ./messaging/custom-config.json. Om du i stället vill åsidosätta specifika egenskaper i standardkonfigurationen anropar du metoden WithConfiguration(IResourceBuilder<AzureServiceBusEmulatorResource>, Action<JsonNode>):

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfiguration(
                                 (JsonNode configuration) =>
                                 {
                                     var userConfig = configuration["UserConfig"];
                                     var ns = userConfig["Namespaces"][0];
                                     var firstQueue = ns["Queues"][0];
                                     var properties = firstQueue["Properties"];
                                     
                                     properties["MaxDeliveryCount"] = 5;
                                     properties["RequiresDuplicateDetection"] = true;
                                     properties["DefaultMessageTimeToLive"] = "PT2H";
                                 });
                         });

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

Föregående kod hämtar noden UserConfig från standardkonfigurationen. Sedan uppdateras den första köns egenskaper för att ställa in MaxDeliveryCount till 5, RequiresDuplicateDetection till true, och DefaultMessageTimeToLive till 2 hours.

Utför hälsokontroller för integration

Azure Service Bus värdintegrering lägger automatiskt till en hälsokontroll för Service Bus-resursen. Hälsokontrollen verifierar att servicebussen körs och att en anslutning kan upprättas till den.

Värdintegrationen är beroende av 📦 AspNetCore.HealthChecks.AzureServiceBus NuGet-paketet.

Client integration

Kom igång med .NET AspireAzure Service Bus-klientintegrering genom att installera 📦Aspire.Azure. Messaging.ServiceBus NuGet-paket i det klientkrävande projektet, dvs. projektet för programmet som använder Service Bus-klienten. Service Bus-klientintegrering registrerar en ServiceBusClient instans som du kan använda för att interagera med Service Bus.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

Lägg till Service Bus-klient

I Program.cs-filen för ditt klientanvändande projekt anropar du AddAzureServiceBusClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera ServiceBusClient för användning i beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddAzureServiceBusClient(connectionName: "messaging");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till Service Bus-resursen i appvärdprojektet. Med andra ord, när du anropar AddAzureServiceBus och anger ett namn på messaging ska samma namn användas när du anropar AddAzureServiceBusClient. För mer information, se Lägg till Azure Service Bus resurs.

Du kan sedan hämta ServiceBusClient-instansen med hjälp av dependency injection. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till en nycklad Service Bus-klient

Det kan finnas situationer där du vill registrera flera ServiceBusClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade Service Bus-klienter anropar du metoden AddKeyedAzureServiceBusClient:

builder.AddKeyedAzureServiceBusClient(name: "mainBus");
builder.AddKeyedAzureServiceBusClient(name: "loggingBus");

Viktig

När du använder nyckelade tjänster förväntas service bus-resursen konfigurera två namngivna bussar, en för mainBus och en för loggingBus.

Sedan kan du hämta ServiceBusClient-instans genom dependency injection. Om du till exempel vill hämta anslutningen från en exempeltjänst:

public class ExampleService(
    [FromKeyedServices("mainBus")] ServiceBusClient mainBusClient,
    [FromKeyedServices("loggingBus")] ServiceBusClient loggingBusClient)
{
    // Use clients...
}

Mer information om nyckelade tjänster finns under .NET beroendeinjektion: Nyckelade tjänster.

Konfiguration

Den .NET AspireAzure Service Bus integreringen innehåller flera alternativ för att konfigurera anslutningen baserat på kraven och konventionerna i ditt projekt.

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 metoden AddAzureServiceBusClient:

builder.AddAzureServiceBusClient("messaging");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

{
  "ConnectionStrings": {
    "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};"
  }
}

Mer information om hur du formaterar den här anslutningssträngen finns i dokumentationen om ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire- ochAzure Service Bus-integrationen stöder Microsoft.Extensions.Configuration. Den läser in AzureMessagingServiceBusSettings från konfigurationen med hjälp av nyckeln Aspire:Azure:Messaging:ServiceBus. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "ConnectionString": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};",
          "DisableTracing": false
        }
      }
    }
  }
}

Det fullständiga Service Bus-klientintegreringsschemat JSON finns i Aspire.Azure. Messaging.ServiceBus/ConfigurationSchema.json.

Använd infogade delegater

Du kan också skicka delegeringen Action<AzureMessagingServiceBusSettings> configureSettings för att konfigurera vissa eller alla alternativ direkt, till exempel för att inaktivera spårning i koden.

builder.AddAzureServiceBusClient(
    "messaging",
    static settings => settings.DisableTracing = true);

Du kan också konfigurera Azure.Messaging.ServiceBus.ServiceBusClientOptions med hjälp av den valfria Action<ServiceBusClientOptions> configureClientOptions parametern för metoden AddAzureServiceBusClient. Om du till exempel vill sätta ServiceBusClientOptions.Identifier-suffixet för 'user-agent'-huvudet för alla förfrågningar som görs av den här klienten:

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => clientOptions.Identifier = "myapp");

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Integreringen av .NET AspireAzure Service Bus:

Lägger till hälsokontrollen när AzureMessagingServiceBusSettings.DisableTracing är false, vilket försöker ansluta till Service Bus.
Integrerar med HTTP-slutpunkten /health, som anger att alla registrerade hälsokontroller måste godkännas för att appen ska betraktas som redo att ta emot trafik.

Observerbarhet och telemetri

.NET .NET Aspire integreringar ställer automatiskt in konfigurationer för loggning, spårning och mätvärden, som ibland är kända som grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire 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

.NET Aspire Azure Service Bus-integreringen använder följande loggkategorier:

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

Förutom att få Azure Service Bus begärandediagnostik för misslyckade begäranden kan du konfigurera tröskelvärden för svarstid för att avgöra vilken lyckad Azure Service Bus begärandediagnostik som ska loggas. Standardvärdena är 100 ms för punktåtgärder och 500 ms för åtgärder som inte är punktåtgärder.

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => {
            clientOptions.ServiceBusClientTelemetryOptions = new()
            {
                ServiceBusThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Spårning

.NET Aspire Azure Service Bus-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

Azure Service Bus spårning är för närvarande i förhandsversion, så du måste aktivera den experimentella funktionen för att säkerställa att spårningar släpps ut.

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

Mer information finns i Azure Service Bus: Distribuerad spårning och korrelation via Service Bus-meddelanden.

Mått

Den .NET AspireAzure Service Bus integreringen stöder för närvarande inte mått som standard på grund av begränsningar med Azure SDK.

Se även

Azure Service Bus
översikt över .NET.NET Aspire integreringar
översikt över .NET AspireAzure integreringar
.NET Aspire GitHub repo

Dela via