適用於 Xamarin 的 AWS Mobile SDK 現在已包含在 中 適用於 .NET 的 AWS SDK。本指南參考 Mobile SDK for Xamarin 的封存版本。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用物件持久性模型
<a name="dynamodb-integration-objectpersistencemodel"></a>

適用於 .NET 和 Xamarin 的 AWS Mobile SDK 提供物件持久性模型，可讓您將用戶端類別映射至 DynamoDB 資料表。然後，每個物件執行個體都會對應至對應資料表中的項目。若要將用戶端物件儲存至資料表，物件持久性模型會提供 DynamoDBContext 類別，這是 DynamoDB 的進入點。此類別可讓您連線至 DynamoDB，並可讓您存取資料表、執行各種 CRUD 操作，以及執行查詢。

物件持久性模型不提供 API 來建立、更新或刪除資料表。它只提供資料操作。若要建立、更新和刪除資料表，您必須使用低階 API。如需如何使用低階 API 的說明，請參閱[使用 DynamoDB 服務層級 APIs](dynamodb-integration-lowlevelapi.md)。

## 概觀
<a name="overview"></a>

物件持久性模型提供一組屬性，可將用戶端類別映射至資料表，並將屬性/欄位映射至資料表屬性。物件持久性模型支援類別屬性和資料表屬性之間的明確和預設映射。
+  **明確映射**：若要將屬性映射至主索引鍵，您必須使用 DynamoDBHashKey 和 DynamoDBRangeKey 物件持久性模型屬性。此外，對於非主要金鑰屬性，如果您類別中的屬性名稱和您要映射的對應資料表屬性不同，則必須明確新增 DynamoDBProperty 屬性來定義映射。
+  **預設映射** - 物件持久性模型預設會將類別屬性映射至資料表中同名的屬性。

您不需要映射每個單一類別屬性。您可以新增 DynamoDBIgnore 屬性來識別這些屬性。儲存和擷取物件的執行個體會省略任何標示此屬性的屬性。

## 支援的資料類型
<a name="supported-data-types"></a>

物件持久性模型支援一組基本 .NET 資料類型、集合和任意資料類型。模型目前支援下列基本資料類型。
+ bool
+ byte
+ char
+ DateTime
+ 小數、雙數、浮點數
+ Int16, Int32, Int64
+ SByte
+ string
+ UInt16, UInt32, UInt64

物件持久性模型也支援具有下列限制的 .NET 集合類型：
+ 集合類型必須實作 ICollection 介面。
+ 集合類型必須由支援的基本類型組成。例如，ICollection<string>、ICollection<bool>。
+ 集合類型必須提供無參數建構函數。

如需物件持久性模型的詳細資訊，請參閱 [.NET 物件持久性模型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DotNetSDKHighLevel.html)。

## 建立 DynamoDB 用戶端
<a name="create-a-dynamodb-client"></a>

若要建立 DynamoDB 用戶端：

```
var client = new AmazonDynamoDBClient(credentials,region);
DynamoDBContext context = new DynamoDBContext(client);
```

## CRUD 操作
<a name="crud-operations"></a>

### 儲存物件
<a name="save-an-object"></a>

建立 物件：

```
[DynamoDBTable("Books")]
public class Book {
  [DynamoDBHashKey] // Hash key.
  public string Id {
    get;
    set;
  }

  [DynamoDBGlobalSecondaryIndexHashKey]
  public string Author {
    get;
    set;
  }

  [DynamoDBGlobalSecondaryIndexRangeKey]
  public string Title {
    get;
    set;
  }
  public string ISBN {
    get;
    set;
  }
  public int Price {
    get;
    set;
  }
  public string PageCount {
    get;
    set;
  }
}

Book myBook = new Book
{
    Id = id,
    Author = "Charles Dickens",
    Title = "Oliver Twist",
    ISBN = "111-1111111001",
    Price = 10,
    PageCount = 300
};
```

將物件儲存至 DynamoDB 資料表：

```
context.Save(myBook);
```

### 擷取物件
<a name="retrieve-an-object"></a>

若要擷取物件：

```
Book retrievedBook = context.Load<Book>(1);
```

### 更新物件
<a name="update-an-object"></a>

若要更新物件：

```
Book retrievedBook = context.Load<Book>(1);
retrievedBook.ISBN = "111-1111111001";
context.Save(retrievedBook);
```

### 刪除物件
<a name="delete-an-object"></a>

若要刪除物件：

```
Book retrievedBook = context.Load<Book>(1);
context.Delete(retrievedBook);
```

## 查詢和掃描
<a name="query-and-scan"></a>

若要查詢和擷取作者為「Charles Dickens」的所有書籍：

```
public async Task QueryAsync(AWSCredentials credentials, RegionEndpoint region) {
  var client = new AmazonDynamoDBClient(credentials, region);
  DynamoDBContext context = new DynamoDBContext(client);

  var search = context.FromQueryAsync < Book > (new Amazon.DynamoDBv2.DocumentModel.QueryOperationConfig() {
    IndexName = "Author-Title-index",
    Filter = new Amazon.DynamoDBv2.DocumentModel.QueryFilter("Author", Amazon.DynamoDBv2.DocumentModel.QueryOperator.Equal, "Charles Dickens")
  });

  Console.WriteLine("items retrieved");

  var searchResponse = await search.GetRemainingAsync();
  searchResponse.ForEach((s) = > {
    Console.WriteLine(s.ToString());
  });
}
```

以下掃描範例程式碼會傳回我們資料表中的所有書籍：

```
public async Task ScanAsync(AWSCredentials credentials, RegionEndpoint region) {
  var client = new AmazonDynamoDBClient(credentials, region);
  DynamoDBContext context = new DynamoDBContext(client);

  var search = context.FromScanAsync < Book > (new Amazon.DynamoDBv2.DocumentModel.ScanOperationConfig() {
   ConsistentRead = true
  });

  Console.WriteLine("items retrieved");

  var searchResponse = await search.GetRemainingAsync();
  searchResponse.ForEach((s) = > {
   Console.WriteLine(s.ToString());
  });
}
```