Freigeben über

Schnellstart: Verwenden von Azure DocumentDB mit MongoDB-Treiber für C#

In dieser Schnellstartanleitung erstellen Sie eine einfache Azure DocumentDB-Anwendung mit C#. Azure DocumentDB ist ein NoSQL-Datenspeicher, mit dem Anwendungen Dokumente in der Cloud speichern und mit offiziellen MongoDB-Treibern darauf zugreifen können. In diesem Handbuch wird gezeigt, wie Sie Dokumente erstellen und grundlegende Aufgaben in Ihrem Azure DocumentDB-Cluster mit C# ausführen.

API-Referenz | Quellcode | Paket (NuGet)

Voraussetzungen

  • Ein Azure-Abonnement

    • Wenn Sie nicht über ein Azure-Abonnement verfügen, erstellen Sie ein kostenloses Konto
  • .NET 10.0 oder höher

Erstellen eines Azure DocumentDB-Clusters

Zunächst müssen Sie einen Azure DocumentDB-Cluster erstellen, der als Grundlage für das Speichern und Verwalten Ihrer NoSQL-Daten dient.

  1. Melden Sie sich beim Azure-Portal an (https://portal.azure.com).

  2. Wählen Sie im Menü des Azure-Portals oder auf der Startseite die Option Ressource erstellen aus.

  3. Suchen Sie auf der Seite "Neu" nach Azure DocumentDB, und wählen Sie sie aus.

    Screenshot der Suche nach Azure DocumentDB.

  4. Wählen Sie auf der Seite "Azure DocumentDB-Cluster erstellen" und im Abschnitt " Grundlagen " die Option "Konfigurieren" im Abschnitt " Clusterebene " aus.

    Screenshot der Option

  5. Konfigurieren Sie auf der Seite "Skalieren " diese Optionen, und wählen Sie dann " Speichern " aus, um ihre Änderungen auf der Clusterebene beizubehalten.

    Wert
    Cluster-Ebene M30 tier, 2 vCore, 8-GiB RAM
    Speicherplatz pro Shard 128 GiB

    Screenshot der Konfigurationsoptionen für die Berechnung und Speicherung eines neuen Azure DocumentDB-Clusters.

  6. Gehen Sie zurück in den Abschnitt "Grundlagen" und konfigurieren Sie die folgenden Optionen:

    Wert
    Subscription Wählen Sie Ihr Azure-Abonnement aus.
    Ressourcengruppe Erstellen Sie eine neue Ressourcengruppe, oder wählen Sie eine vorhandene Ressourcengruppe aus
    Clustername Geben Sie einen global eindeutigen Namen an.
    Ort Wählen Sie eine unterstützte Azure-Region für Ihre Subscription
    MongoDB-Version Auswählen 8.0
    Administratorbenutzername Erstellen eines Benutzernamens für den Zugriff auf den Cluster als Benutzeradministrator
    Passwort Verwenden eines eindeutigen Kennworts, das dem Benutzernamen zugeordnet ist

    Screenshot mit Clusterparametern.

    Tipp

    Notieren Sie die Werte, die Sie für Benutzername und Kennwort verwenden. Diese Werte werden weiter unten in diesem Leitfaden verwendet. Weitere Informationen zu gültigen Werten finden Sie unter Clusterbeschränkungen.

  7. Klicken Sie auf Weiter: Netzwerk.

  8. Konfigurieren Sie im Abschnitt "Firewallregeln " auf der Registerkarte "Netzwerk " die folgenden Optionen:

    Wert
    Konnektivitätsmethode Public access
    Zulassen des öffentlichen Zugriffs von Azure-Diensten und -Ressourcen in Azure auf diesen Cluster Aktiviert

  9. Fügen Sie eine Firewallregel für Ihr aktuelles Clientgerät hinzu, um Zugriff auf den Cluster zu gewähren, indem Sie +Aktuelle Client-IP-Adresse hinzufügen auswählen.

    Screenshot mit Netzwerkkonfigurationen.

    Tipp

    In vielen Unternehmensumgebungen werden IP-Adressen des Entwicklercomputers aufgrund von VPN-Einstellungen oder anderer Unternehmensnetzwerkeinstellungen ausgeblendet. In diesen Fällen können Sie vorübergehend den Zugriff auf alle IP-Adressen zulassen, indem Sie den 0.0.0.0 - 255.255.255.255 IP-Adressbereich als Firewallregel hinzufügen. Verwenden Sie diese Firewallregel nur vorübergehend als Teil von Verbindungstests und -entwicklung.

  10. Klicken Sie auf Überprüfen + erstellen.

  11. Überprüfen Sie die von Ihnen angegebenen Einstellungen, und wählen Sie dann Erstellen aus. Die Erstellung des Clusters dauert einige Minuten. Warten Sie, bis die Ressourcenbereitstellung abgeschlossen ist.

  12. Wählen Sie schließlich "Zur Ressource wechseln " aus, um im Portal zum Azure DocumentDB-Cluster zu navigieren.

Screenshot mit goto-Ressourcenoptionen.

Abrufen von Clusteranmeldeinformationen

Rufen Sie die Anmeldeinformationen ab, die Sie zum Herstellen einer Verbindung mit dem Cluster verwenden.

  1. Wählen Sie auf der Clusterseite die Option "Verbindungszeichenfolgen" im Ressourcenmenü aus.

  2. Kopieren oder aufzeichnen Sie im Abschnitt "Verbindungszeichenfolgen " den Wert aus dem Feld "Verbindungszeichenfolge ".

Screenshot der Option für Verbindungszeichenfolgen.

Von Bedeutung

Die Verbindungszeichenfolge im Portal enthält nicht den Kennwortwert. Sie müssen den <password> Platzhalter durch die Anmeldeinformationen ersetzen, die Sie beim Erstellen des Clusters eingegeben haben, oder das Kennwort interaktiv eingeben.

Initialisieren des Projekts

Erstellen Sie ein neues .NET-Konsolenanwendungsprojekt in Ihrem aktuellen Verzeichnis.

  1. Beginnen Sie in einem leeren Verzeichnis.

  2. Öffnen Sie ein Terminal im aktuellen Verzeichnis.

  3. Erstellen Sie eine neue .NET-Konsolenanwendung.

    dotnet new console

  4. Erstellen Sie das Projekt, um sicherzustellen, dass es erfolgreich erstellt wurde.

    dotnet build

Installieren der Clientbibliothek

Die Clientbibliothek ist über NuGet als MongoDB.Driver-Paket verfügbar.

  1. Installieren Sie den MongoDB .NET-Treiber mit dem NuGet-Paket-Manager.

    dotnet add package MongoDB.Driver

  2. Öffnen Und überprüfen Sie die Datei "azure-documentdb-dotnet-quickstart.csproj ", um zu überprüfen, ob der Paketverweis vorhanden ist.

  3. Importieren Sie die erforderlichen Namespaces in Ihren Anwendungscode:

    using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Driver;

Objektmodell

Name Description
MongoClient Typ, der zum Herstellen einer Verbindung mit MongoDB verwendet wird.
IMongoDatabase Stellt eine Datenbank im Cluster dar.
IMongoCollection<T> Stellt eine Auflistung innerhalb einer Datenbank im Cluster dar.

Code-Beispiele

Der Code in dieser Anwendung stellt eine Verbindung zu einer Datenbank namens adventureworks und einer Sammlung namens products her. Die products Sammlung enthält Details wie Name, Kategorie, Menge, eindeutigen Bezeichner und ein Verkaufskennzeichen für jedes Produkt. In den Codebeispielen werden hier die am häufigsten verwendeten Vorgänge beim Arbeiten mit einer Auflistung ausgeführt.

Authentifizieren des Clients

Stellen Sie zunächst mithilfe einer einfachen Verbindungszeichenfolge eine Verbindung mit dem Client her.

  1. Erstellen Sie die Hauptmethode, und richten Sie die Verbindungszeichenfolge ein. Ersetzen Sie <your-cluster-name>, <your-username> und <your-password> durch Ihre tatsächlichen Clusterinformationen.

    class Program
{
    static async Task Main(string[] args)
    {
        // Connection string for Azure DocumentDB cluster
        string connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

        // Create MongoDB client settings
        var settings = MongoClientSettings.FromConnectionString(connectionString);

  2. Erstellen Sie den MongoDB-Client, und überprüfen Sie die Verbindung.

            // Create a new client and connect to the server
        var client = new MongoClient(settings);

        // Ping the server to verify connection
        var database = client.GetDatabase("admin");
        var pingCommand = new BsonDocument("ping", 1);
        await database.RunCommandAsync<BsonDocument>(pingCommand);

        Console.WriteLine("Successfully connected and pinged Azure DocumentDB");

Sammlung abrufen

Rufen Sie nun Ihre Datenbank und Sammlung ab. Wenn die Datenbank und Sammlung noch nicht vorhanden ist, verwenden Sie den Treiber, um sie automatisch zu erstellen.

  1. Holen Sie sich eine Referenz auf die Datenbank.

            // Get database reference
        var adventureWorksDatabase = client.GetDatabase("adventureworks");
        Console.WriteLine($"Connected to database: {adventureWorksDatabase.DatabaseNamespace.DatabaseName}");

  2. Rufen Sie einen Verweis auf die Sammlung in der Datenbank ab.

            // Get collection reference
        var productsCollection = adventureWorksDatabase.GetCollection<Product>("products");
        Console.WriteLine($"Connected to collection: products");

Erstellen eines Dokuments

Erstellen Sie dann ein paar neue Dokumente in Ihrer Sammlung. Führen Sie eine Upsert für die Dokumente aus, um sicherzustellen, dass vorhandene Dokumente ersetzt werden, wenn sie bereits mit demselben eindeutigen Bezeichner vorhanden sind.

  1. Definieren Sie eine Produktklasse, und erstellen Sie Beispielproduktdokumente.

            // Create sample products
        var products = new List<Product>
        {
            new Product
            {
                Id = "00000000-0000-0000-0000-000000004018",
                Name = "Windry Mittens",
                Category = "apparel-accessories-gloves-and-mittens",
                Quantity = 121,
                Price = 35.00m,
                Sale = false
            },
            new Product
            {
                Id = "00000000-0000-0000-0000-000000004318",
                Name = "Niborio Tent",
                Category = "gear-camp-tents",
                Quantity = 140,
                Price = 420.00m,
                Sale = true
            }
        };

  2. Fügen Sie die Dokumente mithilfe von Upsert-Vorgängen ein.

            // Insert documents with upsert
        foreach (var product in products)
        {
            var filter = Builders<Product>.Filter.Eq(p => p.Id, product.Id);
            var options = new ReplaceOptions { IsUpsert = true };

            await productsCollection.ReplaceOneAsync(filter, product, options);
            Console.WriteLine($"Upserted product: {product.Name}");
        }

  3. Fügen Sie die Produktklassendefinition am Ende der Program.cs Datei hinzu.

    public class Product
{
    [BsonId]
    [BsonElement("_id")]
    public string Id { get; set; }

    [BsonElement("name")]
    public string Name { get; set; }

    [BsonElement("category")]
    public string Category { get; set; }

    [BsonElement("quantity")]
    public int Quantity { get; set; }

    [BsonElement("price")]
    public decimal Price { get; set; }

    [BsonElement("sale")]
    public bool Sale { get; set; }
}

Abrufen eines Dokuments

Führen Sie als Nächstes einen Punktlesevorgang aus, um ein bestimmtes Dokument aus Ihrer Sammlung abzurufen.

  1. Definieren Sie den Filter, um ein bestimmtes Dokument anhand der ID zu finden.

            // Retrieve a specific document by ID
        var filter = Builders<Product>.Filter.Eq(p => p.Id, "00000000-0000-0000-0000-000000004018");

  2. Führen Sie die Abfrage aus, und rufen Sie das Ergebnis ab.

            var retrievedProduct = await productsCollection.Find(filter).FirstOrDefaultAsync();

        if (retrievedProduct != null)
        {
            Console.WriteLine($"Retrieved product: {retrievedProduct.Name} - ${retrievedProduct.Price}");
        }
        else
        {
            Console.WriteLine("Product not found");
        }

Abfragedokumente

Fragen Sie schließlich mehrere Dokumente mithilfe der MongoDB Query Language (MQL) ab.

  1. Definieren Sie eine Abfrage, um Dokumente zu finden, die bestimmten Kriterien entsprechen.

            // Query for products on sale
        var saleFilter = Builders<Product>.Filter.Eq(p => p.Sale, true);
        var saleProducts = await productsCollection.Find(saleFilter).ToListAsync();

  2. Durchlaufen Sie die Ergebnisse, um die übereinstimmenden Dokumente anzuzeigen.

            Console.WriteLine("Products on sale:");
        foreach (var product in saleProducts)
        {
            Console.WriteLine($"- {product.Name}: ${product.Price:F2} (Category: {product.Category})");
        }
    }
}

Erkunden Ihrer Daten mithilfe von Visual Studio Code

Verwenden Sie die DocumentDB-Erweiterung in Visual Studio Code, um kerne Datenbankvorgänge auszuführen, einschließlich Abfragen, Einfügen, Aktualisieren und Löschen von Daten.

  1. Öffnen Sie Visual Studio Code.

  2. Navigieren Sie zur Ansicht "Erweiterungen ", und suchen Sie nach dem Ausdruck DocumentDB. Suchen Sie die DocumentDB-Erweiterung für VS Code .

  3. Wählen Sie die Schaltfläche " Installieren " für die Erweiterung aus. Warten Sie, bis die Installation abgeschlossen ist. Laden Sie Visual Studio Code neu, wenn Sie dazu aufgefordert werden.

  4. Navigieren Sie zur DocumentDB-Erweiterung , indem Sie das entsprechende Symbol in der Aktivitätsleiste auswählen.

  5. Wählen Sie im Bereich "DocumentDB-Verbindungen " +Neue Verbindung... aus.

  6. Wählen Sie im Dialogfeld "Dienstermittlung " und dann "Azure DocumentDB – Azure Service Discovery" aus.

  7. Wählen Sie Ihr Azure-Abonnement und Ihren neu erstellten Azure DocumentDB-Cluster aus.

    Tipp

    In vielen Unternehmensumgebungen werden IP-Adressen des Entwicklercomputers aufgrund von VPN-Einstellungen oder anderer Unternehmensnetzwerkeinstellungen ausgeblendet. In diesen Fällen können Sie vorübergehend den Zugriff auf alle IP-Adressen zulassen, indem Sie den 0.0.0.0 - 255.255.255.255 IP-Adressbereich als Firewallregel hinzufügen. Verwenden Sie diese Firewallregel nur vorübergehend als Teil von Verbindungstests und -entwicklung. Weitere Informationen finden Sie unter "Konfigurieren der Firewall".

  8. Erweitern Sie im Bereich DocumentDB-Verbindungen den Knoten für Ihren Cluster, und navigieren Sie zu Ihren vorhandenen Dokument- und Sammlungsknoten.

  9. Öffnen Sie das Kontextmenü für die Auflistung, und wählen Sie dann "DocumentDB Scrapbook New DocumentDB Scrapbook > " aus.

  10. Geben Sie die folgenden MongoDB Query Language (MQL)-Befehle ein, und wählen Sie dann "Alle ausführen" aus. Beobachten Sie die Ergebnisse der Befehle.

    db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)

Bereinigen von Ressourcen

Wenn Sie mit dem Azure DocumentDB-Cluster fertig sind, können Sie die azure-Ressourcen löschen, die Sie erstellt haben, damit keine weiteren Gebühren anfallen.

  1. Suchen Sie über die Suchleiste des Azure-Portals nach Ressourcengruppen, und wählen Sie die entsprechende Option aus.

    Screenshot der Option zum Durchsuchen von Ressourcengruppen.

  2. Wählen Sie in der Liste die Ressourcengruppe aus, die Sie für diesen Schnellstart verwendet haben.

    Screenshot: Ressourcengruppe.

  3. Wählen Sie auf der Ressourcengruppenseite die Option Ressourcengruppe löschen aus.

  4. Geben Sie im Dialogfeld zum Bestätigen des Löschvorgangs den Namen der Ressourcengruppe ein, um zu bestätigen, dass Sie sie löschen möchten. Wählen Sie abschließend Löschen aus, um die Ressourcengruppe endgültig zu löschen.

    Screenshot mit der Bestätigungsschaltfläche

Verwandte Inhalte

  • Last updated on