Snabbstart: Använda Azure Cosmos DB för MongoDB vCore med MongoDB-drivrutin för .NET

I den här snabbstarten distribuerar du ett grundläggande Azure Cosmos DB for MongoDB vCore-program med hjälp av .NET. Azure Cosmos DB for MongoDB vCore är ett schemalöst datalager som gör att program kan lagra ostrukturerade dokument i molnet med MongoDB-bibliotek. Du lär dig hur du skapar dokument och utför grundläggande uppgifter i din Azure Cosmos DB-resurs med hjälp av .NET.

Bibliotekets källkod | Package (NuGet) | Azure Developer CLI

Förutsättningar

• Azure Developer CLI

• Docker Desktop

• En prenumeration på Azure

  • Om du inte har en Azure-prenumeration, skapa ett gratis konto innan du börjar.

• .NET SDK 9.0

Initiera projektet

Använd Azure Developer CLI (azd) för att skapa ett Azure Cosmos DB for MongoDB vCore-kluster och distribuera ett containerbaserat exempelprogram. Exempelprogrammet använder klientbiblioteket för att hantera, skapa, läsa och fråga efter exempeldata.

1. Öppna en terminal i en tom katalog.

2. Om du inte redan är autentiserad autentiserar du till Azure Developer CLI med hjälp av azd auth login. Följ stegen som anges av verktyget för att autentisera till CLI med dina önskade Azure-autentiseringsuppgifter.

   azd auth login
   

3. Använd azd init för att initiera projektet.

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

4. Under initieringen konfigurerar du ett unikt miljönamn.

5. Distribuera klustret med .azd up Bicep-mallarna installerar också en exempelwebbapplikation.

   azd up
   

6. Under etableringsprocessen väljer du din prenumeration, önskad plats och målresursgrupp. Vänta tills försörjningsprocessen har slutförts. Processen kan ta ungefär fem minuter.

7. När etableringen av dina Azure-resurser är klar inkluderas en URL till det webbprogram som körs i utdata.

   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. Använd URL:en i konsolen för att navigera till webbprogrammet i webbläsaren. Observera utdata från appen som körs.

Installera klientbiblioteket

Klientbiblioteket är tillgängligt via NuGet som MongoDB.Driver paket. För Microsoft Entra-autentisering använder du Azure.Identity paketet från Azure SDK för .NET.

1. Öppna en terminal och navigera till /src/web mappen.

   cd ./src/web
   

2. Om det inte redan är installerat, installera MongoDB.Driver-paketet med hjälp av dotnet add package.

   dotnet add package MongoDB.Driver
   

3. Installera paketet om det Azure.Identity inte redan är installerat.

   dotnet add package Azure.Identity
   

4. Öppna och granska filen src/api/Microsoft.Learn.AzureCosmosDBMongoDBQuickstart.Api.csproj för att verifiera att båda paketposterna finns.

Importera bibliotek

Importera följande namnområden till programkoden:

using Azure.Core;
using Azure.Identity;

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

Objektmodell

Kodexempel

• Autentisera klienten
• Hämta en databas
• Hämta en samling
• Skapa ett dokument
• Hämta ett dokument
• Söka i dokument
• Ta bort ett dokument

Exempelkoden i mallen använder en databas med namnet cosmicworks och samlingen med namnet products. Samlingen products innehåller information som namn, kategori, kvantitet och en unik identifierare för varje produkt. Samlingen använder egenskapen /category som en fragmentnyckel.

Autentisera klienten

Microsoft Entra-autentisering för Azure Cosmos DB for MongoDB vCore kan använda välkända TokenCredential typer, men du måste implementera en anpassad tokenhanterare. Den här exempelimplementeringen kan användas för att skapa en MongoClient med stöd för Microsoft Entra-standardautentisering av många identitetstyper.

1. Skapa först en ny klass i en separat fil som implementerar IOidcCallback gränssnittet.

   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. Skapa en ny instans av din anpassade hanteringsklass som skickar in en ny instans av DefaultAzureCredential typen och ditt klient-ID.

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

3. Skapa en instans av MongoUrl med hjälp av slutpunkten och schemat för din Azure Cosmos DB for MongoDB vCore-instans som nyligen distribuerats.

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

4. Konfigurera din MongoClient instans med hjälp av kända best practice-konfigurationsalternativ för Azure Cosmos DB för MongoDB vCore och anpassad IOidcCallback implementering.

   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);
   

Få tillgång till en databas

Det här exemplet skapar en instans av gränssnittet IMongoDatabase med hjälp av metoden GetDatabase i klassen MongoClient.

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

Hämta en samling

Det här exemplet skapar en instans av det generiska IMongoCollection<> gränssnittet med hjälp av gränssnittets GetCollection<>IMongoDatabase allmänna metod. Det generiska gränssnittet och -metoden använder båda en typ med namnet Product definierat i en annan klass.

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

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

Skapa ett dokument

Skapa ett dokument i samlingen med hjälp av collection.ReplaceOneAsync<> och den generiska typparametern Product. Den här metoden uppdaterar eller lägger till dokumentet och ersätter det, om det redan finns i samlingen.

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 }
);

Läsa ett dokument

Utför en läsåtgärd med hjälp av både den unika identifieraren (id) för dokumenten. Använd collection.FindAsync<> med den generiska typparametern Product för att effektivt hämta det specifika dokumentet.

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

Sök dokument

Utföra en fråga över flera dokument i en container med hjälp av collection.AsQueryable() och språkintegrerad fråga (LINQ). Den här sökfrågan hittar alla dokument inom en angiven kategori (shard-nyckel).

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

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

Ta bort ett dokument

Ta bort ett dokument genom att skicka ett filter för dokumentets unika identifierare. Använd collection.DeleteOneAsync<> för att asynkront ta bort dokumentet från samlingen.

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

Utforska dina data

Använd Visual Studio Code-tillägget för Azure Cosmos DB för att utforska dina MongoDB vCore-data. Du kan utföra grundläggande databasåtgärder, inklusive, men inte begränsat till:

• Utföra sökningar med hjälp av ett skrivblock eller frågeredigeraren
• Ändra, uppdatera, skapa och ta bort dokument
• Importera massdata från andra källor
• Hantera databaser och samlingar

Mer information finns i Använda Visual Studio Code-tillägget för att utforska Azure Cosmos DB for MongoDB vCore-data.

Rensa resurser

När du inte längre behöver exempelprogrammet eller resurserna tar du bort motsvarande distribution och alla resurser.

azd down --force

Relaterat innehåll

• Node.js snabbstart
• Snabbstart för Python