Erste Schritte mit Azure Cosmos DB for NoSQL unter Verwendung von .NET
GILT FÜR: 
NoSQL
In diesem Artikel erfahren Sie, wie Sie mithilfe des .NET SDK eine Verbindung mit Azure Cosmos DB for NoSQL herstellen. Sobald die Verbindung hergestellt ist, können Sie Vorgänge für Datenbanken, Container und Elemente ausführen.
Paket (NuGet) | Beispiele | API-Dokumentation | Bibliothekquellcode | Feedback einreichen
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure Cosmos DB for NoSQL-Konto. Erstellen eines „API für NoSQL“-Kontos.
- .NET 6.0 oder höher
- Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell
Einrichten des Projekts
Erstellen Sie eine neue .NET-Anwendung mithilfe des Befehls mit der dotnet new Vorlage Konsole.
dotnet new console
Importieren Sie das Microsoft.Azure.Cosmos NuGet Paket mithilfe des dotnet add package-Befehls.
dotnet add package Microsoft.Azure.Cosmos
Erstellen Sie das Projekt mit dem dotnet build-Befehl.
dotnet build
Herstellen einer Verbindung mit Azure Cosmos DB for NoSQL
Um eine Verbindung mit der API für NoSQL von Azure Cosmos DB herzustellen, erstellen Sie eine Instanz der CosmosClient-Klasse. Diese Klasse ist der Ausgangspunkt, um alle Vorgänge für Datenbanken auszuführen.
Um eine Verbindung mit Ihrer API für das NoSQL-Konto mithilfe von Microsoft Entra herzustellen, verwenden Sie einen Sicherheitsprinzipal. Der genaue Prinzipaltyp hängt davon ab, wo Sie Ihren Anwendungscode hosten. Die folgende Tabelle dient als Kurzanleitung.
| Ausführungsort der Anwendung | Sicherheitsprinzipal |
|---|---|
| Lokaler Computer (Entwickeln und Testen) | Benutzeridentität oder Dienstprinzipal |
| Azure | Verwaltete Identität |
| Server oder Clients außerhalb von Azure | Dienstprinzipal |
Importieren Sie Azure.Identity
Das Azure.Identity NuGet-Paket enthält grundlegende Authentifizierungsfunktionen, die von allen Azure SDK-Bibliotheken gemeinsam genutzt werden.
Importieren Sie das Azure.Identity-NuGet-Paket mithilfe des dotnet add package-Befehls.
dotnet add package Azure.Identity
Erstellen Sie das Projekt mit dem dotnet build-Befehl neu.
dotnet build
Fügen Sie in Ihrem Code-Editor using-Direktiven für Azure.Core und Azure.Identity Namespaces hinzu.
using Azure.Core;
using Azure.Identity;
Erstellen von CosmosClient mit Standard-Implementierung von Anmeldeinformationen
Wenn Sie auf einem lokalen Computer testen oder Ihre Anwendung auf Azure-Diensten mit direkter Unterstützung für verwaltete Identitäten ausgeführt wird, rufen Sie ein OAuth-Token ab, indem Sie eine DefaultAzureCredential-Instanz erstellen.
In diesem Beispiel haben wir die Instanz in einer Variablen vom Typ TokenCredential gespeichert, da es sich um einen generischeren Typ handelt, der über SDKs wiederverwendbar ist.
// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();
Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit der COSMOS_ENDPOINT-Umgebungsvariable und dem TokenCredential-Objekt als Parameter.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Erstellen Ihrer Anwendung
Beim Erstellen Ihrer Anwendung interagiert Ihr Code hauptsächlich mit vier Arten von Ressourcen:
Das API für NoSQL-Konto, das der eindeutige Namespace der obersten Ebene für Ihre Azure Cosmos DB-Daten ist.
Datenbanken, die Container in Ihrem Konto organisieren.
Container, die eine Reihe einzelner Elemente in Ihrer Datenbank enthalten.
Elemente, die ein JSON-Dokument in Ihrem Container darstellen.
Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.
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.
Jeder Ressourcentyp wird durch eine oder mehrere zugeordnete .NET-Klassen dargestellt. Nachstehend finden Sie eine Liste der gängigsten Hilfsprogramme.
| Klasse | BESCHREIBUNG |
|---|---|
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 möglicherweise noch nicht im Dienst 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 serverseitig validiert, wenn Sie versuchen, damit zu arbeiten. |
In den folgenden Leitfäden wird gezeigt, wie Sie diese verschiedenen Klassen verwenden, um Ihre Anwendung zu erstellen.
| Handbuch | BESCHREIBUNG |
|---|---|
| Erstellen einer Datenbank | Erstellen von Datenbanken |
| Container erstellen | Erstellen von Containern. |
| Lesen eines Elements | Punktlesevorgang eines bestimmten Elements |
| Abfrageelemente | Mehrere Elemente abfragen |