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

GILT FÜR: Azure Cosmos DB-API für MongoDB

Erste Schritte mit MongoDB zum Erstellen von Datenbanken, Sammlungen und Dokumenten in Ihrer Cosmos DB-Ressource. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

Hinweis

Die Beispielcodeausschnitte sind auf GitHub als .NET-Projekt verfügbar.

MongoDB-API-Referenzdokumentation | MongoDB-Paket (NuGet)

Voraussetzungen

Prüfen der Voraussetzungen

  • Führen Sie in einem Terminal- oder Befehlsfenster dotnet --list-sdks aus, um sich zu vergewissern, dass .NET 6.x eine der verfügbaren Versionen ist.
  • Führen Sie az --version (Azure CLI) oder Get-Module -ListAvailable AzureRM (Azure PowerShell) aus, um zu überprüfen, ob die geeigneten Azure-Befehlszeilentools installiert wurden.

Einrichten

In diesem Abschnitt werden Sie durch die Schritte zum Erstellen eines Azure Cosmos-Kontos und Einrichten eines Projekts geführt, bei dem die MongoDB-NuGet-Pakete verwendet werden.

Erstellen eines Azure Cosmos DB-Kontos

In diesem Schnellstart wird ein einzelnes Azure Cosmos DB-Konto mithilfe der MongoDB-API erstellt.

  1. Erstellen Sie Shellvariablen für accountName, resourceGroupName und location.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. Wenn Sie das noch nicht getan haben, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an.

  3. Erstellen Sie mit dem Befehl az group create eine neue Ressourcengruppe in Ihrem Abonnement.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. Erstellen Sie mit dem Befehl az cosmosdb create ein neues Azure Cosmos DB-MongoDB-API-Konto mit Standardeinstellungen.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
        --kind MongoDB
    

Abrufen der MongoDB-Verbindungszeichenfolge

  1. Suchen Sie mit dem Befehl az cosmosdb list-connection-strings die MongoDB API-Verbindungszeichenfolge in der Liste der Verbindungszeichenfolgen für das Konto.

    az cosmosdb list-connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. Zeichnen Sie die PRIMARY KEY-Werte (Primärschlüsselwerte) auf. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Erstellen einer neuen .NET-App

Erstellen Sie eine neue .NET-Anwendung in einem leeren Ordner mit Ihrem bevorzugten Terminal. Verwenden Sie dotnet new console, um eine neue Konsolen-App zu erstellen.

dotnet new console -o <app-name>

Installieren des NuGet-Pakets

Fügen Sie das MongoDB.Driver-NuGet-Paket dem neuen .NET-Projekt hinzu. Verwenden Sie den dotnet add package-Befehl, der den Namen des NuGet Pakets angibt.

dotnet add package MongoDb.Driver

Konfigurieren von Umgebungsvariablen

Wenn Sie die Werte von CONNECTION STRING (Verbindungszeichenfolge) in Ihrem Code verwenden möchten, legen diesen Wert auf dem lokalen Computer fest, auf dem die Anwendung ausgeführt wird. Verwenden Sie zum Festlegen der Umgebungsvariablen Ihr bevorzugtes Terminal, um die folgenden Befehle auszuführen:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

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.

Hierarchisches Diagramm mit einem Azure Cosmos DB-Konto oben. Das Konto verfügt über zwei untergeordnete Datenbankknoten. Einer der Datenbankknoten enthält zwei untergeordnete Sammlungsknoten. Der andere Datenbankknoten enthält einen einzelnen untergeordneten Sammlungsknoten. Dieser einzelne Sammlungsknoten verfügt über drei untergeordnete Dokumentknoten.

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 MongoDB-API-Ebene in 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.

Codebeispiele

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 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-SQL-API-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