Partager via

intégration .NET AspireAzure Cosmos DB

  • Article

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

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 à leurs API, ajoutez le package NuGet .Hosting..CosmosDB dans le projet hôte de l'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.

Génération du provisioning avec 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, le Bicep suivant est généré :

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

param principalType string

param principalId string

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'
    disableLocalAuth: true
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource cosmos_roleDefinition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-08-15' existing = {
  name: '00000000-0000-0000-0000-000000000002'
  parent: cosmos
}

resource cosmos_roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-08-15' = {
  name: guid(principalId, cosmos_roleDefinition.id, cosmos.id)
  properties: {
    principalId: principalId
    roleDefinitionId: cosmos_roleDefinition.id
    scope: cosmos.id
  }
  parent: cosmos
}

output connectionString string = cosmos.properties.documentEndpoint

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 : les emplacements du compte Cosmos DB. La valeur par défaut est l’emplacement du groupe de ressources.

Outre le compte Cosmos DB, il ajoute également l’application actuelle au rôle Data Contributor pour le compte Cosmos DB. 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 interface fluide pour configurer les ressources Azure en utilisant 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...

Remarque

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 des ressources de base de données et de conteneur AzureAzure Cosmos DB

Pour ajouter une ressource de base de données AzureAzure Cosmos DB, appelez la méthode AddCosmosDatabase sur une instance de IResourceBuilder<AzureCosmosDBResource> :

var builder = DistributedApplication.CreateBuilder(args);

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

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

Lorsque vous appelez AddCosmosDatabase, il ajoute une base de données nommée db à vos ressources Cosmos DB et retourne la ressource de base de données nouvellement créée. 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.

Un conteneur AzureAzure Cosmos DB est l’emplacement où les données sont stockées. Quand vous créez un conteneur, vous devez fournir une clé de partition.

Pour ajouter une ressource de conteneur AzureAzure Cosmos DB, appelez la méthode AddContainer sur une instance de IResourceBuilder<AzureCosmosDBDatabaseResource> :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
db.AddContainer("entries", "/id");

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

Le conteneur est créé dans la base de données représentée par la AzureCosmosDBDatabaseResource que vous avez ajoutée précédemment.

Pour plus d’informations, consultez Bases de données, conteneurs et éléments dans AzureAzure Cosmos DB.

Ajouter AzureAzure Cosmos DB ressource d’émulateur

Pour ajouter une ressource d’émulateur de AzureAzure Cosmos DB, chaînez un appel à partir de IResourceBuilder<AzureCosmosDBResource> vers 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

Différentes configurations sont disponibles pour les ressources de conteneur ; par exemple, vous pouvez configurer les ports du conteneur, les variables environnementales, sa 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.

Utiliser l’émulateur basé sur Linux(aperçu)

La nouvelle génération de l’émulateur de AzureAzure Cosmos DB est entièrement basée sur Linuxet est disponible en tant que container Docker. Il prend en charge l’exécution sur une grande variété de processeurs et de systèmes d’exploitation.

Pour utiliser la préversion de l’émulateur de Cosmos DB, appelez la méthode RunAsPreviewEmulator. Étant donné que cette fonctionnalité est en préversion, vous devez choisir explicitement la fonctionnalité d’aperçu en supprimant le diagnostic expérimental ASPIRECOSMOSDB001.

L’émulateur d’aperçu prend également en charge l’exposition d’un point de terminaison « Explorateur de données » qui vous permet d’afficher les données stockées dans l’émulateur Cosmos DB via une interface utilisateur web. Pour activer l’Explorateur de données, appelez la méthode WithDataExplorer.

#pragma warning disable ASPIRECOSMOSDB001

var builder = DistributedApplication.CreateBuilder(args);

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

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

Le code précédent configure le conteneur de l'émulateur Cosmos DB basé sur l’aperçu Linux, avec le point de terminaison de l’Explorateur de données, à utiliser au moment de l’exécution.

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 lui.

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

intégration 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 DB ressource.

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 clé Cosmos DB

Il peut arriver que vous souhaitiez inscrire plusieurs instances de CosmosClient avec différents noms de connexion. Pour enregistrer les clients par clé Cosmos DB, 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 avec clé, consultez .NET injection de dépendances : services avec clé.

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 en utilisant 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 en ligne

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 la traçabilité à partir du 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 de l'état de l'intégration

Actuellement, l’intégration du client .NET AspireCosmos DB n’implémente pas de contrôles de santé, même si cela peut changer dans les versions ultérieures.

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 le traçage est actuellement en préversion, vous devez donc activer un 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