Partager via

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

Inclut :Intégration de l’hébergement incluse intégration d’hébergement —&— Client intégration incluseClient

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

Intégration de l’hébergement

Le serveur MongoDB hébergeant les modèles d’intégration du serveur 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 Manage package dependencies in .NET applications.

Ajouter MongoDB ressource de serveur 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 de serveur MongoDB. 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...

Remarque

Le MongoDB conteneur 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 plus d’informations, consultez La durée de vie des ressources 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 de serveur MongoDB (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 de serveur MongoDB 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 et ASP.NET CoreAjouter MongoDB une ressource de serveur 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 à un serveur MongoDB existant, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter MongoDB ressource de serveur avec un volume de données

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

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 du serveur MongoDB en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin d’accès /data/db dans le conteneur du serveur MongoDB et lorsqu’un paramètre name n’est pas fourni, le nom est généré au hasard. 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 la 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.

Important

Certaines des intégrations de base de données, y compris l’intégration .NET AspireMongoDB, ne peuvent pas réussir à utiliser les volumes de données après le déploiement vers Azure Container Apps (ACA). Cela est dû au fait que L’ACA utilise Server Le bloc de messages (SMB) pour connecter des conteneurs à des volumes de données, et certains systèmes ne peuvent pas utiliser cette connexion. Dans le Aspire tableau de bord, une base de données affectée par ce problème a un état d’activation ou d’échec de l’activation , mais elle n’est jamais répertoriée comme en cours d’exécution.

Vous pouvez résoudre le problème en déployant sur un cluster Kubernetes, tel qu'AzureKubernetes Services (AKS). Pour plus d'informations, consultez les déploiements .NET.NET Aspire.

Ajoutez la ressource serveur MongoDB avec un montage de liaison de fichiers.

Pour ajouter un montage de liaison de données à la ressource de serveur MongoDB, 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 , qui offrent de meilleures performances, une meilleure portabilité et une plus grande 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 du serveur MongoDB entre les redémarrages de conteneur. Le point de montage de liaison de données est monté au chemin d'accès C:\MongoDB\Data sur Windows (ou /MongoDB/Data sur Unix) sur la machine hôte, dans le conteneur du serveur MongoDB. Pour plus d’informations sur les montages de liaison de données, consultez Docker la documentation : Montages de liaison.

Ajoutez la ressource serveur MongoDB avec montage de liaison pour les données d'initialisation

Pour ajouter un montage de fichiers et de données d’initialisation à la ressource de serveur MongoDB, 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 données d'initialisation est utilisé pour initialiser le serveur MongoDB avec des données. Le montage de liaison de données d'initialisation est monté au chemin C:\MongoDB\Init sous Windows (ou /MongoDB/Init sur Unix) sur la machine hôte dans le conteneur serveur MongoDB et se rapporte au chemin /docker-entrypoint-initdb.d dans le conteneur serveur MongoDB. 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 MongoDB ressource de serveur 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 web MongoDB . Pour ajouter une MongoDB ressource Express qui correspond à l’imagedocker.io/library/mongo-express conteneur, appelez la WithMongoExpress méthode sur la ressource serveur MongoDB :

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 de serveur MongoDB. 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 de serveur MongoDB. La vérification d’intégrité vérifie que la ressource de serveur MongoDB est en cours d’exécution et qu’une connexion peut être établie à celui-ci.

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

intégration de Client

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

dotnet add package Aspire.MongoDB.Driver

Important

Le package NuGet Aspire.MongoDB.Driver dépend du package NuGet MongoDB.Driver. Avec la version 3.0.0 de MongoDB.Driver, une modification de rupture binaire a été introduite. Pour résoudre ce problème, un nouveau package d’intégration client, Aspire.MongoDB.Driver.v3, a été créé. Le package d’origine Aspire.MongoDB.Driver continue de référencer MongoDB.Driver la version 2.30.0, ce qui garantit la compatibilité avec les versions précédentes de l’intégration du RabbitMQ client. Le nouveau Aspire.MongoDB.Driver.v3 package fait référence à MongoDB.Driver la version 3.0.0. Dans une version ultérieure de .NET.NET Aspire, le Aspire.MongoDB.Driver sera mis à jour vers la version 3.x et le package Aspire.MongoDB.Driver.v3 sera déconseillé. Pour plus d’informations, consultez Mettre à niveau vers la version 3.0.

Ajouter MongoDB client

Dans le fichier Program.cs de votre projet client, appelez la méthode d'extension AddMongoDBClient sur n'importe quel IHostApplicationBuilder afin d'enregistrer un IMongoClient pour son utilisation 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 serveur MongoDB (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 MongoDB une ressource de serveur et une 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 de serveur MongoDB. 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 .NET l’injection de dépendances.

Ajouter un client MongoDB avec clé

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 l’injection de dépendances : services à clé.

Paramétrage

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 MongoDBla 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 Descriptif
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.

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

Par défaut, les intégrations de clients .NET.NET Aspire ont les contrôles de santé activés pour tous les services. De même, de nombreuses intégrations d'hébergement .NET.NET Aspire activent également les endpoints de vérification de santé. Pour plus d’informations, consultez :

Par défaut, l’intégration du client .NET AspireMongoDB 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 les intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées piliers de l’observabilité. Pour plus d’informations sur l’observabilité et la télémétrie d’intégration, consultez .NET.NET Aspire la 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