在 Xamarin.Forms 中使用 Azure Cosmos DB 文档数据库

下载示例

Azure Cosmos DB 文档数据库是 NoSQL 数据库，它提供对 JSON 文档的低延迟访问，为需要无缝缩放和全局复制的应用程序提供快速、高度可用的可缩放数据库服务。 本文介绍如何使用 Azure Cosmos DB .NET Standard 客户端库将 Azure Cosmos DB 文档数据库集成到 Xamarin.Forms 应用程序中。

Microsoft Azure Cosmos DB 视频

可以使用 Azure 订阅来预配 Azure Cosmos DB 文档数据库帐户。 每个数据库帐户可以有零个或零个以上的数据库。 Azure Cosmos DB 中的文档数据库是文档集合和用户的逻辑容器。

Azure Cosmos DB 文档数据库可能包含零个或零个以上的文档集合。 每个文档集合可以有不同的性能级别，这样就可以为频繁访问的集合指定较高的吞吐量，为不经常访问的集合指定较低的吞吐量。

每个文档集合由零个或零个以上的 JSON 文档组成。 集合中的文档是无架构的，因此不需要共享相同的结构或字段。 当文档添加到文档集合时，Azure Cosmos DB 会自动为它们编制索引，使它们可供查询。

出于开发目的，还可以通过模拟器使用文档数据库。 使用模拟器，可以在本地开发和测试应用程序，无需创建 Azure 订阅，也不会产生任何费用。 有关模拟器的详细信息，请参阅使用 Azure Cosmos DB 模拟器进行本地开发。

本文以及随附的示例应用程序演示了一个待办事项列表应用程序，其中的任务存储在 Azure Cosmos DB 文档数据库中。 有关示例应用程序的详细信息，请参阅了解示例。

有关 Azure Cosmos DB 的详细信息，请参阅 Azure Cosmos DB 文档。

注意

如果还没有 Azure 订阅，可以在开始前创建一个免费帐户。

安装

将 Azure Cosmos DB 文档数据库集成到 Xamarin.Forms 应用程序的过程如下：

1. 创建 Azure Cosmos DB 帐户。 有关详细信息，请参阅创建 Azure Cosmos DB 帐户。
2. 将 Azure Cosmos DB .NET Standard 客户端库 NuGet 包添加到 Xamarin.Forms 解决方案的平台项目中。
3. 将 Microsoft.Azure.Documents、Microsoft.Azure.Documents.Client 和 Microsoft.Azure.Documents.Linq 命名空间的 using 指令添加到将访问 Azure Cosmos DB 帐户的类。

执行这些步骤后，可将 Azure Cosmos DB .NET Standard 客户端库用于配置和执行针对文档数据库的请求。

注意

Azure Cosmos DB .NET Standard 客户端库只能安装到平台项目中，而不能安装到可移植类库 (PCL) 项目中。 因此，示例应用程序是一个共享访问项目 (SAP)，目的是避免代码重复。 不过，用户可以在 PCL 项目中使用 DependencyService 类来调用特定于平台的项目中包含的 Azure Cosmos DB .NET Standard 客户端库代码。

使用 Azure Cosmos DB 帐户

DocumentClient 类型会封装用于访问 Azure Cosmos DB 帐户的终结点、凭据和连接策略，用于配置和执行针对该帐户的请求。 以下代码示例演示了如何创建此类的实例：

DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);

必须向 DocumentClient 构造函数提供 Azure Cosmos DB URI 和主键。 它们可以从 Azure 门户获取。 有关详细信息，请参阅连接到 Azure Cosmos DB 帐户。

创建数据库

文档数据库是文档集合和用户的逻辑容器，可以在 Azure 门户中创建，也可以使用 DocumentClient.CreateDatabaseIfNotExistsAsync 方法以编程方式创建：

public async Task CreateDatabase(string databaseName)
{
  ...
  await client.CreateDatabaseIfNotExistsAsync(new Database
  {
    Id = databaseName
  });
  ...
}

CreateDatabaseIfNotExistsAsync 方法指定 Database 对象作为参数，而 Database 对象指定数据库名称作为其 Id 属性。 如果数据库不存在，则 CreateDatabaseIfNotExistsAsync 方法会创建该数据库；如果数据库已存在，则会返回该数据库。 但是，示例应用程序会忽略 CreateDatabaseIfNotExistsAsync 方法返回的任何数据。

注意

CreateDatabaseIfNotExistsAsync 方法返回一个 Task<ResourceResponse<Database>> 对象。可以检查响应的状态代码以确定是创建了数据库还是返回了现有数据库。

创建文档集合

文档集合是 JSON 文档的容器，可以在 Azure 门户中创建，也可以使用 DocumentClient.CreateDocumentCollectionIfNotExistsAsync 方法以编程方式创建：

public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
  ...
  // Create collection with 400 RU/s
  await client.CreateDocumentCollectionIfNotExistsAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    new DocumentCollection
    {
      Id = collectionName
    },
    new RequestOptions
    {
      OfferThroughput = 400
    });
  ...
}

CreateDocumentCollectionIfNotExistsAsync 方法需要两个强制参数 - 指定为 Uri 的数据库名称和 DocumentCollection 对象。 DocumentCollection 对象表示一个文档集合，其名称通过 Id 属性指定。 如果文档集合不存在，则 CreateDocumentCollectionIfNotExistsAsync 方法会创建该文档集合；如果文档集合已存在，则会返回该文档集合。 但是，示例应用程序会忽略 CreateDocumentCollectionIfNotExistsAsync 方法返回的任何数据。

注意

CreateDocumentCollectionIfNotExistsAsync 方法返回一个 Task<ResourceResponse<DocumentCollection>> 对象。可以检查响应的状态代码以确定是创建了文档集合还是返回了现有文档集合。

（可选）CreateDocumentCollectionIfNotExistsAsync 方法还可以指定一个 RequestOptions 对象，该对象会封装可为向 Azure Cosmos DB 帐户发出的请求指定的选项。 RequestOptions.OfferThroughput 属性用于定义文档集合的性能级别，在示例应用程序中设置为每秒 400 个请求单位。 应根据集合是被频繁访问还是不被频繁访问来增加或减少该值。

重要

请注意，CreateDocumentCollectionIfNotExistsAsync 方法将创建一个具有预留吞吐量的新集合，这会影响定价。

检索文档集合文档

可以通过创建和执行文档查询来检索文档集合的内容。 使用 DocumentClient.CreateDocumentQuery 方法创建文档查询：

public async Task<List<TodoItem>> GetTodoItemsAsync()
{
  ...
  var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
            .AsDocumentQuery();
  while (query.HasMoreResults)
  {
    Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
  }
  ...
}

此查询异步检索指定集合中的所有文档，并将这些文档放入 List<TodoItem> 集合中进行显示。

CreateDocumentQuery<T> 方法指定一个 Uri 参数，该参数表示应该可以在其中查询文档的集合。 在此示例中，collectionLink 变量是一个类级字段，它指定的 Uri 表示可供从中检索文档的文档集合：

Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);

CreateDocumentQuery<T> 方法创建一个同步执行的查询，并返回 IQueryable<T> 对象。 不过，AsDocumentQuery 方法会将 IQueryable<T> 对象转换为可以异步执行的 IDocumentQuery<T> 对象。 异步查询使用 IDocumentQuery<T>.ExecuteNextAsync 方法执行，该方法从文档数据库检索下一页结果，并使用 IDocumentQuery<T>.HasMoreResults 属性指示是否有要从查询返回的其他结果。

可以通过在查询中包含 Where 子句在服务器端筛选文档，该子句将筛选谓词应用于针对文档集合的查询：

var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
          .Where(f => f.Done != true)
          .AsDocumentQuery();

此查询从 Done 属性等于 false 的集合中检索所有文档。

将文档插入文档集合

文档是用户定义的 JSON 内容，可以使用 DocumentClient.CreateDocumentAsync 方法插入到文档集合中：

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.CreateDocumentAsync(collectionLink, item);
  ...
}

CreateDocumentAsync 方法指定一个 Uri 参数（表示文档应插入到其中的集合）和一个 object 参数（表示要插入的文档）。

替换文档集合中的文档

可以使用 DocumentClient.ReplaceDocumentAsync 方法替换文档集合中的文档：

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
  ...
}

ReplaceDocumentAsync 方法指定一个 Uri 参数（表示集合中应替换的文档）和一个 object 参数（表示更新的文档数据）。

从文档集合中删除文档

可以使用 DocumentClient.DeleteDocumentAsync 方法从文档集合中删除文档：

public async Task DeleteTodoItemAsync(string id)
{
  ...
  await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
  ...
}

DeleteDocumentAsync 方法指定一个 Uri 参数，该参数表示集合中应删除的文档。

删除文档集合

可以使用 DocumentClient.DeleteDocumentCollectionAsync 方法从数据库中删除文档集合：

await client.DeleteDocumentCollectionAsync(collectionLink);

DeleteDocumentCollectionAsync 方法指定一个 Uri 参数，该参数表示要删除的文档集合。 请注意，调用此方法还会删除存储在集合中的文档。

删除数据库

可以使用 DocumentClient.DeleteDatabaesAsync 方法从 Azure Cosmos DB 数据库帐户中删除数据库：

await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));

DeleteDatabaseAsync 方法指定一个 Uri 参数，该参数表示要删除的数据库。 请注意，调用此方法还会删除数据库中存储的文档集合以及文档集合中存储的文档。

总结

本文介绍了如何使用 Azure Cosmos DB .NET Standard 客户端库将 Azure Cosmos DB 文档数据库集成到 Xamarin.Forms 应用程序中。 Azure Cosmos DB 文档数据库是 NoSQL 数据库，它提供对 JSON 文档的低延迟访问，为需要无缝缩放和全局复制的应用程序提供快速、高度可用的可缩放数据库服务。

相关链接

• Todo Azure Cosmos DB（示例）
• Azure Cosmos DB 文档
• Azure Cosmos DB .NET Standard 客户端库
• Azure Cosmos DB API