Partager via

Créer une application console .NET avec Azure DocumentDB

Ce guide montre comment créer une application console .NET pour se connecter à un cluster Azure DocumentDB. Vous configurez votre environnement de développement, utilisez la Azure.Identity bibliothèque à partir du Kit de développement logiciel (SDK) Azure pour .NET pour vous authentifier et interagir avec la base de données pour créer, interroger et mettre à jour des documents.

Prerequisites

  • Un abonnement Azure

  • Un cluster Azure DocumentDB existant

    • Si vous n’avez pas de cluster, créez un cluster

Récupérer les métadonnées de l'instance Microsoft Entra

Pour récupérer un jeton d'accès à l'aide de la classe TokenCredential dans Azure.Identity, il vous faut l'identificateur unique du locataire Microsoft Entra. Dans cette étape requise, utilisez Azure CLI pour récupérer et enregistrer la tenantId valeur.

  1. Obtenez les détails de l'abonnement Azure actuellement en cours de session en utilisant az account show.

    az account show

  2. La commande génère une réponse JSON contenant différents champs.

    {
  "environmentName": "AzureCloud",
  "homeTenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "id": "dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
  "isDefault": true,
  "managedByTenants": [],
  "name": "example-azure-subscription",
  "state": "Enabled",
  "tenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "user": {
    "cloudShellID": true,
    "name": "kai@adventure-works.com",
    "type": "user"
  }
}

  3. Enregistrez la valeur de la tenantId propriété. Cette propriété est l’identificateur unique de votre locataire Microsoft Entra et est parfois appelée ID de locataire. Vous utilisez cette valeur dans les étapes d’une section suivante.

Configurer votre application console

Ensuite, créez un projet d’application console et importez les bibliothèques nécessaires pour vous authentifier auprès de votre cluster.

  1. Dans un répertoire vide, créez une application console .NET.

    dotnet new console

  2. Importez le Azure.Identity package à partir de NuGet.

    dotnet add package Azure.Identity

  3. Ensuite, importez le MongoDB.Driver package.

    dotnet add package MongoDB.Driver

  4. Générer le projet .NET

    dotnet build

Se connecter au cluster

À présent, utilisez la bibliothèque Azure.Identity pour obtenir un TokenCredential à utiliser afin de vous connecter à votre cluster. Le pilote MongoDB officiel a une interface spéciale qui doit être implémentée pour obtenir des jetons de Microsoft Entra à utiliser lors de la connexion au cluster.

  1. Dans le fichier Program.cs, ajoutez des blocs d’utilisation pour ces espaces de noms Azure.Identity et MongoDB.Driver.

    using Azure.Identity;
using MongoDB.Driver;

  2. Créez une classe dans un fichier distinct qui implémente tous les membres requis de l’interface MongoDB.Driver.Authentication.Oidc.IOidcCallback .

    using Azure.Core;
using MongoDB.Driver.Authentication.Oidc;

internal sealed class AzureIdentityTokenHandler(
    TokenCredential credential,
    string tenantId
) : IOidcCallback
{
    private readonly string[] scopes = ["https://ossrdbms-aad.database.windows.net/.default"];

    public OidcAccessToken GetOidcAccessToken(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = credential.GetToken(
            new TokenRequestContext(scopes, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }

    public async Task<OidcAccessToken> GetOidcAccessTokenAsync(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(
            new TokenRequestContext(scopes, parentRequestId: null, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }
}

    Conseil / Astuce

    À des fins d’illustration, cette classe est nommée AzureIdentityTokenHandler. Vous pouvez nommer cette classe comme vous le souhaitez. Le reste de ce guide suppose que la classe est nommée AzureIdentityTokenHandler.

  3. Revenez à l’éditeur du fichier Program.cs .

  4. Créez une variable de chaîne avec le nom de votre cluster existant. Ensuite, utilisez cette variable pour créer une instance de type MongoUrl à l’aide de MongoUrl.Create

    string clusterName = "<azure-documentdb-cluster-name>";

MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");

  5. Configurez une nouvelle instance MongoSettings en utilisant ce qui a été créé avec MongoUrl lors des étapes précédentes, et appliquez la configuration standard selon les meilleures pratiques pour Azure DocumentDB.

    MongoClientSettings settings = MongoClientSettings.FromUrl(url);

settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);

  6. Créez un nouvel identifiant de type DefaultAzureCredential.

    DefaultAzureCredential credential = new();

    Conseil / Astuce

    Vous pouvez utiliser les informations d’identification de type TokenCredential ici. DefaultAzureCredential est l'option la plus fluide pour les scénarios de développement précoces.

  7. Créez une instance de votre classe qui implémente IOidcCallback et configurez-la avec l’ID de locataire que vous avez enregistré précédemment dans ce guide.

    string tenantId = "<microsoft-entra-tenant-id>";

AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);

  8. Configurez les informations d’identification de vos paramètres à l’aide de MongoCredential.CreateOidcCredential et en y passant votre implémentation de rappel de gestionnaire personnalisé.

    settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);

  9. Bloquez les paramètres, puis créez une nouvelle instance de MongoClient.

    settings.Freeze();

MongoClient client = new(settings);

Console.WriteLine("Client created");

Effectuer des opérations courantes

Enfin, utilisez la bibliothèque officielle pour effectuer des tâches courantes avec des bases de données, des collections et des documents. Ici, vous utilisez les mêmes classes et méthodes que celles que vous utiliseriez pour interagir avec MongoDB ou DocumentDB pour gérer vos collections et éléments.

  1. Représentez vos documents en créant un type d’enregistrement personnalisé dans un fichier distinct.

    public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

    Conseil / Astuce

    À des fins d’illustration, ce struct est nommé Product. Le reste de ce guide suppose que vous avez déjà défini ce struct.

  2. Revenez au fichier Program.cs .

  3. Obtenez un pointeur vers votre base de données à l’aide de MongoClient.GetDatabase.

    string databaseName = "<database-name>";

IMongoDatabase database = client.GetDatabase(databaseName);

Console.WriteLine("Database pointer created");

  4. Ensuite, utilisez le pointeur de base de données pour obtenir un pointeur vers votre collection en utilisant IMongoDatabase.GetCollection<>.

    string collectionName = "<collection-name>";

IMongoCollection<Product> collection = database.GetCollection<Product>(collectionName);

Console.WriteLine("Collection pointer created");

  5. Créez et upsertez deux documents à l’aide de la IMongoCollection<>.ReplaceOneAsync méthode.

    Product classicSurfboard = new(
    id: "bbbbbbbb-1111-2222-3333-cccccccccccc",
    category: "gear-surf-surfboards",
    name: "Kiama Classic Surfboard",
    quantity: 25,
    price: 790.00m,
    clearance: false
);

Product paddleKayak = new(
    id: "cccccccc-2222-3333-4444-dddddddddddd",
    category: "gear-paddle-kayaks",
    name: "Lastovichka Paddle Kayak",
    quantity: 10,
    price: 599.99m,
    clearance: true
);

await collection.ReplaceOneAsync<Product>(
    doc => doc.id == classicSurfboard.id,
    classicSurfboard,
    new ReplaceOptions { IsUpsert = true }
);

Console.WriteLine($"Upserted document:\t{classicSurfboard.id}");

await collection.ReplaceOneAsync<Product>(
    doc => doc.id == paddleKayak.id,
    paddleKayak,
    new ReplaceOptions { IsUpsert = true }
);

Console.WriteLine($"Upserted document:\t{paddleKayak.id}");

  6. Lire un document unique de la collection à l’aide IMongoCollection<>.Find et IFindFluent<,>.SingleAsync. Utilisez un filtre pour spécifier le document spécifique que vous souhaitez rechercher.

    Product document = await collection.Find(
    doc => doc.id == "cccccccc-2222-3333-4444-dddddddddddd"
).SingleAsync();

Console.WriteLine($"Found document:\t{document.name}");

  7. Recherchez tous les documents qui correspondent à un filtre à l’aide de la même Find méthode. Utilisez un filtre pour définir une propriété spécifique (comme category) et une valeur spécifique (par exemple gear-surf-surfboards). Énumérez les résultats à l’aide de IFindFluent<,>.ToListAsync.

    List<Product> documents = await collection.Find(
    doc => doc.category == "gear-surf-surfboards"
).ToListAsync();

foreach (Product doc in documents)
{
    Console.WriteLine($"Queried document:\t{doc}");
}

  8. Supprimez un document spécifique de la collection à l’aide IMongoCollection<>.DeleteOneAsync et un filtre.

    await collection.DeleteOneAsync(
    doc => doc.id == "bbbbbbbb-1111-2222-3333-cccccccccccc"
);

Console.WriteLine($"Deleted document");

  9. Enregistrez tous les fichiers de code dans le projet.

  10. Exécuter le projet à l’aide de dotnet run

    dotnet run

  11. Observez la sortie de l’application en cours d’exécution.

    Client created
Database pointer created
Collection pointer created
Upserted document:      bbbbbbbb-1111-2222-3333-cccccccccccc
Upserted document:      cccccccc-2222-3333-4444-dddddddddddd
Found document: Lastovichka Paddle Kayak
Queried document:       Product { id = bbbbbbbb-1111-2222-3333-cccccccccccc, category = gear-surf-surfboards, name = Kiama Classic Surfboard, quantity = 25, price = 790.00, clearance = False }
Deleted document

Contenu connexe

  • Last updated on