Partager via

intégration de .NET AspireAzure Cosmos DB

  • Article

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

Azure Cosmos DB est un service de base de données NoSQL entièrement managé pour le développement d’applications modernes. L’intégration .NET AspireAzure Cosmos DB vous permet de vous connecter à des instances de Cosmos DB existantes ou de créer de nouvelles instances à partir de .NET avec l’émulateur de Azure Cosmos DB.

Intégration de l’hébergement

Le modèle d'intégration .NET.NET AspireAzure Cosmos DB héberge les différentes ressources Cosmos DB sous les types suivants :

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

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Ajouter une ressource AzureAzure Cosmos DB

Dans votre projet hôte d’application, appelez AddAzureCosmosDB pour ajouter et retourner un générateur de ressources AzureAzure Cosmos DB.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");

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

Lorsque vous ajoutez un AzureCosmosDBResource à l’hôte d’application, il expose d’autres API utiles pour ajouter des bases de données et des conteneurs. En d’autres termes, vous devez ajouter un AzureCosmosDBResource avant d’ajouter toute autre ressource Cosmos DB.

Important

Lorsque vous appelez AddAzureCosmosDB, 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 approvisionnement local : Configuration.

Approvisionnement 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 Bicep généré est fourni en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource AzureAzure Cosmos DB, un bicep suivant est généré :


bascule AzureAzure Cosmos DB Bicep. 

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

param keyVaultName string

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
}

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' = {
  name: take('cosmos-${uniqueString(resourceGroup().id)}', 44)
  location: location
  properties: {
    locations: [
      {
        locationName: location
        failoverPriority: 0
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    databaseAccountOfferType: 'Standard'
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource connectionString 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  name: 'connectionString'
  properties: {
    value: 'AccountEndpoint=${cosmos.properties.documentEndpoint};AccountKey=${cosmos.listKeys().primaryMasterKey}'
  }
  parent: keyVault
}

Bicep précédent est un module qui provisionne un compte AzureAzure Cosmos DB avec les valeurs par défaut suivantes :

  • kind: type de compte Cosmos DB. La valeur par défaut est GlobalDocumentDB.
  • consistencyPolicy: stratégie de cohérence du compte Cosmos DB. La valeur par défaut est Session.
  • locations: emplacements du compte Cosmos DB. La valeur par défaut est l’emplacement du groupe de ressources.

En plus du compte Cosmos DB, il provisionne également une ressource Azure Key Vault. Il est utilisé pour stocker la chaîne de connexion du compte Cosmos DB en toute sécurité. Bicep généré est un point de départ et peut être personnalisé pour répondre à vos besoins spécifiques.

Personnaliser l’infrastructure d’approvisionnement

Toutes les ressources .NET AspireAzure sont des sous-classes du type AzureProvisioningResource. Ce type permet la personnalisation du Bicep généré en fournissant une API Fluent pour configurer les ressources Azure à l’aide de l’API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Par exemple, vous pouvez configurer le kind, consistencyPolicy, locations, etc. L’exemple suivant montre comment personnaliser la ressource AzureAzure Cosmos DB :

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var cosmosDbAccount = infra.GetProvisionableResources()
                                   .OfType<CosmosDBAccount>()
                                   .Single();

        cosmosDbAccount.Kind = CosmosDBAccountKind.MongoDB;
        cosmosDbAccount.ConsistencyPolicy = new()
        {
            DefaultConsistencyLevel = DefaultConsistencyLevel.Strong,
        };
        cosmosDbAccount.Tags.Add("ExampleKey", "Example value");
    });

Code précédent :

Il existe de nombreuses autres options de configuration disponibles pour personnaliser la ressource AzureAzure Cosmos DB. Pour plus d’informations, consultez Azure.Provisioning.CosmosDB. Pour plus d’informations, consultez Azure. Personnalisation de l’approvisionnement.

Se connecter à un compte AzureAzure Cosmos DB existant

Vous disposez peut-être d’un compte AzureAzure Cosmos DB existant auquel vous souhaitez vous connecter. Au lieu de représenter une nouvelle ressource AzureAzure Cosmos DB, vous pouvez ajouter une chaîne de connexion à l’hôte de l’application. Pour ajouter une connexion à un compte AzureAzure Cosmos DB existant, appelez la méthode AddConnectionString :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddConnectionString("cosmos-db");

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

// 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": {
        "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
    }
}

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 "cosmos-db". L’API GetConnectionString est abrégée pour IConfiguration.GetSection("ConnectionStrings")[name].

Ajouter AzureAzure Cosmos DB ressource de base de données

Pour ajouter une ressource de base de données AzureAzure Cosmos DB, chaînez un appel sur un IResourceBuilder<AzureCosmosDBResource> à l’API AddDatabase :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AddDatabase("db");

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

Lorsque vous appelez AddDatabase, il configure vos ressources Cosmos DB pour qu’une base de données nommée db. La base de données est créée dans le compte Cosmos DB représenté par le AzureCosmosDBResource que vous avez ajouté précédemment. La base de données est un conteneur logique pour les collections et les utilisateurs. Pour plus d’informations, consultez Bases de données, conteneurs et éléments dans AzureAzure Cosmos DB.

Note

Lorsque vous utilisez l’API AddDatabase pour ajouter une base de données à une ressource AzureAzure Cosmos DB, si vous exécutez l’émulateur, la base de données n’est pas réellement créée dans l’émulateur. Cette API est destinée à inclure une base de données dans le Bicep généré par l’infrastructure d’approvisionnement.

Ajouter AzureAzure Cosmos DB ressource d’émulateur

Pour ajouter une ressource d’émulateur de AzureAzure Cosmos DB, chaînez un appel sur un IResourceBuilder<AzureCosmosDBResource> à l’API RunAsEmulator :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .RunAsEmulator();

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

Lorsque vous appelez RunAsEmulator, il configure vos ressources Cosmos DB pour qu’elles s’exécutent localement à l’aide d’un émulateur. L’émulateur dans ce cas est l’émulateur AzureAzure Cosmos DB. L’émulateur de Azure Cosmos DB fournit un environnement local gratuit pour tester vos applications Azure Cosmos DB 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 d’application, comme illustré dans l’exemple précédent avec l’image mcr.microsoft.com/cosmosdb/emulator, 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 Cosmos DB conteneur d’émulateur

Il existe différentes configurations disponibles pour les ressources de conteneur, par exemple, vous pouvez configurer les ports du conteneur, les variables d’environnement, il est durée de vie, etc.

Configurer le port de passerelle du conteneur de l’émulateur Cosmos DB

Par défaut, le conteneur de l’émulateur Cosmos DB lorsqu’il est configuré par .NET Aspire, expose les points de terminaison suivants :

Point de terminaison Port de conteneur Port hôte
https 8081 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 sur le générateur de ressources de conteneur fourni par la méthode RunAsEmulator, comme illustré dans l’exemple suivant :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithGatewayPort(7777);
                     });

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

Le code précédent configure le point de terminaison Cosmos DB existant du conteneur d’émulateur https pour écouter le port 8081. Le port de l’émulateur Cosmos DB est mappé au port hôte, comme indiqué dans le tableau suivant :

Nom du point de terminaison Mappage de ports (container:host)
https 8081:7777
Configurer Cosmos DB conteneur d’émulateur avec une durée de vie persistante

Pour configurer le conteneur d’émulateur Cosmos DB avec une durée de vie persistante, appelez la méthode WithLifetime sur la ressource de conteneur de l’émulateur Cosmos DB et transmettez ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithLifetime(ContainerLifetime.Persistent);
                     });

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

Pour plus d’informations, consultez durée de vie des ressources de conteneur.

Configurer le conteneur d’émulateur Cosmos DB avec un volume de données

Pour ajouter un volume de données à la ressource de l’émulateur AzureAzure Cosmos DB, appelez la méthode WithDataVolume sur la ressource de l’émulateur AzureAzure Cosmos DB :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithDataVolume();
                     });

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

Le volume de données est utilisé pour conserver les données de l’émulateur Cosmos DB en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /tmp/cosmos/appdata dans le conteneur de l'émulateur Cosmos DB, et lorsque le paramètre name n'est pas fourni, un nom est généré. L’émulateur a sa variable d’environnement AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE définie sur true. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés par rapport aux montages de liaison, consultez les docs Docker : Volumes.

Configurer le nombre de partitions de conteneur de l'émulateur Cosmos DB

Pour configurer le nombre de partitions du conteneur de l’émulateur Cosmos DB, appelez la méthode WithPartitionCount :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithPartitionCount(100); // Defaults to 25
                     });

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

Le code précédent configure le conteneur de l’émulateur Cosmos DB pour avoir un nombre de partitions de 100. Il s’agit d’un raccourci pour définir la variable d’environnement AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Vérifications de l'intégrité de l'hébergement intégré

L’intégration d’hébergement Azure Cosmos DB ajoute automatiquement un contrôle d’intégrité pour la ressource Cosmos DB. Le contrôle d'intégrité vérifie que le Cosmos DB fonctionne et qu'une connexion peut être établie avec celui-ci.

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

intégration de Client

Pour commencer à utiliser l'intégration du client .NET AspireAzure Cosmos DB, installez le package NuGet 📦Aspire.Microsoft.Azure.Cosmos dans le projet consommant le client, c'est-à-dire pour le projet de l'application qui utilise le client Cosmos DB. L’intégration du client Cosmos DB inscrit une instance de CosmosClient que vous pouvez utiliser pour interagir avec Cosmos DB.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Ajouter Cosmos DB client

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

builder.AddAzureCosmosClient(connectionName: "cosmos-db");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource Cosmos DB dans le projet hôte de l’application. En d’autres termes, lorsque vous appelez AddAzureCosmosDB et fournissez un nom de cosmos-db ce même nom doit être utilisé lors de l’appel de AddAzureCosmosClient. Pour plus d’informations, consultez Ajouter AzureAzure Cosmos DBressource .

Vous pouvez ensuite récupérer l’instance CosmosClient à 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(CosmosClient client)
{
    // Use client...
}

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

Ajouter un client Cosmos DB clé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de CosmosClient avec différents noms de connexion. Pour inscrire les clients Cosmos DB codés, appelez la méthode AddKeyedAzureCosmosClient :

builder.AddKeyedAzureCosmosClient(name: "mainDb");
builder.AddKeyedAzureCosmosClient(name: "loggingDb");

Important

Lorsque vous utilisez des services à clé, il est prévu que votre ressource Cosmos DB a configuré deux bases de données nommées, une pour le mainDb et l’autre pour le loggingDb.

Vous pouvez ensuite récupérer les instances CosmosClient à 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("mainDb")] CosmosClient mainDbClient,
    [FromKeyedServices("loggingDb")] CosmosClient loggingDbClient)
{
    // Use clients...
}

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

Configuration

L’intégration .NET AspireAzure Cosmos DB 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 AddAzureCosmosClient :

builder.AddAzureCosmosClient("cosmos-db");

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

{
  "ConnectionStrings": {
    "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_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 .NET AspireAzure Cosmos DB prend en charge Microsoft.Extensions.Configuration. Il charge le MicrosoftAzureCosmosSettings à partir de la configuration à l’aide de la clé Aspire:Microsoft:Azure:Cosmos. L’extrait de code suivant est un exemple de fichier appsettings.json qui configure certaines des options :

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

Pour obtenir le schéma complet de l'intégration du client Cosmos DBJSON, consultez Aspire. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

Utiliser des délégués inline

Vous pouvez également transmettre le délégué Action<MicrosoftAzureCosmosSettings> configureSettings pour configurer certaines ou toutes les options en ligne, par exemple pour désactiver le suivi directement depuis le code :

builder.AddAzureCosmosClient(
    "cosmos-db",
    static settings => settings.DisableTracing = true);

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

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

Client vérifications d’intégrité de l’intégration

Par défaut, les .NET.NET Aspire intégrations activent 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 Cosmos DB :

  • Ajoute la vérification de l'état de santé lorsque MicrosoftAzureCosmosSettings.DisableTracing est false, et tente de se connecter au Cosmos DB.
  • S'intègre au point de terminaison HTTP /health, qui spécifie que toutes les vérifications d'intégrité enregistrées doivent être validées pour que l'application soit considérée comme prête à accepter le 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 Cosmos DB utilise les catégories de journaux suivantes :

  • Azure-Cosmos-Operation-Request-Diagnostics

En plus d’obtenir des diagnostics de requête Azure Cosmos DB pour les demandes ayant échoué, vous pouvez configurer des seuils de latence pour déterminer lesquels diagnostics de requête réussis Azure Cosmos DB 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.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Traçage

L’intégration .NET AspireAzure Cosmos DB émet les activités de suivi suivantes à l’aide de OpenTelemetry:

  • Azure.Cosmos.Operation

Azure Azure Cosmos DB suivi est actuellement en préversion. Vous devez donc définir le commutateur expérimental pour vous assurer que les traces sont émises.

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

Pour plus d’informations, consultez Observabilité du kit de développement logiciel (SDK) AzureAzure Cosmos DB : Attributs de trace.

Métriques

L’intégration .NET AspireAzure Cosmos DB 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