Partager via

intégration de base de données .NET AspireMongoDB

  • Article

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

MongoDB est une base de données NoSQL qui offre des performances élevées, une haute disponibilité et une scalabilité facile. L’intégration .NET AspireMongoDB vous permet de vous connecter à des instances MongoDB existantes (y compris MongoDB Atlas) ou de créer de nouvelles instances à partir de .NET avec l’image conteneur docker.io/library/mongo

Intégration de l’hébergement

Le modèle d'intégration de l'hébergement MongoDBserver représente le server comme type MongoDBServerResource et la base de données comme type MongoDBDatabaseResource. Pour accéder à ces types et API, ajoutez le package NuGet .Host. dans le projet hôte de l’application .

dotnet add package Aspire.Hosting.MongoDB

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

Ajouter MongoDBserver ressource et ressource de base de données

Dans votre projet hôte d’application, appelez AddMongoDB pour ajouter et retourner un générateur de ressources MongoDBserver. Chaînez un appel au générateur de ressources retourné pour AddDatabase, pour ajouter une ressource de base de données MongoDB.

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithLifetime(ContainerLifetime.Persistent);

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Note

Le conteneur MongoDB peut être lent à démarrer. Il est donc préférable d’utiliser une durée de vie persistante pour éviter les redémarrages inutiles. Pour obtenir plus d'informations, consultez la durée de vie des ressources de conteneur.

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image docker.io/library/mongo, il crée une instance de MongoDB sur votre ordinateur local. Une référence à votre générateur de ressources MongoDBserver (la variable mongo) est utilisée pour ajouter une base de données. La base de données est nommée mongodb, puis ajoutée au ExampleProject. La ressource MongoDBserver inclut les informations d’identification par défaut :

  • MONGO_INITDB_ROOT_USERNAME: valeur de admin.
  • MONGO_INITDB_ROOT_PASSWORD: password aléatoire générée à l’aide de la méthode CreateDefaultPasswordParameter.

Lorsque l’hôte de l’application s’exécute, le mot de passe est stocké dans le magasin de secrets de l’hôte d’application. Elle est ajoutée à la section Parameters, par exemple :

{
  "Parameters:mongo-password": "<THE_GENERATED_PASSWORD>"
}

Le nom du paramètre est mongo-password, mais il suffit de mettre en forme le nom de la ressource avec un suffixe -password. Pour plus d’informations, consultez Stockage sécurisé des secrets d’application dans le développement dans ASP.NET Core et Ajouter une ressource MongoDBserver avec des paramètres.

La méthode WithReference configure une connexion dans le ExampleProject nommé mongodb et l'WaitFor indique à l’hôte de l’application de ne pas démarrer le service dépendant tant que la ressource mongodb n’est pas prête.

Pourboire

Si vous préférez vous connecter à une MongoDBserverexistante, appelez AddConnectionString à la place. Pour plus d'informations, consultez Ressources existantes de référence.

Ajouter une ressource MongoDBserver avec un volume de données

Pour ajouter un volume de données à la ressource MongoDBserver, appelez la méthode WithDataVolume sur la ressource MongoDBserver :

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataVolume();

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Le volume de données est utilisé pour conserver les données MongoDBserver en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /data/db dans le conteneur MongoDBserver et lorsqu’un paramètre name n’est pas fourni, le nom est généré aléatoirement. 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 Docker documentation : Volumes.

Avertissement

Le mot de passe est stocké dans le volume de données. Lors de l’utilisation d’un volume de données et si le mot de passe change, il ne fonctionnera pas tant que vous ne supprimez pas le volume.

Ajouter la ressource MongoDBserver avec montage de liaison des données

Pour ajouter un montage de liaison de données à la ressource MongoDBserver, appelez la méthode WithDataBindMount :

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataBindMount(@"C:\MongoDB\Data");

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes , ce qui offre de meilleures performances, la portabilité et la sécurité, ce qui les rend plus adaptés aux environnements de production. Toutefois, les montages de liens permettent un accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et les tests nécessitant des modifications en temps réel.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données MongoDBserver entre les redémarrages de conteneur. Le montage de liaison de données est monté sur le C:\MongoDB\Data sur Windows (ou /MongoDB/Data sur Unix) chemin sur l’ordinateur hôte dans le conteneur MongoDBserver. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.

Ajouter la ressource MongoDBserver avec un montage de liaison pour les données d'initialisation

Pour ajouter un montage de liaison de données de dossiers d’initialisation à la ressource MongoDBserver, appelez la méthode WithInitBindMount :

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithInitBindMount(@"C:\MongoDB\Init");

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Le montage de liaison de données d’initialisation est utilisé pour initialiser le MongoDBserver avec des données. Le montage de liaison des données d'initialisation est monté sur le chemin C:\MongoDB\Init sur Windows (ou /MongoDB/Init sur Unix) de l'ordinateur hôte dans le conteneur MongoDBserver et correspond au chemin /docker-entrypoint-initdb.d dans le conteneur MongoDBserver. MongoDB exécute les scripts trouvés dans ce dossier, ce qui est utile pour charger des données dans la base de données.

Ajouter MongoDBserver ressource avec des paramètres

Lorsque vous souhaitez fournir explicitement le mot de passe utilisé par l’image conteneur, vous pouvez fournir ces informations d’identification en tant que paramètres. Prenons l’exemple de remplacement suivant :

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var mongo = builder.AddMongoDB("mongo", username, password);
var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Pour plus d’informations sur la fourniture de paramètres, consultez paramètres externes.

Ajouter la ressource Express MongoDB

MongoDB Express est une interface utilisateur d’administrateur MongoDB basée sur le web. Pour ajouter une ressource Express MongoDB qui correspond à l’image conteneur docker.io/library/mongo-express, appelez la méthode WithMongoExpress sur la ressource MongoDBserver :

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithMongoExpress();

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Pourboire

Pour configurer le port hôte de la chaîne MongoExpressContainerResource un appel à l’API WithHostPort et fournir le numéro de port souhaité.

Le code précédent ajoute une ressource Express MongoDB configurée pour se connecter à la ressource MongoDBserver. Les informations d’identification par défaut sont les suivantes :

  • ME_CONFIG_MONGODB_SERVER: nom attribué au MongoDBServerResourceparent , dans ce cas, il serait mongo.
  • ME_CONFIG_BASICAUTH: valeur de false.
  • ME_CONFIG_MONGODB_PORT: Affecté depuis le port cible du point de terminaison principal du MongoDBServerResourceparent.
  • ME_CONFIG_MONGODB_ADMINUSERNAME: le même nom d’utilisateur que celui configuré dans le MongoDBServerResourceparent .
  • ME_CONFIG_MONGODB_ADMINPASSWORD: le même mot de passe que celui configuré dans le MongoDBServerResourceparent .

En outre, l’API WithMongoExpress expose un paramètre configureContainer facultatif de type Action<IResourceBuilder<MongoExpressContainerResource>> que vous utilisez pour configurer la ressource de conteneur express MongoDB.

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

L’intégration d’hébergement MongoDB ajoute automatiquement un contrôle d’intégrité pour la ressource MongoDBserver. La vérification de l'état de santé vérifie que la ressource MongoDBserver fonctionne et qu’une connexion peut être établie.

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

intégration de Client

Pour commencer à utiliser l’intégration .NET AspireMongoDBclient, installez le package NuGet 📦Aspire.MongoDB. Driver dans le projet consommant client, c’est-à-dire le projet pour l’application qui utilise le MongoDBclient. L’intégration MongoDBclient inscrit une instance IMongoClient que vous pouvez utiliser pour interagir avec la ressource MongoDBserver. Si votre hôte d’application ajoute les ressources de base de données MongoDB, l’instance IMongoDatabase est également enregistrée.

dotnet add package Aspire.MongoDB.Driver

Ajouter MongoDBclient

Dans le fichier Program.cs de votre projet consommateur de client, appelez la méthode d’extension AddMongoDBClient sur n’importe quel IHostApplicationBuilder pour inscrire un IMongoClient à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddMongoDBClient(connectionName: "mongodb");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource MongoDBserver (ou de la ressource de base de données fournie) dans le projet hôte de l’application. En d’autres termes, lorsque vous appelez AddDatabase et fournissez un nom de mongodb ce même nom doit être utilisé lors de l’appel de AddMongoDBClient. Pour plus d’informations, consultez Ajouter MongoDBla ressourceserver et la ressource de base de données.

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

public class ExampleService(IMongoClient client)
{
    // Use client...
}

La IMongoClient est utilisée pour interagir avec la ressource MongoDBserver. Il peut être utilisé pour créer des bases de données qui ne sont pas déjà connues du projet hôte d’application. Lorsque vous définissez une ressource de base de données MongoDB dans votre hôte d’application, vous pouvez plutôt exiger que le conteneur d’injection de dépendances fournit une instance IMongoDatabase. Pour plus d’informations sur l’injection de dépendances, consultez l’injection de dépendances .NET.

Ajouter des clés MongoDBclient

Il peut arriver que vous souhaitiez inscrire plusieurs instances de IMongoDatabase avec différents noms de connexion. Pour inscrire les clients spécifiques MongoDB, appelez la méthode AddKeyedMongoDBClient :

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

Important

Lorsque vous utilisez des services à clé, il est prévu que votre ressource MongoDB 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 IMongoDatabase à 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")] IMongoDatabase mainDatabase,
    [FromKeyedServices("loggingDb")] IMongoDatabase loggingDatabase)
{
    // Use databases...
}

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

Configuration

L’intégration de base de données .NET AspireMongoDB fournit plusieurs approches et options de configuration pour répondre aux exigences et 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.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

La chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings. Prenons l'exemple suivant de la configuration MongoDBJSON :

{
  "ConnectionStrings": {
    "mongo": "mongodb://server:port/test",
  }
}

Considérez l’exemple suivant de configuration MongoDB Atlas JSON :

{
  "ConnectionStrings": {
    "mongo": "mongodb+srv://username:password@server.mongodb.net/",
  }
}

Pour plus d’informations sur la mise en forme de cette chaîne de connexion, consultez MongoDB: documentation ConnectionString.

Utiliser des fournisseurs de configuration

L’intégration .NET AspireMongoDB prend en charge Microsoft.Extensions.Configuration. Il charge le MongoDBSettings à partir de la configuration à l’aide de la clé Aspire:MongoDB:Driver. L’extrait de code suivant est un exemple de fichier appsettings.json qui configure certaines des options :

{
  "Aspire": {
    "MongoDB": {
      "Driver": {
        "ConnectionString": "mongodb://server:port/test",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      },
    }
  }

Utiliser des configurations intégrées

Vous pouvez également passer le délégué Action<MongoDBSettings> pour configurer certaines ou toutes les options directement :

builder.AddMongoDBClient("mongodb",
    static settings => settings.ConnectionString = "mongodb://server:port/test");

Options de configuration

Voici les options configurables avec les valeurs par défaut correspondantes :

Nom Description
ConnectionString Chaîne de connexion de la base de données MongoDB à laquelle se connecter.
DisableHealthChecks Valeur booléenne qui indique si la vérification d’intégrité de la base de données est désactivée ou non.
HealthCheckTimeout Valeur int? qui indique le délai d’expiration du contrôle d’intégrité MongoDB en millisecondes.
DisableTracing Valeur booléenne qui indique si le suivi OpenTelemetry est désactivé ou non.

Vérifications d’intégrité

Par défaut, les .NET.NET Aspire intégrations activent les vérifications de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

Par défaut, l’intégration .NET AspireMongoDBclient gère les scénarios suivants :

  • Ajoute une vérification d'intégrité lorsqu'elle est activée qui vérifie qu'une connexion peut être établie et que des commandes peuvent être effectuées sur la base de données MongoDB dans un certain délai.
  • S’intègre au point de terminaison HTTP /health, qui spécifie que tous les contrôles de santé enregistrés doivent être validés 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 de base de données .NET AspireMongoDB utilise la journalisation standard de .NET, et dans les catégories suivantes, vous trouverez les entrées de journal :

  • MongoDB[.*]: toutes les entrées de journal de l’espace de noms MongoDB.

Traçage

L’intégration de base de données .NET AspireMongoDB émet les activités de traçage suivantes à l’aide de OpenTelemetry:

  • MongoDB.Driver.Core.Extensions.DiagnosticSources

Métriques

L’intégration de base de données .NET AspireMongoDB n’expose actuellement aucune métrique OpenTelemetry.

Voir aussi