# .NET 对象持久化模型中的 DynamoDBContext 类 `DynamoDBContext` 类是 Amazon DynamoDB 的入口点。这个类提供到 DynamoDB 的连接，让您能够访问各种表的数据，执行各种 CRUD 操作，以及执行查询。`DynamoDBContext` 类提供了以下方法。 **Topics** + [Create​MultiTable​BatchGet](#w2aac17b9c21c23c39b7) + [Create​MultiTable​BatchWrite](#w2aac17b9c21c23c39b9) + [CreateBatchGet](#w2aac17b9c21c23c39c11) + [CreateBatchWrite](#w2aac17b9c21c23c39c13) + [删除](#w2aac17b9c21c23c39c15) + [Dispose](#w2aac17b9c21c23c39c17) + [Execute​Batch​Get](#w2aac17b9c21c23c39c19) + [Execute​Batch​Write](#w2aac17b9c21c23c39c21) + [FromDocument](#w2aac17b9c21c23c39c23) + [FromQuery](#w2aac17b9c21c23c39c25) + [FromScan](#w2aac17b9c21c23c39c27) + [Get​Target​Table](#w2aac17b9c21c23c39c29) + [Load](#w2aac17b9c21c23c39c31) + [查询](#w2aac17b9c21c23c39c33) + [Save](#w2aac17b9c21c23c39c35) + [Scan](#w2aac17b9c21c23c39c37) + [ToDocument](#w2aac17b9c21c23c39c39) + [指定 DynamoDBContext 的可选参数](#OptionalConfigParams) ## Create​MultiTable​BatchGet 创建 `MultiTableBatchGet` 对象，由多个单独 `BatchGet` 对象组成。每个 `BatchGet` 对象可用于从单个 DynamoDB 表中检索项目。 要从表中检索项目，请使用 `ExecuteBatchGet` 方法，传递 `MultiTableBatchGet` 对象作为参数。 ## Create​MultiTable​BatchWrite 创建 `MultiTableBatchWrite` 对象，由多个单独 `BatchWrite` 对象组成。每个 `BatchWrite` 对象可用于写入或删除单个 DynamoDB 表中的项目。 要写入表，请使用 `ExecuteBatchWrite` 方法，传递 `MultiTableBatchWrite` 对象作为参数。 ## CreateBatchGet 创建 `BatchGet` 对象，可以用于从表中检索多个项目。 ## CreateBatchWrite 创建 `BatchWrite` 对象，可以用于将多个项目放入表中，或者从表中删除多个项目。 ## 删除 删除表中的项目。此方法需要要删除的项目的主键。您可以提供主键值或包含主键值的客户端对象作为此方法的参数。 + 如果将客户端对象指定为参数，并且启用了乐观锁定，则只有在对象的客户端版本和服务器端版本匹配时，删除才会成功。 + 如果仅将主键值指定为参数，则无论您是否启用了乐观锁定，删除都会成功。 **注意** 要在后台执行此操作，请使用 `DeleteAsync` 方法。 ## Dispose 处置所有托管和非托管资源。 ## Execute​Batch​Get 从一个或多个表中读取数据，处理 `MultiTableBatchGet` 中的所有 `BatchGet` 对象。 **注意** 要在后台执行此操作，请使用`ExecuteBatchGetAsync`方法。 ## Execute​Batch​Write 在一个或多个表中写入或删除数据，处理 `MultiTableBatchWrite` 中的所有 `BatchWrite` 对象。 **注意** 要在后台执行此操作，请使用`ExecuteBatchWriteAsync`方法。 ## FromDocument 给定一个 `Document` 实例，`FromDocument` 方法返回客户端类的实例。 如果要将文档模型类与对象持久化模型一起使用来执行任何数据操作，这将非常有用。有关 适用于 .NET 的 AWS SDK 提供的文档模型类的更多信息，请参阅[在 DynamoDB 中使用 .NET 文档模型](DotNetSDKMidLevel.md)。 假设您有一个名为 `doc` 的 `Document` 对象，其中包含 `Forum` 项目。（要了解如何构造此对象，请参阅本主题稍后的 `ToDocument` 方法说明。） 您可以使用 `FromDocument` 从 `Document` 检索 `Forum` 项目，如以下 C\$1 代码示例所示。 **Example** ``` forum101 = context.FromDocument(101); ``` **注意** 如果您的`Document`对象实现`IEnumerable`接口，您可以使用`FromDocuments`方法。这允许您遍历`Document`的所有类实例。 ## FromQuery 运行`Query`操作，查询参数定义在`QueryOperationConfig`对象。 **注意** 要在后台执行此操作，请使用`FromQueryAsync`方法。 ## FromScan 运行`Scan`操作，扫描参数定义在`ScanOperationConfig`对象。 **注意** 要在后台执行此操作，请使用`FromScanAsync`方法。 ## Get​Target​Table 检索指定类型的目标表。如果您正在编写用于将任意数据映射到 DynamoDB 表的自定义转换器，并且需要确定哪个表与自定义数据类型相关联，则此选项非常有用。 ## Load 检索表中的项目。方法只需要要检索的项目的主键。 默认情况下，DynamoDB 所返回的项目的值采用最终一致性。有关最终一致性模式的信息，请参阅[DynamoDB 读取一致性](HowItWorks.ReadConsistency.md)。 `Load` 或 `LoadAsync` 方法调用 [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) 操作，该操作要求您为表指定主键。由于 `GetItem` 忽略了 `IndexName` 参数，因此您无法使用索引的分区或排序键加载项目。因此，必须使用表的主键来加载项目。 **注意** 要在后台执行此操作，请使用 `LoadAsync` 方法。要查看使用 `LoadAsync` 方法对 DynamoDB 表执行高级 CRUD 操作的示例，请参阅以下示例。 ``` /// /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB /// table. /// public class HighLevelItemCrud { public static async Task Main() { var client = new AmazonDynamoDBClient(); DynamoDBContext context = new DynamoDBContext(client); await PerformCRUDOperations(context); } public static async Task PerformCRUDOperations(IDynamoDBContext context) { int bookId = 1001; // Some unique value. Book myBook = new Book { Id = bookId, Title = "object persistence-AWS SDK for.NET SDK-Book 1001", Isbn = "111-1111111001", BookAuthors = new List { "Author 1", "Author 2" }, }; // Save the book to the ProductCatalog table. await context.SaveAsync(myBook); // Retrieve the book from the ProductCatalog table. Book bookRetrieved = await context.LoadAsync(bookId); // Update some properties. bookRetrieved.Isbn = "222-2222221001"; // Update existing authors list with the following values. bookRetrieved.BookAuthors = new List { " Author 1", "Author x" }; await context.SaveAsync(bookRetrieved); // Retrieve the updated book. This time, add the optional // ConsistentRead parameter using DynamoDBContextConfig object. await context.LoadAsync(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); // Delete the book. await context.DeleteAsync(bookId); // Try to retrieve deleted book. It should return null. Book deletedBook = await context.LoadAsync(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); if (deletedBook == null) { Console.WriteLine("Book is deleted"); } } } ``` ## 查询 根据您提供的查询参数查询表。 只有当表或索引具有复合主键（分区键和排序键）时，您才能对其执行查询。在查询时，您必须指定分区键以及适用于排序键的条件。 假设您有一个客户端`Reply`类映射到 DynamoDB 的 `Reply` 表。以下 C\$1 代码示例查询 `Reply` 以查找过去 15 天内发布的论坛话题回复。这些区域有：`Reply`表中有一个主键，该主键具有`Id`分区键和`ReplyDateTime`排序键。 **Example** ``` 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 latestReplies = context.Query(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate); ``` 该查询会一系列 `Reply` 对象。 在默认情况下，`Query` 方法返回“延迟加载”`IEnumerable`集合。它最初只返回一页结果，然后在需要时发出服务调用请求下一页结果。要获取所有匹配项目，请对 `IEnumerable` 集合进行迭代。 如果表具有简单主键（分区键），则无法使用 `Query` 方法。相反，您可以使用`Load`方法并提供用于检索项目的分区键。 **注意** 要在后台执行此操作，请使用`QueryAsync`方法。 ## Save 将指定对象保存到表中。如果表中不存在输入对象中指定的主键，则方法会将新项目添加到表中。如果存在主键，此方法就会更新现有项目。 如果您配置了乐观锁定，则仅当客户端和项目的服务器端版本匹配时，更新才会成功。有关更多信息，请参阅 [将 DynamoDB 和 适用于 .NET 的 AWS SDK 对象持久化模型结合使用的乐观锁](DynamoDBContext.VersionSupport.md)。 **注意** 要在后台执行此操作，请使用`SaveAsync`方法。 ## Scan 执行整个表扫描。 您可以通过指定扫描条件来筛选扫描结果。可以根据表中的任何属性对条件进行评估。假设您有一个客户端类 `Book` 映射到 DynamoDB 的 `ProductCatalog` 表。以下 C\$1 示例扫描表并仅返回价格小于 0 的书籍项目。 **Example** ``` IEnumerable itemsWithWrongPrice = context.Scan( new ScanCondition("Price", ScanOperator.LessThan, price), new ScanCondition("ProductCategory", ScanOperator.Equal, "Book") ); ``` 在默认情况下，`Scan` 方法返回“延迟加载”`IEnumerable`集合。它最初只返回一页结果，然后在需要时发出服务调用请求下一页结果。要获取所有匹配项，请对 `IEnumerable` 集合进行迭代。 出于性能考虑，您应查询表并避免表扫描。 **注意** 要在后台执行此操作，请使用`ScanAsync`方法。 ## ToDocument 返回类实例中的 `Document` 文档模型类。 如果要将文档模型类与对象持久化模型一起使用来执行任何数据操作，这将非常有用。有关 适用于 .NET 的 AWS SDK 提供的文档模型类的更多信息，请参阅[在 DynamoDB 中使用 .NET 文档模型](DotNetSDKMidLevel.md)。 假设您有一个映射到示例 `Forum` 表的客户端类。然后，您可以使用 `DynamoDBContext` 从 `Forum` 表获取一个项目作为 `Document` 对象，如以下 C\$1 代码示例所示。 **Example** ``` DynamoDBContext context = new DynamoDBContext(client); Forum forum101 = context.Load(101); // Retrieve a forum by primary key. Document doc = context.ToDocument(forum101); ``` ## 指定 DynamoDBContext 的可选参数 使用对象持久化模型时，您可以为 `DynamoDBContext` 指定以下可选参数。 + **`ConsistentRead`—**使用 `Load`、`Query` 或 `Scan` 操作检索数据时，可以添加此可选参数来请求数据的最新值。 + **`IgnoreNullValues`—**此参数通知 `DynamoDBContext` 在 `Save` 操作时忽略属性空值。如果此参数为 false（或未设置），则空值将被解释为删除特定属性的指令。 + **`SkipVersionCheck`—**此参数通知`DynamoDBContext`保存或删除项目时不比较版本。有关版本控制的更多信息，请参阅[将 DynamoDB 和 适用于 .NET 的 AWS SDK 对象持久化模型结合使用的乐观锁](DynamoDBContext.VersionSupport.md)。 + **`TableNamePrefix`—**在所有表名称前加上特定字符串。如果此参数为 null（或未设置），则不使用前缀。 + `DynamoDBEntryConversion` – 指定客户端使用的转换架构。可以将此参数设置为版本 V1 或 V2。默认版本是 V1。 根据您设置的版本，此参数的行为会发生变化。例如： + 在 V1 中，`bool` 数据类型转换为 `N` 数字类型，其中 0 代表 false，1 代表 true。在 V2 中，`bool` 转换为 `BOOL`。 + 在 V2 中，列表和数组不与哈希集组合在一起。数字、基于字符串的类型和基于二进制的类型的列表和数组将转换为 `L`（列表）类型，该类型可以发送空值以更新列表。这与 V1 不同，在 V1 中，不通过网络发送空列表。 在 V1 中，集合类型（例如列表、哈希集和数组）的处理方式相同。列表、哈希集和数组将转换为 `NS`（数字集）类型。 以下示例将转换架构版本设置为 V2，这会更改 .NET 类型和 DynamoDB 数据类型之间的转换行为。 ``` var config = new DynamoDBContextConfig { Conversion = DynamoDBEntryConversion.V2 }; var contextV2 = new DynamoDBContext(client, config); ``` 下面的 C\$1 示例通过指定前面的两个可选参数（`ConsistentRead` 和 `SkipVersionCheck`），来创建一个新的 `DynamoDBContext`。 **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true}); ``` `DynamoDBContext` 包含这些可选参数以及您使用此上下文发送的每个请求。 不在 `DynamoDBContext` 级别设置这些参数，可以为使用 `DynamoDBContext` 运行的各个操作指定，如以下 C\$1 代码示例所示。此示例加载特定的图书项目。`DynamoDBContext` 的 `Load` 方法指定 `ConsistentRead` 和 `SkipVersionCheck` 可选参数。 **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client); Book bookItem = context.Load(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true }); ``` 在这种情况下，`DynamoDBContext` 仅在发送 `Get` 请求时包含这些参数。