探索適用於 Azure Cosmos DB 的 Microsoft .NET SDK v3

  • 3 分鐘

本單元聚焦於適用於 NoSQL 的 Azure Cosmos DB .NET SDK v3 for API。 (Microsoft.Azure.Cosmos NuGet 封裝。)如果您熟悉舊版 .NET SDK，則可能已熟悉「集合」和「文件」這兩個字詞。

azure-cosmos-dotnet-v3 GitHub 存放庫包含最新的 .NET 範例解決方案。 您可以使用這些解決方案在 Azure Cosmos DB 資源上執行 CRUD (建立、讀取、更新和刪除)，以及其他常見作業。

因為 Azure Cosmos DB 支援多個 API 模型，.NET SDK 第 3 版使用「容器」和「項目」這兩個通用字詞。 「容器」可以是集合、圖形或資料表。 「項目」可以是文件、邊緣/頂點或資料列，並且是容器內的內容。

以下範例顯示您應該熟悉的一些重要作業。 如需更多範例，請瀏覽先前顯示的 GitHub 連結。 下列範例全都使用非同步版本的方法。

CosmosClient

使用連接字串建立新的 CosmosClient。 CosmosClient 是安全執行緒。 建議在應用程式的每次存留期只保持一個 CosmosClient 執行個體，使得連線管理和效能更有效率。

CosmosClient client = new CosmosClient(endpoint, key);

資料庫範例

建立資料庫

如果已有同名的資料庫存在，則 CosmosClient.CreateDatabaseAsync 方法會擲回例外狀況。

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

CosmosClient.CreateDatabaseIfNotExistsAsync 檢查資料庫是否存在，如果不存在，則會建立資料庫。 只有資料庫 id 用來驗證是否有現有的資料庫。

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

按識別碼讀取資料庫

以非同步作業形式從 Azure Cosmos DB 服務讀取資料庫。

DatabaseResponse readResponse = await database.ReadAsync();

刪除資料庫

以非同步作業形式刪除資料庫。

await database.DeleteAsync();

容器範例

建立容器

Database.CreateContainerIfNotExistsAsync 方法檢查容器是否存在，如果不存在，則會建立容器。 只有容器 id 用來驗證是否有現有的容器。

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

按識別碼取得容器

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

刪除容器

以非同步作業形式刪除容器。

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

項目範例

建立項目

使用 Container.CreateItemAsync 方法來建立項目。 此方法需要 JSON 可序列化物件，而此物件必須包含 id 屬性和 partitionKey。

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

讀取項目

使用 Container.ReadItemAsync 方法來讀取項目。 此方法需要型別連同 id 屬性和 partitionKey 來序列化項目。

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

查詢項目

Container.GetItemQueryIterator 方法使用 SQL 陳述式和參數化值，在 Azure Cosmos 資料庫中為容器下的項目建立查詢。 其會傳回 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
    });

其他資源