登录控制台
Amazon DynamoDB
开发人员指南 (API 版本 2012-08-10)
AWS 文档 » Amazon DynamoDB » 开发人员指南 » 使用 DynamoDB 和 AWS 开发工具包进行编程 » DynamoDB 的高级编程接口 » .NET：对象持久化模型 » DynamoDBContext 类
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

DynamoDBContext 类

DynamoDBContext 类是 Amazon DynamoDB 数据库的入口点。它提供到 DynamoDB 的连接、让您能够访问各种表中的数据、执行各种 CRUD 操作，以及执行查询。DynamoDBContext 类提供以下方法。

Create​MultiTable​BatchGet

创建由多个 MultiTableBatchGet 对象组成的 BatchGet 对象。其中每个 BatchGet 对象都可用于检索单个 DynamoDB 表的项目。

要检索表中的项目，请使用 ExecuteBatchGet 方法，将 MultiTableBatchGet 对象作为参数传递。

Create​MultiTable​BatchWrite

创建由多个 MultiTableBatchWrite 对象组成的 BatchWrite 对象。其中每个 BatchWrite 对象都可用于写入或删除单个 DynamoDB 表中的项目。

要向表中写入，请使用 ExecuteBatchWrite 方法，将 MultiTableBatchWrite 对象作为参数传递。

Create​Batch​Get

创建可用于检索表中的多个项目的 BatchGet 对象。有关更多信息，请参阅批量获取：获取多个项目 。

Create​Batch​写入

创建用于将多个项目放入表中或删除表中多个项目的 BatchWrite 对象。有关更多信息，请参阅批量写入：放置和删除多个项目 。

Delete

删除表中的项目。此方法需要您提供要删除的项目的主键。您可以提供主键值，也可以提供包含主键值的客户端数据元作为此方法的参数。

  • 如果您指定一个客户端数据元作为参数，并且启用了乐观锁，那么只有当数据元的客户端版本和服务器端版本相匹配时才能成功执行删除操作。

  • 如果您只将主键值指定为参数，那么不管您是否启用乐观锁，都可以成功执行删除操作。

注意

要在后台执行此操作，请使用 DeleteAsync 方法。

Dispose

处理所有托管及非托管资源。

Execute​Batch​Get

读取一个或多个表中的数据，在 BatchGet 中处理所有 MultiTableBatchGet 对象。

注意

要在后台执行此操作，请使用 ExecuteBatchGetAsync 方法。

Execute​Batch​写入

在一个或多个表中写入或删除数据，在 BatchWrite 中处理所有 MultiTableBatchWrite 对象。

注意

要在后台执行此操作，请使用 ExecuteBatchWriteAsync 方法。

FromDocument

对于 Document 的实例，FromDocument 方法会返回客户端类的实例。

如果您要将文档模型类与对象持久化模型结合使用来执行任意数据操作，此方法会非常有用。有关适用于 .NET 的 AWS 开发工具包提供的文档模型类的更多信息，请参阅 .NET：文档模型。

假设您有名为 doc 的 Document 对象，其中包含 Forum 项目的表示。（要了解如何构造该对象，请参阅本主题稍后部分对 ToDocument 方法的说明。） 您可以使用 FromDocument 检索 Document 的 Forum 项目，如下面的 C# 代码示例所示。

例 

forum101 = context.FromDocument<Forum>(101);

注意

如果您的 Document 对象实现 IEnumerable 接口，则您可以使用 FromDocuments 方法。这样，您就可以对 Document 中的所有类实例进行迭代。

FromQuery

使用在 Query 对象中定义的查询参数执行 QueryOperationConfig 操作。

注意

要在后台执行此操作，请使用 FromQueryAsync 方法。

FromScan

使用在 Scan 对象中定义的扫描参数执行 ScanOperationConfig 操作。

注意

要在后台执行此操作，请使用 FromScanAsync 方法。

Get​Target​表

检索指定类型的目标表。如果您要编写用于将任意数据映射到 DynamoDB 表的自定义转换器，并需要确定与某个自定义数据类型关联的表，则该操作十分有用。

Load

检索表中的项目。此方法只需要您提供要检索的项目的主键。

默认情况下，DynamoDB 所返回的项目的值采用最终一致性。有关最终一致性模式的信息，请参阅读取一致性。

注意

要在后台执行此操作，请使用 LoadAsync 方法。

查询

根据您提供的查询参数查询表。

只有当表拥有复合主键 (分区键和排序键) 时，您才可以查询表。查询时，您必须指定一个分区键和一个适用于排序键的条件。

假设您有一个客户端 Reply 类映射到 DynamoDB 中的 Reply 表。以下 C# 代码示例可以查询 Reply 表，以查找过去 15 天内发布的论坛话题回复。Reply 表的主键具有 Id 分区键和 ReplyDateTime 排序键。有关 Reply 表的更多信息，请参阅创建表并加载样本数据。

例 

DynamoDBContext context = new DynamoDBContext(client);

string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key 
DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare.
IEnumerable<Reply> latestReplies = context.Query<Reply>(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);

此查询返回一系列 Reply 数据元。

Query 方法可以返回“延迟加载”IEnumerable 集合。它最初只返回一页结果，然后在需要时发出服务调用请求下一页结果。要获取所有匹配项，您只需对 IEnumerable 进行迭代。

如果您的表具有简单主键（分区键），您就无法使用 Query 方法。您可以改而使用 Load 方法并提供分区键来检索相应的项目。

注意

要在后台执行此操作，请使用 QueryAsync 方法。

Save

将指定对象保存到表中。如果表中没有在输入对象中指定的主键，该方法就会向表中添加新项目。如果主键存在，该方法会更新现有项目。

如果您配置了乐观锁，那么只有在项目的客户端版本和服务器端版本匹配时才能成功执行更新操作。有关更多信息，请参阅 乐观锁（使用版本号）与 DynamoDB（使用适用于 .NET 的 AWS 开发工具包对象持久化模型）配合使用。

注意

要在后台执行此操作，请使用 SaveAsync 方法。

扫描

执行全表扫描。

您可以通过指定扫描条件来筛选扫描结果。您可以就表中的任意属性对条件进行评估。假设您有一个客户端类 Book 映射到 DynamoDB 中的 ProductCatalog 表。以下 C# 代码示例可以扫描此表，并且只返回价格低于 0 的图书项目。

例 

IEnumerable<Book> itemsWithWrongPrice = context.Scan<Book>(
                    new ScanCondition("Price", ScanOperator.LessThan, price),
                    new ScanCondition("ProductCategory", ScanOperator.Equal, "Book")
      );

Scan 方法可以返回“延迟加载”IEnumerable 集合。它最初只返回一页结果，然后在需要时发出服务调用请求下一页结果。要获取所有匹配的项目，您只需对 IEnumerable 进行迭代。

出于性能考虑，您应对表进行查询，而避免进行扫描。

注意

要在后台执行此操作，请使用 ScanAsync 方法。

ToDocument

从您的类实例返回 Document 文档模型类的实例。

如果您要将文档模型类与对象持久化模型结合使用来执行任意数据操作，此方法会非常有用。有关适用于 .NET 的 AWS 开发工具包提供的文档模型类的更多信息，请参阅.NET：文档模型。

假设您有一个客户端类映射到 Forum 样本表。您就可以使用 DynamoDBContext 从 Forum 表中获取项目作为 Document 对象，如以下 C# 代码示例所示。

例 

DynamoDBContext context = new DynamoDBContext(client);

Forum forum101 = context.Load<Forum>(101); // Retrieve a forum by primary key.
Document doc = context.ToDocument<Forum>(forum101);

指定适用于 DynamoDBContext 的可选参数

在使用对象持久化模型时，您可以为 DynamoDBContext 指定以下可选参数。

  • ConsistentRead — 当使用 Load、Query 或 Scan 操作检索数据时，您可以选择添加此可选参数来请求数据的最新值。

  • IgnoreNullValues — 此参数通知 DynamoDBContext 在 Save 操作期间忽略属性的所有空值。如果该参数为 False（或者未设置），则会将空值解释为用于删除特定属性的指令。

  • SkipVersionCheck— 此参数通知 DynamoDBContext 在保存或删除项目时不比较版本。有关版本控制的更多信息，请参阅乐观锁（使用版本号）与 DynamoDB（使用适用于 .NET 的 AWS 开发工具包对象持久化模型）配合使用。

  • TableNamePrefix— 为所有表名称加上特定字符串前缀。如果该参数为空 (或者未设置)，则不使用前缀。

以下 C# 代码示例通过指定上述两个可选参数来创建新的 DynamoDBContext。

例 

AmazonDynamoDBClient client = new AmazonDynamoDBClient();      
...
DynamoDBContext context = 
       new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});

DynamoDBContext 在您使用此上下文发送的每个请求中都包含这两个可选参数。

您可以不在 DynamoDBContext 级设置这两个参数，而是为使用 DynamoDBContext 执行的操作单独指定这两个参数，如以下 C# 代码示例所示。该示例加载一个特定图书项目。Load 的 DynamoDBContext 方法会指定上述可选参数。

例 

AmazonDynamoDBClient client = new AmazonDynamoDBClient();      
...
DynamoDBContext context = new DynamoDBContext(client);
Book bookItem = context.Load<Book>(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });

在本示例中，DynamoDBContext 只在发送 Get 请求时包含这两个参数。