Erste Schritte mit Azure Cosmos DB for NoSQL unter Verwendung von .NET

Artikel
06/01/2023

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 die .NET-Konsolenanwendung

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. Es gibt drei Hauptmethoden zum Herstellen einer Verbindung mit einem API für NoSQL-Konto mit der CosmosClient-Klasse:

Verbinden mit einem API für NoSQL-Endpunkt und Lese-/Schreibschlüssel
Verbinden mit einer API für NoSQL-Verbindungszeichenfolge
Verbinden mit Microsoft Entra ID

Verbinden Sie sich mit einem Endpunkt und Schlüssel

Der gebräuchlichste Konstruktor für CosmosClient hat zwei Parameter:

Parameter	Beispielwert	BESCHREIBUNG
`accountEndpoint`	Umgebungsvariable `COSMOS_ENDPOINT`	API für NoSQL-Endpunkt, der für alle Anforderungen verwendet werden soll
`authKeyOrResourceToken`	Umgebungsvariable `COSMOS_KEY`	Kontoschlüssel oder Ressourcentoken zur Verwendung bei der Authentifizierung

Rufen Sie Ihren Kontoendpunkt und -schlüssel ab

Erstellen Sie eine Shell-Variable für resourceGroupName.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-dotnet-howto-rg"

Verwenden Sie den Befehlaz cosmosdb list, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

Rufen Sie den API für NoSQL-Endpunkt-URI für das Konto mithilfe des az cosmosdb show-Befehls ab.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

Suchen Sie den PRIMÄRSCHLÜSSEL aus der Liste der Schlüssel für das Konto mit dem az-cosmosdb-keys-list-Befehl.

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

Aufzeichnen der Werte von URI und PRIMÄRSCHLÜSSEL. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Erstellen Sie eine Shell-Variable für RESOURCE_GROUP_NAME.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "msdocs-cosmos-dotnet-howto-rg"

Verwenden Sie den BefehlGet-AzCosmosDBAccount-cmdlet, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

# Retrieve most recently created account name
$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
}
$ACCOUNT_NAME = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Name -First 1
).Name

Rufen Sie den API für NoSQL-Endpunkt-URI für das Konto mithilfe des Get-AzCosmosDBAccount-Cmdlets ab.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
}
Get-AzCosmosDBAccount @parameters |
    Select-Object -Property "DocumentEndpoint"

Suchen Sie den PRIMÄRSCHLÜSSEL aus der Liste der Schlüssel für das Konto mit dem Get-AzCosmosDBAccountKey-Cmdlet.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "Keys"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "PrimaryMasterKey"

Aufzeichnen der Werte von URI und PRIMÄRSCHLÜSSEL. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Tipp

Für diese Anleitung empfehlen wir die Verwendung des Ressourcengruppennamens msdocs-cosmos-dotnet-howto-rg.

Melden Sie sich beim Azure-Portal an.
Navigieren Sie zur Seite des vorhandenen Azure Cosmos DB for NoSQL-Kontos.
Wählen Sie auf der Seite für das Azure Cosmos DB for NoSQL-Konto im Navigationsmenü die Option Schlüssel aus.
Zeichnen Sie die Werte aus den Feldern von URI - und PRIMÄRSCLÜSSEL auf. Diese Werte benötigen Sie in einem späteren Schritt.

Um die Werte von URI und dem PRIMÄRSCHLÜSSEL in Ihrem .NET-Code zu verwenden, speichern Sie auf neuen Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

Windows
Linux/macOS

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

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

Erstellen Sie CosmosClient mit Kontoendpunkt und Schlüssel

Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit den Variablen und COSMOS_ENDPOINTCOSMOS_KEY Umgebungsvariablen als Parameter.

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

Verbinden mit einer Verbindungszeichenfolge

Ein weiterer Konstruktor für CosmosClient enthält nur einen einzelnen Parameter:

Parameter	Beispielwert	BESCHREIBUNG
`accountEndpoint`	Umgebungsvariable `COSMOS_ENDPOINT`	API für NoSQL-Endpunkt, der für alle Anforderungen verwendet werden soll
`connectionString`	Umgebungsvariable `COSMOS_CONNECTION_STRING`	Verbindungszeichenfolge für das API für NoSQL-Konto

Rufen Sie Ihre Kontoverbindungszeichenfolge ab

Verwenden Sie den Befehlaz cosmosdb list, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

Suchen Sie mit dem Befehl az-cosmosdb-keys-list die PRIMÄRE VERBINDUNGSZEICHENFOLGE in der Liste der Verbindungszeichenfolgen für das Konto.

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Verwenden Sie den BefehlGet-AzCosmosDBAccount-cmdlet, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

# Retrieve most recently created account name
$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
}
$ACCOUNT_NAME = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Name -First 1
).Name

Suchen Sie die PRIMÄRE VERBINDUNGSZEICHENFOLGE aus der Liste der Verbindungszeichenfolgen für das Konto mit dem Get-AzCosmosDBAccountKeyCmdlet.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary SQL Connection String" -First 1

Tipp

Für diese Anleitung empfehlen wir die Verwendung des Ressourcengruppennamens msdocs-cosmos-dotnet-howto-rg.

Melden Sie sich beim Azure-Portal an.
Navigieren Sie zur Seite des vorhandenen Azure Cosmos DB for NoSQL-Kontos.
Wählen Sie auf der Seite für das Azure Cosmos DB for NoSQL-Konto im Navigationsmenü die Option Schlüssel aus.
Notieren Sie den Wert aus dem Feld PRIMÄRE VERBINDUNGSZEICHENFOLGE.

Um den PRIMÄREN VERBINDUNGSZEICHENFOLGEN-Wert in Ihrem .NET-Code zu verwenden, halten Sie auf einer neuen Umgebungsvariable auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird, fort.

Windows
Linux/macOS

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

CosmosClient mit Verbindungszeichenfolge erstellen

Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit der COSMOS_CONNECTION_STRINGUmgebungsvariablen als einzigem Parameter.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Anmelden mithilfe von Microsoft Identity Platform

Verwenden Sie einen Sicherheitsprinzipal, um mithilfe von Microsoft Identity Platform und Microsoft Entra ID eine Verbindung mit Ihrem API für NoSQL-Konto herzustellen. 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 von CosmosClient mit Standard-Implementierung von Anmeldeinformationen

Wenn Sie die Anwendung außerhalb von Azure bereitstellen möchten, können Sie ein OAuth-Token abrufen, indem Sie andere Klassen in der Azure.Identity-Clientbibliothek für .NET verwenden. Auch diese anderen Klassen leiten sich von der TokenCredential-Klasse ab.

Für dieses Beispiel erstellen wir eine ClientSecretCredential-Instanz, indem wir Client- und Mandanten-IDs zusammen mit einem geheimen Clientschlüssel verwenden.

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

Sie können die Client-ID, die Mandanten-ID und den geheimen Clientschlüssel abrufen, wenn Sie eine Anwendung in Microsoft Entra ID registrieren. Weitere Informationen zum Registrieren von Microsoft Entra-Anwendungen finden Sie unter Registrieren einer Anwendung bei der Microsoft Identity Platform.

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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

Weitere Informationen

Nächste Schritte

Nachdem Sie sich mit einem API für NoSQL-Konto verbunden haben, befolgen Sie zum Erstellen und Verwalten von Datenbanken die nächste Anleitung.

Erstellen einer Datenbank in Azure Cosmos DB for NoSQL mithilfe von .NET

Erste Schritte mit Azure Cosmos DB for NoSQL unter Verwendung von .NET

Voraussetzungen

Einrichten des Projekts

Erstellen Sie die .NET-Konsolenanwendung

Herstellen einer Verbindung mit Azure Cosmos DB for NoSQL

Verbinden Sie sich mit einem Endpunkt und Schlüssel

Rufen Sie Ihren Kontoendpunkt und -schlüssel ab

Erstellen Sie CosmosClient mit Kontoendpunkt und Schlüssel

Verbinden mit einer Verbindungszeichenfolge

Rufen Sie Ihre Kontoverbindungszeichenfolge ab

CosmosClient mit Verbindungszeichenfolge erstellen

Anmelden mithilfe von Microsoft Identity Platform

Importieren Sie Azure.Identity

Erstellen von CosmosClient mit Standard-Implementierung von Anmeldeinformationen

Erstellen von CosmosClient mit Standard-Implementierung von Anmeldeinformationen

Erstellen Ihrer Anwendung

Weitere Informationen

Nächste Schritte

Zusätzliche Ressourcen