Schnellstart: Azure Cosmos DB for MongoDB für .NET mit dem MongoDB-Treiber

Artikel
03/29/2024

GILT FÜR: MongoDB

Erste Schritte mit MongoDB zum Erstellen von Datenbanken, Sammlungen und Dokumenten in Ihrer Azure Cosmos DB-Ressource. Führen Sie die folgenden Schritte aus, um mithilfe von Azure Developer CLI eine minimale Lösung für Ihre Umgebung bereitzustellen.

Referenzdokumentation der API für MongoDB | MongoDB-Paket (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
GitHub-Konto

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Azure Developer CLI
Docker Desktop

Einrichten

Stellen Sie den Entwicklungscontainer dieses Projekts in Ihrer Umgebung bereit. Verwenden Sie dann das Azure Developer CLI (azd), um ein Azure Cosmos DB for MongoDB-Konto zu erstellen und eine containerisierte Beispielanwendung bereitzustellen. Die Beispielanwendung verwendet die Clientbibliothek zum Verwalten, Erstellen, Lesen und Abfragen von Beispieldaten.

Wichtig

GitHub-Konten enthalten eine Berechtigung für Speicher und Kernstunden, für die jeweils keine Kosten anfallen. Weitere Informationen finden Sie unter Monatlich enthaltene Speicherkapazität und Kernstunden für GitHub-Konten.

Öffnen Sie ein Terminal im Stammverzeichnis des Projekts.
Authentifizieren Sie sich mithilfe von azd auth login bei Azure Developer CLI. Führen Sie die vom Tool angegebenen Schritte aus, um sich mit Ihren bevorzugten Azure-Anmeldeinformationen bei der CLI zu authentifizieren.
```
azd auth login
```
Verwenden Sie azd init, um das Projekt zu initialisieren.
```
azd init
```
Konfigurieren Sie während der Initialisierung einen eindeutigen Umgebungsnamen.

Tipp

Der Umgebungsname wird auch als Name der Zielressourcengruppe verwendet. Ziehen Sie für diese Schnellstartanleitung die Verwendung von msdocs-cosmos-db- in Betracht.
Stellen Sie das Azure Cosmos DB-Konto mit azd up bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.
```
azd up
```
Wählen Sie während des Bereitstellungsprozesses Ihr Abonnement und den gewünschten Standort aus. Warten Sie auf den Abschluss des Bereitstellungsvorgangs. Dieser Prozess kann ca. fünf Minuten dauern.

Sobald die Bereitstellung Ihrer Azure-Ressourcen abgeschlossen ist, enthält die Ausgabe eine URL zur ausgeführten Webanwendung.

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.

Verwenden Sie die URL in der Konsole, um im Browser zu Ihrer Webanwendung zu navigieren. Sehen Sie sich die Ausgabe der ausgeführten App an.

Installieren der Clientbibliothek

Die Clientbibliothek ist über NuGet als Microsoft.Azure.Cosmos-Paket verfügbar.

Öffnen Sie ein Terminal, und navigieren Sie zu dem /src/web-Ordner.
```
cd ./src/web
```
Installieren Sie das MongoDb.Driver-Paket mithilfe von dotnet add package, falls es noch nicht installiert ist.
```
dotnet add package MongoDb.Driver
```
Installieren Sie außerdem das Azure.Identity-Paket (sofern noch nicht installiert).
```
dotnet add package Azure.Identity
```

Objektmodell

Bevor Sie mit dem Erstellen der Anwendung beginnen, sehen Sie sich die Hierarchie von Ressourcen in Azure Cosmos DB an. Bei Azure Cosmos DB gibt es ein spezifisches Objektmodell, das zum Erstellen von und Zugreifen auf Ressourcen verwendet wird. Azure Cosmos DB erstellt Ressourcen in einer Hierarchie, die aus Konten, Datenbanken, Sammlungen und Dokumenten besteht.

Diagram der Azure Cosmos DB-Hierarchie, einschließlich Konten, Datenbanken, Auflistungen und Dokumentation.

Sie werden die folgenden MongoDB-Klassen für die Interaktion mit diesen Ressourcen verwenden:

MongoClient: Diese Klasse bietet eine clientseitige logische Darstellung für die „API für MongoDB“-Ebene in Azure Cosmos DB. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet.
MongoDatabase – Diese Klasse ist ein Verweis auf eine Datenbank, die im Dienst möglicherweise vorhanden oder noch nicht vorhanden ist. Die Datenbank wird vom Server aus überprüft, wenn Sie versuchen, darauf zuzugreifen oder einen Vorgang auszuführen.
Collection – Diese Klasse ist ein Verweis auf eine Sammlung, die im Dienst ebenfalls möglicherweise noch nicht vorhanden ist. Die Sammlung wird vom Server aus überprüft, wenn Sie versuchen, damit zu arbeiten.

Der in diesem Artikel enthaltene Beispielcode erstellt eine Datenbank namens adventureworks mit der Sammlung products. Die Sammlung products soll Produktdetails wie Name (name), Kategorie (category), Menge (quantity) und einen Verkaufsindikator (sale) enthalten. Jedes Produkt enthält außerdem einen eindeutigen Bezeichner.

Authentifizieren des Clients

Öffnen Sie die Program.cs-Datei aus dem Projektverzeichnis heraus. Fügen Sie in Ihrem Editor eine Verwendungsanweisung für MongoDB.Driver hinzu.

using MongoDB.Driver;

Definieren Sie eine neue Instanz der MongoClient-Klasse mit dem Konstruktor und Environment.GetEnvironmentVariable für das Lesen der Verbindungszeichenfolge, die Sie zuvor festgelegt haben.

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

Erstellen einer Datenbank

Verwenden Sie die Methode MongoClient.GetDatabase zum Erstellen einer neuen Datenbank, wenn noch keine vorhanden ist. Diese Methode gibt einen Verweis auf die bereits vorhandene oder neu erstellte Datenbank zurück.

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

Erstellen einer Sammlung

MongoDatabase.GetCollection erstellt eine neue Sammlung, falls noch nicht vorhanden, und gibt einen Verweis auf die Sammlung zurück.

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

Erstellen eines Elements

Die einfachste Möglichkeit zum Erstellen eines neuen Elements in einer Sammlung ist, eine C#-Klasse oder einen Datensatztyp mit allen Elementen zu erstellen, die Sie in JSON serialisieren möchten. In diesem Beispiel verfügt der C#-Datensatz über einen eindeutigen Bezeichner, ein Kategoriefeld für den Partitionsschlüssel und einen zusätzlichen Namen sowie Felder für Mengen und Verkauf.

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

Erstellen Sie ein Element in der Sammlung mithilfe des Product-Datensatzes, indem Sie IMongoCollection<TDocument>.InsertOne aufrufen.

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

Abrufen eines Elements

In Azure Cosmos DB können Sie Elemente abrufen, indem Sie Abfragen mithilfe von Linq verfassen. Rufen Sie im SDK IMongoCollection.FindAsync<> auf, und übergeben Sie einen C#-Ausdruck, um die Ergebnisse zu filtern.

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

Abfrageelemente

Nachdem Sie ein Element eingefügt haben, können Sie eine Abfrage durchführen, um alle Elemente zu erhalten, die einem bestimmten Filter entsprechen, indem Sie die Sammlung als IQueryable behandeln. In diesem Beispiel wird ein Ausdruck verwendet, um Produkte nach Kategorie zu filtern. Sobald der Aufruf von AsQueryable erfolgt ist, rufen Sie MongoQueryable.Where auf, um einen Satz gefilterter Elemente abzurufen.

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

Ausführen des Codes

Diese App erstellt eine Azure Cosmos DB for MongoDB-API-Datenbank und -Sammlung. Anschließend erstellt das Beispiel ein Element und liest dann dasselbe Element wieder ein. Schließlich erstellt das Beispiel ein zweites Element und führt dann eine Abfrage aus, die mehrere Elemente zurückgeben soll. In jedem Schritt gibt das Beispiel über die ausgeführten Schritte Metadaten in die Konsole aus.

Verwenden Sie zur Ausführung der App ein Terminal, um zum Anwendungsverzeichnis zu navigieren und die Anwendung auszuführen.

dotnet run

Die Ausgabe der App sollte ähnlich wie dieses Beispiel aussehen:

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

Bereinigen von Ressourcen

Wenn Sie das Azure Cosmos DB for MongoDB-Konto nicht mehr benötigen, können Sie die entsprechende Ressourcengruppe löschen.

Verwenden Sie den Befehl az group delete zum Löschen der Ressourcengruppe.

az group delete --name $resourceGroupName

Verwenden Sie das Cmdlet Remove-AzResourceGroup zum Löschen der Ressourcengruppe.

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