Partager via


.NET Aspire Azure Service Bus intégration

inclut : l’intégration d’hébergement et l’intégration de Client

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 leur expression, ajoutez le paquet NuGet 📦Aspire.Hosting.Azure.ServiceBus dans le projet hôte de l'application .

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

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

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

Bicep précédent est un module qui provisionne un espace de noms Azure Service Bus avec les valeurs par défaut suivantes :

  • sku: La référence SKU de l’espace de noms Service Bus. La valeur par défaut est Standard.
  • location: emplacement de l’espace de noms Service Bus. La valeur par défaut est l’emplacement du groupe de ressources.

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) Azure du 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
        {
            Tier = ServiceBusSkuTier.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. Au lieu de représenter une nouvelle ressource Azure Service Bus, vous pouvez ajouter une chaîne de connexion à l’hôte de l’application. Pour ajouter une connexion à un espace de noms Azure Service Bus existant, appelez la méthode 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...

Note

Les chaînes de connexion sont utilisées pour représenter un large éventail d’informations de connexion, notamment les connexions de base de données, les répartiteurs de messages, les URI de point de terminaison et d’autres services. Dans .NET.NET Aspire nomenclature, le terme « chaîne de connexion » est utilisé pour représenter n’importe quel type d’informations de connexion.

La chaîne de connexion est configurée dans la configuration de l’hôte d’application, généralement sous secrets utilisateur, sous la section ConnectionStrings. L’hôte de l’application injecte cette chaîne de connexion en tant que variable d’environnement dans toutes les ressources dépendantes, par exemple :

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

La ressource dépendante peut accéder à la chaîne de connexion injectée en appelant la méthode GetConnectionString et en passant le nom de connexion en tant que paramètre, dans ce cas "messaging". L’API GetConnectionString est abrégée pour IConfiguration.GetSection("ConnectionStrings")[name].

Ajouter Azure Service Bus file d’attente

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");
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. 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");
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’émulateur Azure 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 du 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

Le conteneur de l’émulateur Service Bus s’exécute avec un fichier config.json par défaut. Vous pouvez remplacer entièrement ce fichier ou mettre à jour la configuration JSON avec une représentation JsonNode 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 consommateur, c'est-à-dire le projet de l’application utilisant 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 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 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 avec clé, voir la section .NET injection de dépendances : services avec clé.

Configuration

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 de l’intégration du client Service Bus JSON, 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 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 intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire 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 journaux 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 via 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