Démarrage rapide : Azure Cosmos DB for MongoDB pour .NET avec pilote MongoDB

S’APPLIQUE À : MongoDB

Bien démarrer avec MongoDB pour créer des bases de données, des collections et des documents dans votre ressource Azure Cosmos DB. Suivez ces étapes pour déployer une solution minimale sur votre environnement à l’aide de l’interface Azure Developer CLI.

Documentation de référence sur l’API pour MongoDB | Package MongoDB (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

Prérequis

Configuration

Déployez le conteneur de développement de ce projet sur votre environnement. Utilisez ensuite l’interface Azure Developer CLI (azd) pour créer un compte Azure Cosmos DB for MongoDB et déployer un exemple d’application conteneurisée. L’exemple d’application utilise la bibliothèque de client pour gérer, créer, lire et interroger des exemples de données.

1. Ouvrez un terminal dans le répertoire racine du projet.

2. Authentifiez-vous auprès de l’interface Azure Developer CLI en utilisant azd auth login. Suivez les étapes spécifiées par l’outil pour vous authentifier auprès de l’interface CLI à l’aide de vos informations d’identification Azure préférées.

   azd auth login
   

3. Utilisez azd init pour initialiser le projet.

   azd init --template cosmos-db-mongodb-dotnet-quickstart
   

   Remarque

   Ce guide de démarrage rapide utilise le référentiel GitHub du modèle azure-samples/cosmos-db-mongodb-dotnet-quickstart. Azure Developer CLI clone automatiquement ce projet sur votre machine s’il ne s’y trouve pas déjà.

4. Lors de l’initialisation, configurez un nom d’environnement unique.

   Conseil

   Le nom de l’environnement sera également utilisé comme nom du groupe de ressources cible. Pour ce guide de démarrage rapide, utilisez msdocs-cosmos-db.

5. Déployez le compte Azure Cosmos DB en utilisant azd up. Les modèles Bicep déploient également un exemple d’application web.

   azd up
   

6. Pendant le processus d’approvisionnement, sélectionnez votre abonnement et l’emplacement souhaité. Attendez la fin du processus de provisionnement. Le processus peut prendre environ cinq minutes.

7. Une fois le provisionnement de vos ressources Azure effectué, une URL vers l’application web en cours d’exécution est incluse dans la sortie.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Utilisez l’URL dans la console pour accéder à votre application web dans le navigateur. Observez la sortie de l’application en cours d’exécution.

   

Installer la bibliothèque de client

La bibliothèque cliente est disponible via NuGet, en tant que package Microsoft.Azure.Cosmos.

1. Ouvrez un terminal et accédez au dossier /src/web.

   cd ./src/web
   

2. S’il n’est pas déjà installé, installez le package MongoDb.Driver à l’aide de dotnet add package.

   dotnet add package MongoDb.Driver
   

3. Installez également le package Azure.Identity, s’il n’est pas déjà installé.

   dotnet add package Azure.Identity
   

Modèle objet

Avant de commencer à générer l’application, examinons la hiérarchie des ressources dans Azure Cosmos DB. Azure Cosmos DB a un modèle objet spécifique utilisé pour créer et accéder aux ressources. Azure Cosmos DB crée des ressources dans une hiérarchie qui se compose de comptes, de bases de données, de collections et de documents.

Utilisez les classes MongoDB suivantes pour interagir avec ces ressources :

• MongoClient - Cette classe fournit une représentation logique côté client pour la couche d’API for MongoDB dans Cosmos DB. Ce client est utilisé pour configurer et exécuter des requêtes sur le service.
• MongoDatabase : cette classe est une référence à une base de données qui peut exister ou non dans le service. La base de données est validée côté serveur lorsque vous tentez d’y accéder ou d’effectuer une opération sur celle-ci.
• Collection : cette classe est une référence à une collection qui n’existe peut-être pas encore dans le service. La collection est validée côté serveur lorsque vous tentez de l’utiliser.

Exemples de code

• Authentifier le client
• Créer une base de données
• Créer un conteneur
• Créer un élément
• Obtenir un élément
• Éléments de requête

L’exemple de code de cet article crée une base de données nommée adventureworks avec une collection nommée products. La collection products est conçue pour contenir des détails de produit comme le nom, la catégorie, la quantité et un indicateur de vente. Chaque produit contient également un identificateur unique.

Authentifier le client

À partir du répertoire de projet, ouvrez le fichier Program.cs. Dans votre éditeur, ajoutez une directive d’utilisation pour MongoDB.Driver.

using MongoDB.Driver;

Définissez une nouvelle instance de la classe MongoClient à l’aide du constructeur et Environment.GetEnvironmentVariable pour lire la chaîne de connexion définie précédemment par Azure Developer CLI.

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

Création d'une base de données

Utilisez la méthode MongoClient.GetDatabase pour créer uniquement une base de données si elle n’existe pas déjà. Cette méthode retourne une référence à la base de données existante ou nouvellement créée.

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

Création d'une collection

MongoDatabase.GetCollection crée une collection si elle n’existe pas déjà et retourne une référence à la collection.

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

Créer un élément

Le moyen le plus simple de créer un élément dans une collection est de créer une classe C# ou un type d’enregistrement avec tous les membres que vous souhaitez sérialiser en JSON. Dans cet exemple, l’enregistrement C# a un identificateur unique, un champ catégorie pour la clé de partition et un nom supplémentaire, une quantité et des champs vente.

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

Créez un élément dans la collection utilisant l’enregistrement Product en appelant IMongoCollection<TDocument>.InsertOne.

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

Obtenir un élément

Dans Azure Cosmos DB, vous pouvez récupérer des éléments en composant des requêtes utilisant Linq. Dans le SDK, appelez IMongoCollection.FindAsync<> et transmettez une expression C# pour filtrer les résultats.

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

Éléments de requête

Après avoir inséré un élément, vous pouvez exécuter une requête pour obtenir tous les éléments qui correspondent à un filtre spécifique en traitant la collection en tant que IQueryable. Cet exemple utilise une expression pour filtrer les produits par catégorie. Une fois l’appel à AsQueryable effectué, appelez MongoQueryable.Where pour récupérer un ensemble d’éléments filtrés.

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

Exécuter le code

Cette application crée une base de données et une collection d’API MongoDB Azure Cosmos DB. L’exemple crée ensuite un élément, puis lit exactement le même élément. Enfin, l’exemple crée un deuxième élément, puis effectue une requête qui doit retourner plusieurs éléments. Avec chaque étape, l’exemple génère des métadonnées dans la console sur les étapes effectuées.

Pour exécuter l’application, utilisez un terminal pour accéder au répertoire de l’application et exécuter l’application.

dotnet run

La sortie de l’application doit être similaire à l’exemple suivant :

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Nettoyer les ressources

Une fois que vous n’avez plus besoin du compte Azure Cosmos DB for MongoDB, vous pouvez supprimer le groupe de ressources correspondant.

az group delete --name $resourceGroupName

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters