Partager via


.NET AspireAzure Service Bus intégration

Inclut :Intégration de l’hébergement incluse intégration d’hébergement —&— Client intégration incluseClient

Azure Service Bus est un répartiteur de messages d’entreprise entièrement géré avec des files d’attente de messages et des rubriques de publication-abonnement. L’intégration .NET AspireAzure Service Bus vous permet de vous connecter à des instances Azure Service Bus à partir d’applications .NET.

Intégration de l’hébergement

Les modèles d'intégration d'hébergement .NET.NET AspireAzure Service Bus représentent les différentes ressources du Service Bus en tant que types suivants :

Pour accéder à ces types et API pour les exprimer, ajoutez le package NuGet .Hosting..ServiceBus dans le projet hôte d’application.

dotnet add package Aspire.Hosting.Azure.ServiceBus

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de paquets dans les applications .NET.

Ajouter Azure Service Bus ressource

Dans votre projet hôte d’application, appelez AddAzureServiceBus pour ajouter et retourner un générateur de ressources Azure Service Bus.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Lorsque vous ajoutez un AzureServiceBusResource à l’hôte de l’application, il expose d’autres API utiles pour ajouter des files d’attente et des rubriques. En d’autres termes, vous devez ajouter un AzureServiceBusResource avant d’ajouter l’une des autres ressources Service Bus.

Essentiel

Lorsque vous appelez AddAzureServiceBus, il appelle implicitement AddAzureProvisioning, ce qui ajoute la prise en charge de la génération dynamique de ressources Azure pendant le démarrage de l’application. L’application doit configurer l’abonnement et l’emplacement appropriés. Pour plus d’informations, consultez Configuration.

Provisionnement généré par Bicep

Si vous débutez avec Bicep, il s’agit d’un langage spécifique au domaine pour définir des ressources Azure. Avec .NET.NET Aspire, vous n’avez pas besoin d’écrire Bicep manuellement, au lieu de cela, les API d’approvisionnement génèrent Bicep pour vous. Lorsque vous publiez votre application, le fichier Bicep généré est livré en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource Azure Service Bus, le Bicep suivant est généré :

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

param sku string = 'Standard'

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

output serviceBusEndpoint string = service_bus.properties.serviceBusEndpoint

output name string = service_bus.name

Le module Bicep précédent est un module qui provisionne une ressource de namespace Azure Service Bus. En outre, les attributions de rôles sont créées pour la Azure ressource dans un module distinct :

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

param service_bus_outputs_name string

param principalType string

param principalId string

resource service_bus 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: service_bus_outputs_name
}

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
}

En plus de l’espace de noms Service Bus, il provisionne également un rôle intégré de contrôle d’accès en fonction du rôle (Azure RBAC) de Azure propriétaire de données Azure Service Bus. Le rôle est affecté au groupe de ressources de l’espace de noms Service Bus. Pour plus d’informations, consultez Azure Service Bus Propriétaire des données.

Personnaliser l’infrastructure d’approvisionnement

Toutes les ressources .NET AspireAzure sont des sous-classes du type AzureProvisioningResource. Ce type permet de personnaliser le Bicep généré en fournissant une API fluente pour configurer les ressources Azure à l’aide de l’API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Par exemple, vous pouvez configurer la référence SKU, l’emplacement et bien plus encore. L’exemple suivant montre comment personnaliser la ressource Azure Service Bus :

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

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

Code précédent :

Il existe de nombreuses autres options de configuration disponibles pour personnaliser la ressource Azure Service Bus. Pour plus d’informations, consultez Azure.Provisioning.ServiceBus. Pour plus d’informations, consultez Azure. Personnalisation de l’approvisionnement.

Se connecter à un espace de noms Azure Service Bus existant

Vous pouvez avoir un espace de noms Azure Service Bus existant auquel vous souhaitez vous connecter. Chaînez un appel pour annoter que votre AzureServiceBusResource ressource est existante :

var builder = DistributedApplication.CreateBuilder(args);

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

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

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

Pour plus d’informations sur le traitement des Azure Service Bus ressources en tant que ressources existantes, consultez Utiliser des ressources existantesAzure.

Remarque

Plutôt que de représenter une Azure Service Bus ressource, vous pouvez ajouter une chaîne de connexion à l’hébergeur de l’application. Cette approche est faiblement typée et ne fonctionne pas avec les attributions de rôles ou les personnalisations d’infrastructure. Pour plus d’informations, consultez Ajouter des ressources existantes Azure avec des chaînes de connexion.

Ajouter la file d’attente Azure Service Bus

Pour ajouter une file d’attente Azure Service Bus, appelez la méthode AddServiceBusQueue sur la IResourceBuilder<AzureServiceBusResource>:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Lorsque vous appelez AddServiceBusQueue(IResourceBuilder<AzureServiceBusResource>, String, String), il configure vos ressources Service Bus pour avoir une file d’attente nommée queue. Il exprime une relation parent-enfant explicite, entre la messaging ressource Service Bus et son enfant queue. La file d’attente est créée dans l’espace de noms Service Bus représenté par le AzureServiceBusResource, que vous avez ajouté précédemment. Pour plus d’informations, consultez Files d’attente, rubriques et abonnements dans Azure Service Bus.

Ajouter Azure Service Bus rubrique et abonnement

Pour ajouter une rubrique Azure Service Bus, appelez la méthode AddServiceBusTopic sur le IResourceBuilder<AzureServiceBusResource>:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Lorsque vous appelez AddServiceBusTopic(IResourceBuilder<AzureServiceBusResource>, String, String), il configure vos ressources Service Bus pour qu’un sujet nommé topicsoit créé. Le sujet est créé dans l’espace de noms Service Bus représenté par le AzureServiceBusResource que vous avez ajouté précédemment.

Pour ajouter un abonnement à la rubrique, appelez la méthode AddServiceBusSubscription sur le IResourceBuilder<AzureServiceBusTopicResource> et configurez-la à l’aide de la méthode 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...

Le code précédent ajoute non seulement une rubrique et crée et configure un abonnement nommé sub1 pour la rubrique. L’abonnement a un nombre maximal de livraisons de 10 et une règle nommée app-prop-filter-1. La règle est un filtre de corrélation qui filtre les messages en fonction des propriétés ContentType, CorrelationId, Subject, MessageId, ReplyTo, ReplyToSessionId, SessionIdet SendTo.

Pour plus d’informations, consultez Files d’attente, rubriques et abonnements dans Azure Service Bus.

Ajouter la ressource d’émulateur Azure Service Bus

Pour ajouter une ressource d’émulateur Azure Service Bus, enchaînez un appel à partir d’un <IResourceBuilder<AzureServiceBusResource>> à l’API RunAsEmulator :

var builder = DistributedApplication.CreateBuilder(args);

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

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

Lorsque vous appelez RunAsEmulator, il configure vos ressources Service Bus pour qu’elles s’exécutent localement à l’aide d’un émulateur. L’émulateur dans ce cas est l’émulateurAzure Service Bus. L’émulateur de Azure Service Bus fournit un environnement local gratuit pour tester vos applications Azure Service Bus et il s’agit d’un compagnon idéal pour l’intégration de l’hébergement .NET AspireAzure. L’émulateur n’est pas installé, à la place, il est accessible à .NET.NET Aspire en tant que conteneur. Lorsque vous ajoutez un conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image mcr.microsoft.com/azure-messaging/servicebus-emulator (et l’image mcr.microsoft.com/azure-sql-edge complémentaire), il crée et démarre le conteneur au démarrage de l’hôte de l’application. Pour plus d’informations, consultez cycle de vie des ressources de conteneur.

Configurer le conteneur de l’émulateur Service Bus

Il existe différentes configurations disponibles pour les ressources de conteneur, par exemple, vous pouvez configurer les ports du conteneur ou fournir une configuration JSON wholistic qui remplace tout.

Configurer le port hôte du conteneur de l’émulateur Service Bus

Par défaut, le conteneur de l’émulateur Service Bus lorsqu’il est configuré par .NET.NET Aspireexpose les points de terminaison suivants :

Point de terminaison Image Port de conteneur Port hôte
emulator mcr.microsoft.com/azure-messaging/servicebus-emulator 5672 dynamique
tcp mcr.microsoft.com/azure-sql-edge 1433 dynamique

Le port sur lequel il écoute est dynamique par défaut. Au démarrage du conteneur, le port est mappé à un port aléatoire sur l’ordinateur hôte. Pour configurer le port du point de terminaison, enchaînez les appels avec le générateur de ressources de conteneur fourni par la méthode RunAsEmulator, puis le WithHostPort(IResourceBuilder<AzureServiceBusEmulatorResource>, Nullable<Int32>), comme illustré dans l’exemple suivant :

var builder = DistributedApplication.CreateBuilder(args);

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

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

Le code précédent configure le point de terminaison emulator existant du conteneur de l’émulateur Service Bus pour écouter le port 7777. Le port de l’émulateur Service Bus est mappé au port hôte, comme indiqué dans le tableau suivant :

Nom du point de terminaison Mappage de ports (container:host)
emulator 5672:7777
Configurer la configuration du conteneur d’émulateur Service Bus JSON

L’émulateur Service Bus génère automatiquement une configuration similaire à ce fichier config.json à partir des ressources configurées. Vous pouvez remplacer entièrement ce fichier généré ou mettre à jour la JSON configuration avec une JsonNode représentation de la configuration.

Pour fournir un fichier de configuration JSON personnalisé, appelez la méthode WithConfigurationFile(IResourceBuilder<AzureServiceBusEmulatorResource>, String) :

var builder = DistributedApplication.CreateBuilder(args);

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

Le code précédent configure le conteneur de l’émulateur Service Bus pour utiliser un fichier de configuration de JSON personnalisé situé à ./messaging/custom-config.json. Pour remplacer plutôt des propriétés spécifiques dans la configuration par défaut, appelez la méthode 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...

Le code précédent récupère le nœud UserConfig de la configuration par défaut. Il met ensuite à jour les propriétés de la première file d’attente pour définir le MaxDeliveryCount sur 5, RequiresDuplicateDetection sur trueet DefaultMessageTimeToLive sur 2 hours.

Vérifications de l’intégrité des intégrations d'hébergement

L’intégration d’hébergement Azure Service Bus ajoute automatiquement un contrôle d’intégrité pour la ressource Service Bus. La vérification d’intégrité confirme que le Service Bus fonctionne et qu'il est possible d'établir une connexion avec celui-ci.

L’intégration de l’hébergement s’appuie sur le 📦 package NuGet AspNetCore.HealthChecks.AzureServiceBus .

Intégration de Client

Pour commencer à utiliser l'intégration du client .NET AspireAzure Service Bus, installez le package NuGet 📦Aspire.Azure.Messaging.ServiceBus dans le projet consommant le client, c'est-à-dire (le projet pour) l'application qui utilise le client Service Bus. L’intégration du client Service Bus inscrit une instance ServiceBusClient que vous pouvez utiliser pour interagir avec Service Bus.

dotnet add package Aspire.Azure.Messaging.ServiceBus

Ajouter un client Service Bus

Dans le fichier Program.cs de votre projet client, appelez la méthode d'extension AddAzureServiceBusClient sur n'importe quel IHostApplicationBuilder afin d'enregistrer un ServiceBusClient pour son utilisation via le conteneur d'injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddAzureServiceBusClient(connectionName: "messaging");

Conseil / Astuce

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource Service Bus dans le projet hôte de l’application. En d’autres termes, lorsque vous appelez AddAzureServiceBus et fournissez un nom de messaging ce même nom doit être utilisé lors de l’appel de AddAzureServiceBusClient. Pour plus d’informations, consultez Ajouter Azure Service Bus une ressource.

Vous pouvez ensuite récupérer l’instance ServiceBusClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

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

Pour plus d’informations sur l’injection de dépendances, consultez .NET l’injection de dépendances.

Ajouter un client Service Bus avec clé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de ServiceBusClient avec différents noms de connexion. Pour enregistrer des clients avec clé pour Service Bus, appelez la méthode AddKeyedAzureServiceBusClient :

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

Essentiel

Lorsque vous utilisez des services à clé, il est prévu que votre ressource Service Bus a configuré deux bus nommés, un pour le mainBus et un pour le loggingBus.

Vous pouvez ensuite récupérer les instances ServiceBusClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

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

Pour plus d’informations sur les services à clé, consultez .NET l’injection de dépendances : services à clé.

Paramétrage

L’intégration .NET AspireAzure Service Bus fournit plusieurs options pour configurer la connexion en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de la méthode AddAzureServiceBusClient :

builder.AddAzureServiceBusClient("messaging");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

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

Pour plus d’informations sur la mise en forme de cette chaîne de connexion, consultez la documentation ConnectionString.

Utiliser des fournisseurs de configuration

L'intégration de .NET AspireetAzure Service Bus prend en charge Microsoft.Extensions.Configuration. Il charge le AzureMessagingServiceBusSettings depuis la configuration en utilisant la clé Aspire:Azure:Messaging:ServiceBus. L’extrait de code suivant est un exemple de fichier appsettings.json qui configure certaines des options :

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

Pour connaître le schéma complet d’intégration JSON du client Service Bus, consultez Aspire.Azure. Messaging.ServiceBus/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<AzureMessagingServiceBusSettings> configureSettings pour configurer en ligne certaines ou toutes les options, par exemple pour désactiver le traçage à partir du code :

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

Vous pouvez également configurer le Azure.Messaging.ServiceBus.ServiceBusClientOptions à l’aide du paramètre facultatif Action<ServiceBusClientOptions> configureClientOptions de la méthode AddAzureServiceBusClient. Par exemple, pour définir le suffixe d’en-tête de l’agent utilisateur ServiceBusClientOptions.Identifier pour toutes les requêtes effectuées par ce client :

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

Client contrôles de santé de l’intégration

Par défaut, les intégrations .NET.NET Aspire permettent les vérifications d’intégrité pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire la vue d’ensemble des intégrations.

Intégration .NET AspireAzure Service Bus :

  • Ajoute la vérification de l'état de santé lorsque AzureMessagingServiceBusSettings.DisableTracing est false, et essaie de se connecter au Service Bus.
  • S’intègre au point de terminaison HTTP /health, qui spécifie que tous les contrôles de santé enregistrés doivent être réussis pour que l'application soit prête à recevoir du trafic.

Observabilité et télémétrie

.NET.NET Aspire les intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées piliers de l’observabilité. Pour plus d’informations sur l’observabilité et la télémétrie d’intégration, consultez .NET.NET Aspire la vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration .

Exploitation forestière

L’intégration .NET AspireAzure Service Bus utilise les catégories de logs suivantes :

  • Azure.Core
  • Azure.Identity
  • Azure-Messaging-ServiceBus

En plus d’obtenir des diagnostics de requête Azure Service Bus pour les demandes ayant échoué, vous pouvez configurer des seuils de latence pour déterminer lesquels diagnostics de requête réussis Azure Service Bus seront enregistrés. Les valeurs par défaut sont 100 ms pour les opérations de point et 500 ms pour les opérations non point.

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

Traçage

L’intégration .NET AspireAzure Service Bus émet les activités de suivi suivantes à l’aide de 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

Le traçage Azure Service Bus est actuellement en version préliminaire, vous devez donc activer le commutateur expérimental afin de vous assurer de l'émission des traces.

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

Pour plus d’informations, consultez Azure Service Bus: Suivi distribué et corrélation par le biais de la messagerie Service Bus.

Métriques

L’intégration .NET AspireAzure Service Bus ne prend actuellement pas en charge les métriques par défaut en raison de limitations avec le KIT DE développement logiciel (SDK) Azure.

Voir aussi