Erkunden von Microsoft .NET SDK v3 für Azure Cosmos DB

  • 3 Minuten

Diese Lerneinheit konzentriert sich auf das Azure Cosmos DB .NET SDK v3 für API für NoSQL. (NuGet-Paket Microsoft.Azure.Cosmos) Falls Sie mit der vorherigen Version des .NET SDK vertraut sind, kennen Sie unter Umständen bereits die Begriffe „Sammlung“ und „Dokument“.

Das GitHub-Repository azure-cosmos-dotnet-v3 enthält die neuesten .NET-Beispiellösungen. Mithilfe dieser Lösungen führen Sie CRUD-Vorgänge (Create, Read, Update, Delete – Erstellen, Lesen, Aktualisieren, Löschen) und andere allgemeine Vorgänge für Azure Cosmos DB-Ressourcen aus.

Da Azure Cosmos DB mehrere API-Modelle unterstützt, verwendet Version 3 des .NET SDK die generischen Begriffe Container und Element. Ein Container kann eine Sammlung, ein Graph oder eine Tabelle sein. Ein Element kann ein Dokument, eine Kante/Vertex oder eine Zeile sein und ist der Inhalt eines Containers.

Im Folgenden finden Sie Beispiele für einige der wichtigsten Vorgänge, mit denen Sie vertraut sein sollten. Weitere Beispiele finden Sie unter dem zuvor erwähnten GitHub-Link. In den folgenden Beispielen wird die asynchrone Version der Methoden verwendet.

CosmosClient

Hiermit wird ein neuer CosmosClient mit einer Verbindungszeichenfolge erstellt. Der CosmosClient ist threadsicher. Es wird empfohlen, während der gesamten Lebensdauer der Anwendung dieselbe CosmosClient-Instanz zu nutzen, was eine effiziente Verbindungsverwaltung und -leistung ermöglicht.

CosmosClient client = new CosmosClient(endpoint, key);

Datenbankbeispiele

Erstellen einer Datenbank

Die CosmosClient.CreateDatabaseAsync-Methode wirft eine Ausnahme aus, wenn eine Datenbank mit demselben Namen bereits vorhanden ist.

// New instance of Database class referencing the server-side database
Database database1 = await client.CreateDatabaseAsync(
    id: "adventureworks-1"
);

Mit CosmosClient.CreateDatabaseIfNotExistsAsync wird überprüft, ob eine Datenbank vorhanden ist. Falls dies nicht der Fall ist, wird eine Datenbank erstellt. Nur die Datenbank id wird verwendet, um zu überprüfen, ob eine Datenbank vorhanden ist.

// New instance of Database class referencing the server-side database
Database database2 = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks-2"
);

Lesen einer Datenbank nach ID

Hiermit wird eine Datenbank als asynchroner Vorgang aus Azure Cosmos DB-Dienst gelesen.

DatabaseResponse readResponse = await database.ReadAsync();

Löschen einer Datenbank

Sie können eine Datenbank als asynchronen Vorgang löschen.

await database.DeleteAsync();

Containerbeispiele

Erstellen eines Containers

Die Methode Database.CreateContainerIfNotExistsAsync überprüft, ob ein Container vorhanden ist. Falls dies nicht der Fall ist, wird ein Container erstellt. Es wird nur der id-Container verwendet, um zu überprüfen, ob ein Container vorhanden ist.

// Set throughput to the minimum value of 400 RU/s
ContainerResponse simpleContainer = await database.CreateContainerIfNotExistsAsync(
    id: containerId,
    partitionKeyPath: partitionKey,
    throughput: 400);

Abrufen eines Containers nach ID

Container container = database.GetContainer(containerId);
ContainerProperties containerProperties = await container.ReadContainerAsync();

Löschen eines Containers

Sie können einen Container als asynchronen Vorgang löschen.

await database.GetContainer(containerId).DeleteContainerAsync();

Elementbeispiele

Erstellen eines Elements

Verwenden Sie die Methode Container.CreateItemAsync zum Erstellen eines Elements. Die Methode erfordert ein serialisierbares JSON-Objekt, das eine id-Eigenschaft und einen partitionKey enthalten muss.

ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder, new PartitionKey(salesOrder.AccountNumber));

Lesen eines Elements

Verwenden Sie die Container.ReadItemAsync-Methode zum Lesen eines Elements. Die Methode erfordert einen Typ zum Serialisieren des Elements zusammen mit einer id-Eigenschaft und einem partitionKey.

string id = "[id]";
string accountNumber = "[partition-key]";
ItemResponse<SalesOrder> response = await container.ReadItemAsync(id, new PartitionKey(accountNumber));

Abfragen eines Elements

Die Methode Container.GetItemQueryIterator erstellt eine Abfrage für Elemente unter einem Container in einer Azure Cosmos-Datenbank mithilfe einer SQL-Anweisung mit parametrisierten Werten. Zurückgegeben wird ein FeedIterator.

QueryDefinition query = new QueryDefinition(
    "select * from sales s where s.AccountNumber = @AccountInput ")
    .WithParameter("@AccountInput", "Account1");

FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
    query,
    requestOptions: new QueryRequestOptions()
    {
        PartitionKey = new PartitionKey("Account1"),
        MaxItemCount = 1
    });

Weitere Ressourcen