Quickstart: Azure Cosmos DB voor MongoDB vCore gebruiken met MongoDB-stuurprogramma voor .NET

In deze quickstart implementeert u een eenvoudige Azure Cosmos DB voor MongoDB vCore-toepassing met behulp van .NET. Azure Cosmos DB voor MongoDB vCore is een schemaloos gegevensarchief waarmee toepassingen ongestructureerde documenten kunnen opslaan in de cloud met MongoDB-bibliotheken. U leert hoe u documenten maakt en basistaken uitvoert in uw Azure Cosmos DB-resource met behulp van .NET.

Broncode van bibliotheek | Package (NuGet) | Azure Developer CLI

Vereiste voorwaarden

• Azure-ontwikkelaars-CLI

• Docker Desktop

• Een Azure-abonnement

  • Als je geen Azure-abonnement hebt, maak dan een gratis account aan voordat je begint.

• .NET SDK 9.0

Het project initialiseren

Gebruik de Azure Developer CLI (azd) om een Azure Cosmos DB voor MongoDB vCore-cluster te maken en een in een container geplaatste voorbeeldtoepassing te implementeren. De voorbeeldtoepassing maakt gebruik van de clientbibliotheek voor het beheren, maken, lezen en opvragen van voorbeeldgegevens.

1. Open een terminal in een lege map.

2. Als u nog niet bent geverifieerd, moet u zich verifiëren bij de Azure Developer CLI met behulp van azd auth login. Volg de stappen die door het hulpprogramma zijn opgegeven om te verifiëren bij de CLI met behulp van uw favoriete Azure-referenties.

   azd auth login
   

3. Gebruik azd init om het project te initialiseren.

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

4. Configureer tijdens de initialisatie een unieke omgevingsnaam.

5. Implementeer het cluster met behulp van azd up. De Bicep-sjablonen implementeren ook een voorbeeldwebtoepassing.

   azd up
   

6. Selecteer tijdens het inrichtingsproces uw abonnement, gewenste locatie en doelresourcegroep. Wacht tot het provisioningproces is voltooid. Het proces kan ongeveer vijf minuten duren.

7. Zodra het inrichten van uw Azure-resources is voltooid, wordt er een URL naar de actieve webtoepassing opgenomen in de uitvoer.

   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. Gebruik de URL in de console om naar uw webtoepassing in de browser te navigeren. Bekijk de uitvoer van de actieve app.

De clientbibliotheek installeren

De clientbibliotheek is beschikbaar via NuGet, als pakket MongoDB.Driver . Voor Microsoft Entra-verificatie gebruikt u het Azure.Identity pakket van de Azure SDK voor .NET.

1. Open een terminal en navigeer naar de /src/web map.

   cd ./src/web
   

2. Als dit nog niet is geïnstalleerd, installeert u het MongoDB.Driver pakket met behulp van dotnet add package.

   dotnet add package MongoDB.Driver
   

3. Als dit nog niet is geïnstalleerd, installeert u het Azure.Identity pakket.

   dotnet add package Azure.Identity
   

4. Open en controleer het bestand src/api/Microsoft.Learn.AzureCosmosDBMongoDBQuickstart.Api.csproj om te controleren of beide pakketvermeldingen bestaan.

Bibliotheken importeren

Importeer de volgende naamruimten in uw toepassingscode:

using Azure.Core;
using Azure.Identity;

using MongoDB.Driver;
using MongoDB.Driver.Authentication.Oidc;

Objectmodel

Codevoorbeelden

• De client verifiëren
• Een database ophalen
• Een verzameling verkrijgen
• Een document maken
• Een document ophalen
• Documenten opvragen
• Een document verwijderen

De voorbeeldcode in de sjabloon maakt gebruik van een database met de naam cosmicworks en verzameling.products De products verzameling bevat details zoals naam, categorie, hoeveelheid en een unieke id voor elk product. De verzameling gebruikt de /category eigenschap als een shard key.

De client verifiëren

Hoewel Microsoft Entra-verificatie voor Azure Cosmos DB voor MongoDB vCore bekende TokenCredential typen kan gebruiken, moet u een aangepaste tokenhandler implementeren. Deze voorbeeldimplementatie kan worden gebruikt om een MongoClient met ondersteuning voor standaard Microsoft Entra-verificatie voor veel verschillende identiteitstypen te maken.

1. Maak eerst een nieuwe klasse in een afzonderlijk bestand dat interface implementeert 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);
       }
   }
   

2. Maak een nieuw exemplaar van uw aangepaste handlerklasse die een nieuw exemplaar van het DefaultAzureCredential type en uw tenant-id doorgeeft.

   DefaultAzureCredential credential = new();
   
   string tenantId = "<microsoft-entra-tenant-id>";
   
   AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
   

3. Maak een exemplaar van MongoUrl met behulp van het eindpunt en het schema voor uw onlangs geïmplementeerde Azure Cosmos DB voor MongoDB vCore-instantie.

   string clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>";
   
   MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");
   

4. Configureer uw MongoClient exemplaar met behulp van bekende best practice-configuratieopties voor Azure Cosmos DB voor MongoDB vCore en de aangepaste IOidcCallback implementatie.

   MongoClientSettings settings = MongoClientSettings.FromUrl(url);
   
   settings.UseTls = true;
   settings.RetryWrites = false;
   settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);
   settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
   settings.Freeze();
   
   MongoClient client = new(settings);
   

Een database ophalen

In dit voorbeeld wordt een exemplaar van de IMongoDatabase interface gemaakt met behulp van de GetDatabase methode van de MongoClient klasse.

IMongoDatabase database = client.GetDatabase("<database-name>");

Een verzameling ophalen

In dit voorbeeld wordt een exemplaar van de algemene IMongoCollection<> interface gemaakt met behulp van de GetCollection<> algemene methode van de IMongoDatabase interface. De algemene interface en methode gebruiken allebei een type genaamd Product, dat is gedefinieerd in een andere klasse.

IMongoCollection<Product> collection = database.GetCollection<Product>("<collection-name>");

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

Een document maken

Maak een document in de verzameling met behulp van een collection.ReplaceOneAsync<> met de generieke typeparameter Product. Met deze methode wordt het document bijgewerkt of toegevoegd, effectief vervangend als het al bestaat in de verzameling.

Product document = new(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    price: 850.00m,
    clearance: false
);

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

Een document lezen

Voer een leesbewerking uit door gebruik te maken van de unieke identificatie (id) voor de documenten. Gebruik collection.FindAsync<> met de algemene Product-typeparameter om het specifieke document efficiënt op te halen.

Product? document = await collection.Find(
    doc => doc.id == "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
).SingleOrDefaultAsync();

Documenten opvragen

Voer een query uit op meerdere documenten in een container met behulp van collection.AsQueryable() een LINQ (Language Integrated Query). Met deze query worden alle documenten in een opgegeven categorie (shardsleutel) gevonden.

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

foreach (Product document in documents)
{
    // Do something with each document
}

Een document verwijderen

Een document verwijderen door een filter te verzenden voor de unieke id van het document. Gebruik collection.DeleteOneAsync<> dit om het document asynchroon uit de verzameling te verwijderen.

await collection.DeleteOneAsync(
    doc => doc.id == "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
);

Uw gegevens verkennen

Gebruik de Visual Studio Code-extensie voor Azure Cosmos DB om uw MongoDB vCore-gegevens te verkennen. U kunt kerndatabasebewerkingen uitvoeren, waaronder, maar niet beperkt tot:

• Query's uitvoeren met behulp van een scrapbook of de query-editor
• Documenten wijzigen, bijwerken, maken en verwijderen
• Bulkgegevens importeren uit andere bronnen
• Databases en verzamelingen beheren

Zie voor meer informatie Hoe de Visual Studio Code-extensie te gebruiken om Azure Cosmos DB voor MongoDB vCore-gegevens te verkennen.

Hulpmiddelen opruimen

Wanneer u de voorbeeldtoepassing of resources niet meer nodig hebt, verwijdert u de bijbehorende implementatie en alle resources.

azd down --force

Verwante inhoud

• Snelstartgids voor Node.js
• Python-quickstart