Partager via

intégration de .NET AspireCosmos DBEntity Framework Core

  • 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 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 :

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 .

dotnet add package Aspire.Hosting.Azure.CosmosDB

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 fichier 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: 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 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 :

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 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 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 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 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 intitulée 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 basé sur Linux avec l'option de prévisualisation Cosmos DB et le point de terminaison de l’Explorateur de données, à utiliser au moment de l’exécution.

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.

Client intégration

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.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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", "databaseName");

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 est compatible avec 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 en ligne

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

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

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

L’intégration .NET Aspire Microsoft Entity Framework CoreCosmos DB n’implémente actuellement pas les vérifications d'état, 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 d'événements 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

Voir aussi