探索适用于 Azure Cosmos DB 的 Microsoft .NET SDK v3

  • 3 分钟

本单元重点介绍适用于 API for NoSQL 的 Azure Cosmos DB .NET SDK v3。 （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"
);

按 ID 读取数据库

以异步操作的形式从 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);

按 ID 获取容器

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

删除容器

以异步操作的形式删除容器。

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

项示例

创建项

若要创建项，请使用 Container.CreateItemAsync 方法。 该方法需要使用必须包含 id 属性的 JSON 可序列化对象以及 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
    });

其他资源