. 物件持久性模型的 D ynamoDBContext NET類別

焦點模式

. 物件持久性模型的 D ynamoDBContext NET類別 - Amazon DynamoDB

建立MultiTableBatchGet 建立MultiTableBatchWrite CreateBatchGet CreateBatchWrite Delete Dispose ExecuteBatchGet ExecuteBatchWrite FromDocument FromQuery FromScan GetTargetTable 載入 Query Save Scan ToDocument 指定 D 的選用參數ynamoDBContext

DynamoDBContext 類別是 Amazon DynamoDB 資料庫的進入點。它提供 DynamoDB 的連線，可讓您存取各種資料表中的資料、執行各種CRUD操作，以及執行查詢。此 DynamoDBContext 類別提供下列方法。

主題

建立MultiTableBatchGet
建立MultiTableBatchWrite
CreateBatchGet
CreateBatchWrite
Delete
Dispose
ExecuteBatchGet
ExecuteBatchWrite
FromDocument
FromQuery
FromScan
GetTargetTable
載入
Query
Save
Scan
ToDocument
指定 D 的選用參數ynamoDBContext

建立MultiTableBatchGet

建立由多個個別 BatchGet 物件組成的 MultiTableBatchGet 物件。其中的每個 BatchGet 物件都可用來從單一 DynamoDB 資料表中擷取項目。

若要從資料表擷取項目，請使用 ExecuteBatchGet 方法，將 MultiTableBatchGet 物件作為參數傳遞。

建立MultiTableBatchWrite

建立由多個個別 BatchWrite 物件組成的 MultiTableBatchWrite 物件。其中的每個 BatchWrite 物件可用來寫入或刪除單一 DynamoDB 資料表中的項目。

若要寫入資料表，請使用 ExecuteBatchWrite 方法，將 MultiTableBatchWrite 物件作為參數傳遞。

CreateBatchGet

建立 BatchGet 物件，您可以使用該物件從資料表中擷取多個項目。

CreateBatchWrite

建立 BatchWrite 物件，您可以使用該物件將多個項目放入資料表中，或從資料表中刪除多個項目。

Delete

刪除資料表中的項目。這個方法需要您希望刪除之項目的主索引鍵。您可以提供主索引鍵值或包含主索引鍵值的用戶端物件，作為此方法的參數。

如果指定用戶端物件作為參數，且已啟用樂觀鎖定，則只有在物件的用戶端和伺服器端版本相符時，才能成功刪除項目。
如果只指定主索引鍵值作為參數，無論您是否已啟用樂觀鎖定，刪除都會成功。

注意

若要在背景執行此操作，請改用 DeleteAsync 方法。

Dispose

處置所有受管和非受管的資源。

ExecuteBatchGet

從一或多個資料表讀取資料，處理 MultiTableBatchGet 中的所有 BatchGet 物件。

注意

若要在背景執行此操作，請改用 ExecuteBatchGetAsync 方法。

ExecuteBatchWrite

在一或多個資料表中寫入或刪除資料，處理 MultiTableBatchWrite 中的所有 BatchWrite 物件。

注意

若要在背景執行此操作，請改用 ExecuteBatchWriteAsync 方法。

FromDocument

若為 Document 執行個體，FromDocument 方法會傳回用戶端類別的執行個體。

如果您想使用文件模型類別以及物件持久性模型來執行任何資料操作，這會很有幫助。如需所提供文件模型類別的詳細資訊 AWS SDK for .NET，請參閱在 DynamoDB 中使用 .NET 文件模型。

假設您有名為 doc 的 Document 物件，且其中包含 Forum 項目的表示法。(若要查看如何建構此物件，請參閱本主題後續內容中的 ToDocument 方法說明。) 您可以使用 FromDocument 從 Document 擷取 Forum 項目，如下列 C# 程式碼範例所示。

範例


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

注意

如果您的 Document 物件會實作 IEnumerable 界面，您可以使用 FromDocuments 方法。這允許您逐一查看 Document 中的所有類別執行個體。

FromQuery

以 QueryOperationConfig 物件中定義的查詢參數執行 Query 操作。

注意

若要在背景執行此操作，請改用 FromQueryAsync 方法。

FromScan

以 ScanOperationConfig 物件中定義的掃描參數執行 Scan 操作。

注意

若要在背景執行此操作，請改用 FromScanAsync 方法。

GetTargetTable

擷取指定類型的目標資料表。如果您正在撰寫自訂轉換器，將任意資料映射至 DynamoDB 資料表，而且需要判斷哪個資料表與自訂資料類型相關聯，則此功能非常有用。

載入

從資料表擷取項目。這個方法只需要您希望擷取之項目的主索引鍵。

DynamoDB 預設會傳回數值最終一致的項目。如需最終一致性模型的資訊，請參閱 DynamoDB 讀取一致性。

Load 或 LoadAsync方法會呼叫 GetItem操作，這需要您指定資料表的主索引鍵。因為會GetItem忽略 IndexName 參數，所以您無法使用索引的分割區或排序索引鍵載入項目。因此，您必須使用資料表的主索引鍵來載入項目。

注意

若要在背景執行此操作，請改用 LoadAsync 方法。若要檢視使用 LoadAsync方法在 DynamoDB 資料表上執行高階CRUD操作的範例，請參閱下列範例。



    /// <summary>
    /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB
    /// table.
    /// </summary>
    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<string> { "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<Book>(bookId);

            // Update some properties.
            bookRetrieved.Isbn = "222-2222221001";

            // Update existing authors list with the following values.
            bookRetrieved.BookAuthors = new List<string> { " 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<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            // Delete the book.
            await context.DeleteAsync<Book>(bookId);

            // Try to retrieve deleted book. It should return null.
            Book deletedBook = await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            if (deletedBook == null)
            {
                Console.WriteLine("Book is deleted");
            }
        }
    }

Query

根據您提供的查詢參數查詢資料表。

您只能查詢具有複合主索引鍵 (分割區索引鍵和排序索引鍵) 的資料表。查詢時，必須指定分割區索引鍵和套用至排序索引鍵的條件。

假設您有用戶端 Reply 類別映射至 DynamoDB 中的 Reply 資料表。下列 C# 程式碼範例會查詢 Reply 資料表，找出過去 15 天所張貼的論壇主題回覆。Reply 資料表的主索引鍵具有 Id 分割區索引鍵和 ReplyDateTime 排序索引鍵。

範例


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 和 AWS SDK for .NET 物件持久性模型的樂觀鎖定。

注意

若要在背景執行此操作，請改用 SaveAsync 方法。

Scan

執行整個資料表掃描。

您可以指定掃描條件來篩選掃描結果。您可以根據資料表中的任何屬性來評估條件。假設您有用戶端 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 文件模型類別的執行個體。

假設您有用戶端類別映射至範例 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);

指定 D 的選用參數ynamoDBContext

使用物件持久性模型時，您可以指定 DynamoDBContext 的下列選用參數。

ConsistentRead：當使用 Load、Query 或 Scan 操作來擷取資料時，您可以新增此選用參數來請求資料的最新數值。
IgnoreNullValues：此參數會通知 DynamoDBContext 在 Save 操作期間忽略屬性上的 Null 數值。如果此參數為 false (或未設定)，則會將 Null 數值轉譯為刪除特定屬性的指令。
SkipVersionCheck：此參數會通知 DynamoDBContext 不要在儲存或刪除項目時比較版本。如需版本控制的詳細資訊，請參閱「使用 DynamoDB 和 AWS SDK for .NET 物件持久性模型的樂觀鎖定」。
TableNamePrefix：使用特定字串作為所有資料表名稱的字首。如果此參數為 null (或未設定)，則不會使用字首。
DynamoDBEntryConversion – 指定用戶端使用的轉換結構描述。您可以將此參數設定為版本 V1 或 V2。V1 是預設版本。

根據您設定的版本，此參數的行為會變更。例如：
- 在 V1 中，bool資料類型會轉換為N數字類型，其中 0 代表 false，1 代表 true。在 V2 中， bool 會轉換為 BOOL。
- 在 V2 中，清單和陣列不會與分組 HashSets。數值、字串類型和二進位類型清單和陣列會轉換為 L（清單）類型，可以空傳送來更新清單。這與 V1 不同，其中空白清單不會透過線路傳送。
  
  在 V1 中，集合類型，例如 List HashSet和陣列會視為相同。清單 HashSet和的數值陣列會轉換為 NS（資料集）類型。
下列範例會將轉換結構描述版本設定為 V2，這會變更 .NET 類型和 DynamoDB 資料類型之間的轉換行為。
```
var config = new DynamoDBContextConfig
{
    Conversion = DynamoDBEntryConversion.V2
};
var contextV2 = new DynamoDBContext(client, config);
```

下列 C# 範例DynamoDBContext會指定上述兩個選用參數 ConsistentRead和來建立新的參數SkipVersionCheck。

範例


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

DynamoDBContext 包含這些選用參數，以及您使用此內容傳送的每個請求。

您可以使用 DynamoDBContext 為個別操作指定參數，而不是在 DynamoDBContext 層級設定這些參數，如下列 C# 程式碼範例所示。此範例會載入特定的書籍項目。的 Load方法DynamoDBContext指定 ConsistentRead和SkipVersionCheck選用參數。

範例


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

在此例中，DynamoDBContext 只有在傳送 Get 請求時才會包含這些參數。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

DynamoDB 屬性

使用版本編號的樂觀鎖定

選取您的 Cookie 偏好設定

. 物件持久性模型的 D ynamoDBContext NET類別

主題

建立MultiTableBatchGet

建立MultiTableBatchWrite

CreateBatchGet

CreateBatchWrite

Delete

注意

Dispose

Execute​Batch​Get

注意

Execute​Batch​Write

注意

FromDocument

範例

注意

FromQuery

注意

FromScan

注意

Get​Target​Table

載入

注意

Query

範例

注意

Save

注意

Scan

範例

注意

ToDocument

範例

指定 D 的選用參數ynamoDBContext

範例

範例

在本頁面

Related resources

此頁面是否有幫助？

Related resources

下一個主題：

上一個主題：

需要協助？

ExecuteBatchGet

ExecuteBatchWrite

GetTargetTable