Schnellstart: Azure Cosmos DB for NoSQL-Clientbibliothek für .NET

GILT FÜR: NoSQL

Erste Schritte mit der Azure Cosmos DB-Clientbibliothek für .NET, um Datenbanken, Container und Elemente in Ihrem Konto zu erstellen. 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.

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | Beispiele

Voraussetzungen

Prüfen der Voraussetzungen

  • Führen Sie in einem Terminal- oder Befehlsfenster den Befehl dotnet --version aus, um sich zu vergewissern, dass das .NET SDK die Version 6.0 oder höher 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

Dieser Abschnitt führt Sie durch das Erstellen eines Azure Cosmos DB-Kontos und durch das Einrichten eines Projekts, das die Azure Cosmos DB for NoSQL-Clientbibliothek für .NET zum Verwalten von Ressourcen verwendet.

Erstellen eines Azure Cosmos DB-Kontos

Tipp

Kein Azure-Abonnement? Sie können Azure Cosmos DB kostenlos testen, ohne dass eine Kreditkarte erforderlich ist. Wenn Sie mithilfe der kostenlosen Testversion ein Konto erstellen, können Sie mit dem Abschnitt Erstellen einer neuen .NET-App fortfahren.

In dieser Schnellstartanleitung wird ein einzelnes Azure Cosmos DB-Konto mithilfe der API für NoSQL erstellt.

Tipp

Für diesen Schnellstart empfehlen wir die Verwendung des Ressourcengruppennamens msdocs-cosmos-quickstart-rg.

  1. Melden Sie sich beim Azure-Portal an.

  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 Cosmos DB, und wählen Sie die Option aus.

  4. Wählen Sie auf der Seite API-Option auswählen im Abschnitt NoSQL die Option Erstellen aus. Azure Cosmos DB verfügt über sechs APIs: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin und Table. Weitere Informationen zur API für NoSQL.

    Screenshot: ausgewählte API-Optionen-Seite für Azure Cosmos DB.

  5. Geben Sie auf der Seite Azure Cosmos DB-Konto erstellen die folgenden Informationen ein:

    Einstellung Wert BESCHREIBUNG
    Subscription Abonnementname Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos-Konto verwenden möchten.
    Ressourcengruppe Ressourcengruppenname Wählen Sie eine Ressourcengruppe aus, oder wählen Sie Neu erstellen aus, und geben Sie einen eindeutigen Namen für die Ressourcengruppe ein.
    Kontoname Ein eindeutiger Name Geben Sie einen Namen ein, der Ihr Azure Cosmos-Konto identifiziert. Weil der Name als Teil eines vollqualifizierten Domänennamens (FQDN) mit dem Suffix documents.azure.com verwendet wird, muss er global eindeutig sein. Der Name darf nur Kleinbuchstaben, Zahlen und den Bindestrich (-) enthalten. Außerdem muss der Name zwischen 3 und 44 Zeichen lang sein.
    Standort Die Region, die Ihren Benutzern am nächsten liegt Wählen Sie einen geografischen Standort aus, an dem Ihr Azure Cosmos DB-Konto gehostet werden soll. Verwenden Sie den Standort, der Ihren Benutzern am nächsten ist, damit sie möglichst schnell auf die Daten zugreifen können.
    Kapazitätsmodus Bereitgestellter Durchsatz oder serverlos Wählen Sie Bereitgestellter Durchsatz aus, um ein Konto im Modus Bereitgestellter Durchsatz zu erstellen. Wählen Sie Serverlos aus, um ein Konto im Modus Serverlos zu erstellen.
    Anwenden des Rabatts für den Free-Tarif von Azure Cosmos DB Anwenden oder Nicht anwenden Aktivieren Sie den Free-Tarif von Azure Cosmos DB. Mit dem Azure Cosmos DB-Tarif „Free“ erhalten Sie die ersten 1000 RUs/Sek. sowie 25 GB Speicher kostenlos in einem Konto. Weitere Informationen zum Tarif „Free“

    Hinweis

    Sie können pro Azure-Abonnement maximal ein Azure Cosmos DB-Konto im Free-Tarif einrichten und müssen sich beim Erstellen des Kontos anmelden. Wird die Option zum Anwenden des tarifspezifischen Rabatts für den Free-Tarif nicht angezeigt, bedeutet dies, dass bereits ein anderes Konto im Abonnement mit dem Free-Tarif aktiviert wurde.

    Screenshot: Neue Kontoseite für API für NoSQL

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

  7. Überprüfen Sie die von Ihnen angegebenen Einstellungen, und wählen Sie dann Erstellen aus. Die Erstellung des Kontos dauert einige Minuten. Warten Sie, bis auf der Portalseite Ihre Bereitstellung ist abgeschlossen angezeigt wird, bevor sie den Vorgang fortsetzen.

  8. Wählen Sie Zu Ressource wechseln aus, um zur Seite des Azure Cosmos DB-Kontos zu wechseln.

    Screenshot: Bereitstellungsseite für API für NoSQL-Ressource

  9. Wählen Sie auf der API für NoSQL-Kontoseite im Navigationsmenü die Option Schlüssel aus.

    Screenshot: API für NoSQL-Kontoseite mit hervorgehobener Option „Schlüssel“ im Navigationsmenü

  10. Zeichnen Sie die Werte aus den Feldern von URI - und PRIMÄRSCLÜSSEL auf. Diese Werte benötigen Sie in einem späteren Schritt.

    Screenshot: Seite „Schlüssel“ mit diversen Anmeldeinformationen für ein API für NoSQL-Konto

Erstellen einer neuen .NET-App

Erstellen Sie eine neue .NET-Anwendung in einem leeren Ordner mit Ihrem bevorzugten Terminal. Verwenden Sie den Befehl dotnet new, der die Vorlage Console angibt.

dotnet new console

Installieren des Pakets

Fügen Sie dem .NET-Projekt das NuGet-Paket von microsoft.Azure.Cosmos hinzu. Verwenden Sie den dotnet add package-Befehl, der den Namen des NuGet Pakets angibt.

dotnet add package Microsoft.Azure.Cosmos

Erstellen Sie das Projekt mit dem dotnet build-Befehl.

dotnet build

Stellen Sie sicher, dass der Build ohne Fehler erfolgreich war. Die erwartete Ausgabe aus dem Build sollte etwa wie folgt aussehen:

  Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Konfigurieren von Umgebungsvariablen

Um die Werte von URI und PRIMÄRSCHLÜSSEL in Ihrem Code zu verwenden, speichern Sie sie in neuen Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird. Verwenden Sie zum Festlegen der Umgebungsvariablen Ihr bevorzugtes Terminal, um die folgenden Befehle auszuführen:

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

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. Die Azure Cosmos DB erstellt Ressourcen in einer Hierarchie, die aus Konten, Datenbanken, Containern und Elementen besteht.

Diagram der Azure Cosmos DB-Hierarchie, einschließlich Konten, Datenbanken, Containern und Elementen.

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

Weitere Informationen zur Hierarchie der verschiedenen Entitäten finden Sie im Artikel Arbeiten mit Datenbanken, Containern und Elementen in Azure Cosmos DB.

Für die Interaktion mit diesen Ressourcen verwenden Sie die folgenden .NET-Klassen:

  • CosmosClient: Diese Klasse bietet eine clientseitige logische Darstellung für den Azure Cosmos DB-Dienst. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet.
  • Database – 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.
  • Container - Diese Klasse ist ein Verweis auf einen Container, der möglicherweise noch nicht im Dienst vorhanden ist. Der Container wird vom Server aus überprüft, wenn Sie versuchen, damit zu arbeiten.
  • QueryDefinition - Diese Klasse stellt eine SQL-Abfrage und alle Abfrageparameter dar.
  • FeedIterator<> - Diese Klasse stellt einen Iterator dar, der die aktuelle Seite der Ergebnisse nachverfolgen und eine neue Seite mit Ergebnissen erhalten kann.
  • FeedResponse<> - Diese Klasse stellt eine einzelne Seite von Antworten aus dem Iterator dar. Dieser Typ kann über eine foreach-Schleife durchlaufen werden.

Codebeispiele

Der in diesem Artikel beschriebene Beispielcode erstellt eine Datenbank mit dem Namen adventureworks mit einem Container mit dem Namen products. Die products-Tabelle soll Produktdetails wie Name, Kategorie, Menge und Verkaufsindikator enthalten. Jedes Produkt enthält außerdem einen eindeutigen Bezeichner.

Für diesen Beispielcode verwendet der Container die Kategorie als logischer Partitionsschlüssel.

Authentifizieren des Clients

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

using Microsoft.Azure.Cosmos;

Definieren Sie eine neue Instanz der CosmosClient-Klasse mithilfe des Konstruktors und Environment.GetEnvironmentVariable, um die beiden zuvor erstellten Umgebungsvariablen zu lesen.

// New instance of CosmosClient class
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

Weitere Informationen zum Erstellen einer CosmosClient-Instanz finden Sie unter Erste Schritte mit Azure Cosmos DB for NoSQL und .NET.

Erstellen einer Datenbank

Verwenden Sie die Methode CosmosClient.CreateDatabaseIfNotExistsAsync 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
Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks"
);

Console.WriteLine($"New database:\t{database.Id}");

Weitere Informationen zum Erstellen einer Datenbank finden Sie unter Erstellen einer Datenbank in Azure Cosmos DB for NoSQL mithilfe von .NET.

Erstellen eines Containers

Der Database.CreateContainerIfNotExistsAsync erstellt einen neuen Container, wenn er noch nicht vorhanden ist. Diese Methode gibt auch einen Verweis auf den Container zurück.

// Container reference with creation if it does not alredy exist
Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/categoryId",
    throughput: 400
);

Console.WriteLine($"New container:\t{container.Id}");

Weitere Informationen zum Erstellen eines Containers finden Sie unter Erstellen eines Containers in Azure Cosmos DB for NoSQL mithilfe von .NET.

Erstellen eines Elements

Die einfachste Möglichkeit zum Erstellen eines neuen Elements in einem Container besteht darin, zuerst 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 categoryId-Feld für den Partitionsschlüssel und einen zusätzlichen categoryName, name sowie die Felder quantity und sale.

// C# record representing an item in the container
public record Product(
    string id,
    string categoryId,
    string categoryName,
    string name,
    int quantity,
    bool sale
);

Erstellen Sie ein Element im Container, indem Sie Container.CreateItemAsync aufrufen.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    categoryId: "61dba35b-4f02-45c5-b648-c6badc0cbd79",
    categoryName: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.CreateItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.categoryName}]");

Weitere Informationen zu Erstellungs-, Upsert- oder Ersetzungsvorgängen für Elemente finden Sie unter Erstellen eines Elements in Azure Cosmos DB for NoSQL mithilfe von .NET.

Abrufen eines Elements

In Azure Cosmos DB können Sie einen Punktlesevorgang ausführen, indem Sie sowohl die eindeutigen Bezeichner (id) als auch die Partitionsschlüsselfelder verwenden. Rufen Sie im SDK Container.ReadItemAsync<> auf, das beide Werte durchläuft, um eine deserialisierte Instanz Ihres C#-Typs zurückzugeben.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Weitere Informationen zum Lesen von Elementen und Analysieren der Antwort finden Sie unter Lesen eines Elements in Azure Cosmos DB for NoSQL mithilfe von .NET.

Abfrageelemente

Nachdem Sie ein Element eingefügt haben, können Sie eine Abfrage ausführen, um alle Elemente abzurufen, die einem bestimmten Filter entsprechen. In diesem Beispiel wird die SQL-Abfrage ausgeführt: SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79". In diesem Beispiel wird der QueryDefinition-Typ und ein parametrisierter Abfrageausdruck für den Partitionsschlüsselfilter verwendet. Sobald die Abfrage definiert ist, rufen Sie Container.GetItemQueryIterator<> auf, um einen Ergebnis-Iterator abzurufen, der die Seiten der Ergebnisse verwaltet. Verwenden Sie dann eine Kombination aus while- und foreach-Schleifen, um Seiten von Ergebnissen abzurufen und dann über die einzelnen Elemente zu durchlaufen.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.categoryId = @categoryId"
)
    .WithParameter("@categoryId", "61dba35b-4f02-45c5-b648-c6badc0cbd79");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Ausführen des Codes

Diese App erstellt eine API für NoSQL-Datenbank und einen Container. Anschließend erstellt das Beispiel ein Element und liest dann dasselbe Element wieder ein. Schließlich verursacht das Beispiel eine Abfrage, die nur dieses einzelne Element 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:

New database:   adventureworks
New container:  products
Created item:   68719518391     [gear-surf-surfboards]

Bereinigen von Ressourcen

Wenn Sie das API für NoSQL-Konto nicht mehr benötigen, können Sie die entsprechende Ressourcengruppe löschen.

  1. Navigieren Sie zu der Ressourcengruppe, die Sie im Azure-Portal zuvor erstellt haben.

    Tipp

    In diesem Schnellstart haben wir den Namen msdocs-cosmos-quickstart-rg empfohlen.

  2. Wählen Sie die Option Ressourcengruppe löschen.

    Screenshot: Die Option „Ressourcengruppe löschen“ in der Navigationsleiste für eine Ressourcengruppe.

  3. Geben Sie im Dialogfeld Möchten Sie den Löschvorgang durchführen? den Namen der Ressourcengruppe ein, und wählen Sie Löschen aus.

    Screenshot: Die Bestätigungsseite für das Löschen einer Ressourcengruppe.

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie ein Azure Cosmos DB for NoSQL-Konto, eine Datenbank und einen Container mithilfe von .NET SDK erstellen. Sie können nun tiefer in ein Tutorial eintauchen, in dem Sie Ihre Azure Cosmos DB for NoSQL-Ressourcen und -Daten mithilfe einer .NET-Konsolenanwendung verwalten.