intégration de .NET AspireCosmos DBEntity Framework Core

Article
01/09/2025

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 AspireCosmos DBEntity Framework Core vous permet de vous connecter à des instances de Cosmos DB existantes ou de créer de nouvelles instances à partir de .NET avec l’émulateur Azure Cosmos DB.

Intégration de l’hébergement

Le modèle d’intégration .NET.NET AspireAzure Cosmos DB modélise les diverses ressources Cosmos DB sous les types suivants :

AzureCosmosDBResource: représente une ressource AzureAzure Cosmos DB.
AzureCosmosDBEmulatorResource: représente une ressource d’émulateur de AzureAzure Cosmos DB.

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

.NET CLI
packageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de package 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 l’une des autres ressources 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 êtes nouveau dans Bicep, c'est un langage de programmation spécifique au domaine pour définir les 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 est généré en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource AzureAzure Cosmos DB, le Bicep suivant est généré :

Activer/désactiver 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 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 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 :

Chaîne un appel à l’API ConfigureInfrastructure :
- Le paramètre infra est une instance du type AzureResourceInfrastructure.
- Les ressources provisionnables sont récupérées en appelant la méthode GetProvisionableResources().
- La CosmosDBAccount unique est récupérée.
- Le CosmosDBAccount.ConsistencyPolicy est affecté à un DefaultConsistencyLevel.Strong.
- Une balise est ajoutée au compte Cosmos DB avec une clé de ExampleKey et une valeur de Example value.

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, effectuez une chaîne d'appels avec un IResourceBuilder<AzureCosmosDBResource> vers 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 AzureAzure Cosmos DB, enchaî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 le cycle de vie des ressources de 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, sa durée de vie, etc.

Configurer le port de passerelle du conteneur d'é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 fournis par la méthode RunAsEmulator, comme indiqué 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 des conteneurs.

Configurer le conteneur de l’é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é à l’emplacement /tmp/cosmos/appdata dans le conteneur d’émulateur Cosmos DB, et si aucun paramètre name n’est fourni, le 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 on les préfère aux montages de liaison, consultez la documentation 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 d’intégrité de l’intégration d’hébergement

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 de santé vérifie que le Cosmos DB fonctionne et qu'une connexion peut être établie à 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 .NET Aspire Microsoft Entity Framework CoreCosmos DB, installez le 📦Aspire. Microsoft.EntityFrameworkCore.Cosmos package NuGet dans le projet consommant le client, c’est-à-dire le projet pour l’application qui utilise le client Microsoft Entity Framework CoreCosmos DB.

.NET CLI
packageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

<PackageReference Include="Aspire.Microsoft.EntityFrameworkCore.Cosmos"
                  Version="*" />

Ajouter Cosmos DB contexte

Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddCosmosDbContext pour inscrire un System.Data.Entity.DbContext à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddCosmosDbContext<MyDbContext>("cosmosdb");

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 cosmosdb ce même nom doit être utilisé lors de l’appel de AddCosmosDbContext. Pour plus d'informations, consultez Ajouter la ressource AzureAzure Cosmos DB.

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

public class ExampleService(MyDbContext context)
{
    // Use context...
}

Pour plus d’informations sur l’utilisation de Entity Framework Core avec Azure Cosmos DB, consultez les exemples de pour Azure Cosmos DB pour le Kit de développement logiciel (SDK) NoSQL pour .NET.

Configuration

L’intégration .NET Aspire Microsoft Entity Framework CoreCosmos DB fournit plusieurs options pour configurer la connexion Azure Cosmos DB 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 builder.AddCosmosDbContext:

builder.AddCosmosDbContext<MyDbContext>("CosmosConnection");

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

{
  "ConnectionStrings": {
    "CosmosConnection": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
  }
}

Pour plus d’informations, consultez la documentation ConnectionString.

Utiliser des fournisseurs de configuration

L’intégration .NET Aspire Microsoft Entity Framework CoreCosmos DB prend en charge Microsoft.Extensions.Configuration. Il charge le EntityFrameworkCoreCosmosSettings à partir de fichiers de configuration tels que appsettings.json. Exemple _appsettings.json qui configure certaines des options :

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DisableTracing": true
        }
      }
    }
  }
}

Pour le schéma complet Cosmos DB de l'intégration du client JSON, consultez Aspire. Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Utiliser des délégués intégrés

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

builder.AddCosmosDbContext<MyDbContext>(
    "cosmosdb",
    settings => settings.DisableTracing = true);

Client vérifications d’intégrité 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.

L’intégration .NET Aspire Microsoft Entity Framework CoreCosmos DB n’implémente actuellement pas les contrôles d’intégrité, même si cela peut changer dans les versions ultérieures.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement la journalisation, le suivi et les mesures, 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 Aspire Microsoft Entity Framework CoreCosmos DB utilise les catégories de journaux suivantes :

Azure-Cosmos-Operation-Request-Diagnostics
Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Query

Traçage

L’intégration .NET Aspire Microsoft Entity Framework CoreCosmos DB émettra les activités de suivi suivantes à l’aide de OpenTelemetry:

Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore

Métriques

L’intégration .NET Aspire Microsoft Entity Framework CoreCosmos DB prend actuellement en charge les métriques suivantes :

Microsoft.EntityFrameworkCore
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

Partager via