# Working with the .NET object persistence model and DynamoDB
The AWS SDK for .NET provides an object persistence model that enables you to map your client-side classes to Amazon DynamoDB tables. Each object instance then maps to an item in the corresponding tables. To save your client-side objects to the tables, the object persistence model provides the `DynamoDBContext` class, an entry point to DynamoDB. This class provides you a connection to DynamoDB and enables you to access tables, perform various CRUD operations, and run queries.
The object persistence model provides a set of attributes to map client-side classes to tables, and properties/fields to table attributes.
**Note**
The object persistence model does not provide an API to create, update, or delete tables. It provides only data operations. You can use only the AWS SDK for .NET low-level API to create, update, and delete tables.
The following example shows how the object persistence model works. It starts with the `ProductCatalog` table. It has `Id` as the primary key.
```
ProductCatalog(Id, ...)
```
Suppose that you have a `Book` class with `Title`, `ISBN`, and `Authors` properties. You can map the `Book` class to the `ProductCatalog` table by adding the attributes defined by the object persistence model, as shown in the following C\$1 code example.
**Example**
```
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey]
public int Id { get; set; }
public string Title { get; set; }
public int ISBN { get; set; }
[DynamoDBProperty("Authors")]
public List BookAuthors { get; set; }
[DynamoDBIgnore]
public string CoverPage { get; set; }
}
```
In the preceding example, the `DynamoDBTable` attribute maps the `Book` class to the `ProductCatalog` table.
The object persistence model supports both the explicit and default mapping between class properties and table attributes.
+ **Explicit mapping—**To map a property to a primary key, you must use the `DynamoDBHashKey` and `DynamoDBRangeKey` object persistence model attributes. Additionally, for the nonprimary key attributes, if a property name in your class and the corresponding table attribute to which you want to map it are not the same, you must define the mapping by explicitly adding the `DynamoDBProperty` attribute.
In the preceding example, the `Id` property maps to the primary key with the same name, and the `BookAuthors` property maps to the `Authors` attribute in the `ProductCatalog` table.
+ **Default mapping—**By default, the object persistence model maps the class properties to the attributes with the same name in the table.
In the preceding example, the properties `Title` and `ISBN` map to the attributes with the same name in the `ProductCatalog` table.
You don't have to map every single class property. You identify these properties by adding the `DynamoDBIgnore` attribute. When you save a `Book` instance to the table, the `DynamoDBContext` does not include the `CoverPage` property. It also does not return this property when you retrieve the book instance.
You can map properties of .NET primitive types such as int and string. You also can map any arbitrary data types as long as you provide an appropriate converter to map the arbitrary data to one of the DynamoDB types. To learn about mapping arbitrary types, see [Mapping arbitrary data with DynamoDB using the AWS SDK for .NET object persistence model](DynamoDBContext.ArbitraryDataMapping.md).
The object persistence model supports optimistic locking. During an update operation, this ensures that you have the latest copy of the item you are about to update. For more information, see [Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model](DynamoDBContext.VersionSupport.md).
For more information, see the topics below.
**Topics**
+ [Supported data types](#DotNetDynamoDBContext.SupportedTypes)
+ [DynamoDB attributes from the .NET object persistence model](DeclarativeTagsList.md)
+ [DynamoDBContext class from the .NET object persistence model](DotNetDynamoDBContext.md)
+ [Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model](DynamoDBContext.VersionSupport.md)
+ [Mapping arbitrary data with DynamoDB using the AWS SDK for .NET object persistence model](DynamoDBContext.ArbitraryDataMapping.md)
## Supported data types
The object persistence model supports a set of primitive .NET data types, collections, and arbitrary data types. The model supports the following primitive data types.
+ `bool`
+ `byte`
+ `char`
+ `DateTime`
+ `decimal`
+ `double`
+ `float`
+ `Int16`
+ `Int32`
+ `Int64`
+ `SByte`
+ `string`
+ `UInt16`
+ `UInt32`
+ `UInt64`
The object persistence model also supports the .NET collection types. `DynamoDBContext` is able to convert concrete collection types and simple Plain Old CLR Objects (POCOs).
The following table summarizes the mapping of the preceding .NET types to the DynamoDB types.
****
| .NET primitive type | DynamoDB type |
| --- | --- |
| All number types | `N` (number type) |
| All string types | `S` (string type) |
| MemoryStream, byte[] | `B` (binary type) |
| bool | N (number type). 0 represents false and 1 represents true. |
| Collection types | BS (binary set) type, SS (string set) type, and NS (number set) type |
| DateTime | S (string type). The DateTime values are stored as ISO-8601 formatted strings. |
The object persistence model also supports arbitrary data types. However, you must provide converter code to map the complex types to the DynamoDB types.
**Note**
Empty binary values are supported.
Reading of empty string values is supported. Empty string attribute values are supported within attribute values of string Set type while writing to DynamoDB. Empty string attribute values of string type and empty string values contained within List or Map type are dropped from write requests
# DynamoDB attributes from the .NET object persistence model
This section describes the attributes that the object persistence model offers so that you can map your classes and properties to DynamoDB tables and attributes.
**Note**
In the following attributes, only `DynamoDBTable` and `DynamoDBHashKey` are required.
## DynamoDBGlobalSecondaryIndexHashKey
Maps a class property to the partition key of a global secondary index. Use this attribute if you need to `Query` a global secondary index.
## DynamoDBGlobalSecondaryIndexRangeKey
Maps a class property to the sort key of a global secondary index. Use this attribute if you need to `Query` a global secondary index and want to refine your results using the index sort key.
## DynamoDBHashKey
Maps a class property to the partition key of the table's primary key. The primary key attributes cannot be a collection type.
The following C\$1 code example maps the `Book` class to the `ProductCatalog` table, and the `Id` property to the table's primary key partition key.
```
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey]
public int Id { get; set; }
// Additional properties go here.
}
```
## DynamoDBIgnore
Indicates that the associated property should be ignored. If you don't want to save any of your class properties, you can add this attribute to instruct `DynamoDBContext` not to include this property when saving objects to the table.
## DynamoDBLocalSecondaryIndexRangeKey
Maps a class property to the sort key of a local secondary index. Use this attribute if you need to `Query` a local secondary index and want to refine your results using the index sort key.
## DynamoDBProperty
Maps a class property to a table attribute. If the class property maps to a table attribute of the same name, you don't need to specify this attribute. However, if the names are not the same, you can use this tag to provide the mapping. In the following C\$1 statement, the `DynamoDBProperty` maps the `BookAuthors` property to the `Authors` attribute in the table.
```
[DynamoDBProperty("Authors")]
public List BookAuthors { get; set; }
```
`DynamoDBContext` uses this mapping information to create the `Authors` attribute when saving object data to the corresponding table.
## DynamoDBRenamable
Specifies an alternative name for a class property. This is useful if you are writing a custom converter for mapping arbitrary data to a DynamoDB table where the name of a class property is different from a table attribute.
## DynamoDBRangeKey
Maps a class property to the sort key of the table's primary key. If the table has a composite primary key (partition key and sort key), you must specify both the `DynamoDBHashKey` and `DynamoDBRangeKey` attributes in your class mapping.
For example, the sample table `Reply` has a primary key made of the `Id` partition key and `Replenishment` sort key. The following C\$1 code example maps the `Reply` class to the `Reply` table. The class definition also indicates that two of its properties map to the primary key.
```
[DynamoDBTable("Reply")]
public class Reply
{
[DynamoDBHashKey]
public int ThreadId { get; set; }
[DynamoDBRangeKey]
public string Replenishment { get; set; }
// Additional properties go here.
}
```
## DynamoDBTable
Identifies the target table in DynamoDB to which the class maps. For example, the following C\$1 code example maps the `Developer` class to the `People` table in DynamoDB.
```
[DynamoDBTable("People")]
public class Developer { ...}
```
This attribute can be inherited or overridden.
+ The `DynamoDBTable` attribute can be inherited. In the preceding example, if you add a new class, `Lead`, that inherits from the `Developer` class, it also maps to the `People` table. Both the `Developer` and `Lead` objects are stored in the `People` table.
+ The `DynamoDBTable` attribute can also be overridden. In the following C\$1 code example, the `Manager` class inherits from the `Developer` class. However, the explicit addition of the `DynamoDBTable` attribute maps the class to another table (`Managers`).
```
[DynamoDBTable("Managers")]
public class Manager : Developer { ...}
```
You can add the optional parameter, `LowerCamelCaseProperties`, to request DynamoDB to make the first letter of the property name lowercase when storing the objects to a table, as shown in the following C\$1 example.
```
[DynamoDBTable("People", LowerCamelCaseProperties=true)]
public class Developer
{
string DeveloperName;
...
}
```
When saving instances of the `Developer` class, `DynamoDBContext` saves the `DeveloperName` property as the `developerName`.
## DynamoDBVersion
Identifies a class property for storing the item version number. For more information about versioning, see [Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model](DynamoDBContext.VersionSupport.md).
# DynamoDBContext class from the .NET object persistence model
The `DynamoDBContext` class is the entry point to the Amazon DynamoDB database. It provides a connection to DynamoDB and enables you to access your data in various tables, perform various CRUD operations, and run queries. The `DynamoDBContext` class provides the following methods.
**Topics**
+ [CreateMultiTableBatchGet](#w2aac17b9c21c23c39b7)
+ [CreateMultiTableBatchWrite](#w2aac17b9c21c23c39b9)
+ [CreateBatchGet](#w2aac17b9c21c23c39c11)
+ [CreateBatchWrite](#w2aac17b9c21c23c39c13)
+ [Delete](#w2aac17b9c21c23c39c15)
+ [Dispose](#w2aac17b9c21c23c39c17)
+ [ExecuteBatchGet](#w2aac17b9c21c23c39c19)
+ [ExecuteBatchWrite](#w2aac17b9c21c23c39c21)
+ [FromDocument](#w2aac17b9c21c23c39c23)
+ [FromQuery](#w2aac17b9c21c23c39c25)
+ [FromScan](#w2aac17b9c21c23c39c27)
+ [GetTargetTable](#w2aac17b9c21c23c39c29)
+ [Load](#w2aac17b9c21c23c39c31)
+ [Query](#w2aac17b9c21c23c39c33)
+ [Save](#w2aac17b9c21c23c39c35)
+ [Scan](#w2aac17b9c21c23c39c37)
+ [ToDocument](#w2aac17b9c21c23c39c39)
+ [Specifying optional parameters for DynamoDBContext](#OptionalConfigParams)
## CreateMultiTableBatchGet
Creates a `MultiTableBatchGet` object, composed of multiple individual `BatchGet` objects. Each of these `BatchGet` objects can be used for retrieving items from a single DynamoDB table.
To retrieve the items from tables, use the `ExecuteBatchGet` method, passing the `MultiTableBatchGet` object as a parameter.
## CreateMultiTableBatchWrite
Creates a `MultiTableBatchWrite` object, composed of multiple individual `BatchWrite` objects. Each of these `BatchWrite` objects can be used for writing or deleting items in a single DynamoDB table.
To write to tables, use the `ExecuteBatchWrite` method, passing the `MultiTableBatchWrite` object as a parameter.
## CreateBatchGet
Creates a `BatchGet` object that you can use to retrieve multiple items from a table.
## CreateBatchWrite
Creates a `BatchWrite` object that you can use to put multiple items into a table, or to delete multiple items from a table.
## Delete
Deletes an item from the table. The method requires the primary key of the item you want to delete. You can provide either the primary key value or a client-side object containing a primary key value as a parameter to this method.
+ If you specify a client-side object as a parameter and you have enabled optimistic locking, the delete succeeds only if the client-side and the server-side versions of the object match.
+ If you specify only the primary key value as a parameter, the delete succeeds regardless of whether you have enabled optimistic locking or not.
**Note**
To perform this operation in the background, use the `DeleteAsync` method instead.
## Dispose
Disposes of all managed and unmanaged resources.
## ExecuteBatchGet
Reads data from one or more tables, processing all of the `BatchGet` objects in a `MultiTableBatchGet`.
**Note**
To perform this operation in the background, use the `ExecuteBatchGetAsync` method instead.
## ExecuteBatchWrite
Writes or deletes data in one or more tables, processing all of the `BatchWrite` objects in a `MultiTableBatchWrite`.
**Note**
To perform this operation in the background, use the `ExecuteBatchWriteAsync` method instead.
## FromDocument
Given an instance of a `Document`, the `FromDocument` method returns an instance of a client-side class.
This is helpful if you want to use the document model classes along with the object persistence model to perform any data operations. For more information about the document model classes provided by the AWS SDK for .NET, see [Working with the .NET document model in DynamoDB](DotNetSDKMidLevel.md).
Suppose that you have a `Document` object named `doc`, that contains a representation of a `Forum` item. (To see how to construct this object, see the description for the `ToDocument` method later in this topic.) You can use `FromDocument` to retrieve the `Forum` item from the `Document`, as shown in the following C\$1 code example.
**Example**
```
forum101 = context.FromDocument(101);
```
**Note**
If your `Document` object implements the `IEnumerable` interface, you can use the `FromDocuments` method instead. This allows you to iterate over all of the class instances in the `Document`.
## FromQuery
Runs a `Query` operation, with the query parameters defined in a `QueryOperationConfig` object.
**Note**
To perform this operation in the background, use the `FromQueryAsync` method instead.
## FromScan
Runs a `Scan` operation, with the scan parameters defined in a `ScanOperationConfig` object.
**Note**
To perform this operation in the background, use the `FromScanAsync` method instead.
## GetTargetTable
Retrieves the target table for the specified type. This is useful if you are writing a custom converter for mapping arbitrary data to a DynamoDB table, and you need to determine which table is associated with a custom data type.
## Load
Retrieves an item from a table. The method requires only the primary key of the item you want to retrieve.
By default, DynamoDB returns the item with values that are eventually consistent. For information about the eventual consistency model, see [DynamoDB read consistency](HowItWorks.ReadConsistency.md).
`Load` or `LoadAsync` method calls the [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) operation, which requires you to specify the primary key for the table. Because `GetItem` ignores the `IndexName` parameter, you can’t load an item using an index’s partition or sort key. Therefore, you must use the table's primary key to load an item.
**Note**
To perform this operation in the background, use the `LoadAsync` method instead. To view an example of using the `LoadAsync` method to perform high-level CRUD operations on a DynamoDB table, see the following example.
```
///
/// 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");
}
}
}
```
## Query
Queries a table based on query parameters you provide.
You can query a table only if it has a composite primary key (partition key and sort key). When querying, you must specify a partition key and a condition that applies to the sort key.
Suppose that you have a client-side `Reply` class mapped to the `Reply` table in DynamoDB. The following C\$1 code example queries the `Reply` table to find forum thread replies posted in the past 15 days. The `Reply` table has a primary key that has the `Id` partition key and the `ReplyDateTime` sort key.
**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);
```
This returns a collection of `Reply` objects.
The `Query` method returns a "lazy-loaded" `IEnumerable` collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you need to iterate only over the `IEnumerable`.
If your table has a simple primary key (partition key), you can't use the `Query` method. Instead, you can use the `Load` method and provide the partition key to retrieve the item.
**Note**
To perform this operation in the background, use the `QueryAsync` method instead.
## Save
Saves the specified object to the table. If the primary key specified in the input object doesn't exist in the table, the method adds a new item to the table. If the primary key exists, the method updates the existing item.
If you have optimistic locking configured, the update succeeds only if the client and the server-side versions of the item match. For more information, see [Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model](DynamoDBContext.VersionSupport.md).
**Note**
To perform this operation in the background, use the `SaveAsync` method instead.
## Scan
Performs an entire table scan.
You can filter scan results by specifying a scan condition. The condition can be evaluated on any attributes in the table. Suppose that you have a client-side class `Book` mapped to the `ProductCatalog` table in DynamoDB. The following C\$1 example scans the table and returns only the book items priced less than 0.
**Example**
```
IEnumerable itemsWithWrongPrice = context.Scan(
new ScanCondition("Price", ScanOperator.LessThan, price),
new ScanCondition("ProductCategory", ScanOperator.Equal, "Book")
);
```
The `Scan` method returns a "lazy-loaded" `IEnumerable` collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you only need to iterate over the `IEnumerable`.
For performance reasons, you should query your tables and avoid a table scan.
**Note**
To perform this operation in the background, use the `ScanAsync` method instead.
## ToDocument
Returns an instance of the `Document` document model class from your class instance.
This is helpful if you want to use the document model classes along with the object persistence model to perform any data operations. For more information about the document model classes provided by the AWS SDK for .NET, see [Working with the .NET document model in DynamoDB](DotNetSDKMidLevel.md).
Suppose that you have a client-side class mapped to the sample `Forum` table. You can then use a `DynamoDBContext` to get an item as a `Document` object from the `Forum` table, as shown in the following C\$1 code example.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
Forum forum101 = context.Load(101); // Retrieve a forum by primary key.
Document doc = context.ToDocument(forum101);
```
## Specifying optional parameters for DynamoDBContext
When using the object persistence model, you can specify the following optional parameters for the `DynamoDBContext`.
+ **`ConsistentRead`—**When retrieving data using the `Load`, `Query`, or `Scan` operations, you can add this optional parameter to request the latest values for the data.
+ **`IgnoreNullValues`—**This parameter informs `DynamoDBContext` to ignore null values on attributes during a `Save` operation. If this parameter is false (or if it is not set), then a null value is interpreted as a directive to delete the specific attribute.
+ **`SkipVersionCheck`—** This parameter informs `DynamoDBContext` not to compare versions when saving or deleting an item. For more information about versioning, see [Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model](DynamoDBContext.VersionSupport.md).
+ **`TableNamePrefix`—** Prefixes all table names with a specific string. If this parameter is null (or if it is not set), then no prefix is used.
+ `DynamoDBEntryConversion` – Specifies the conversion schema that is used by the client. You can set this parameter to version V1 or V2. V1 is the default version.
Based on the version that you set, the behavior of this parameter changes. For example:
+ In V1, the `bool` data type is converted to the `N` number type, where 0 represents false and 1 represents true. In V2, `bool` is converted to `BOOL`.
+ In V2, lists and arrays aren’t grouped together with HashSets. Lists and arrays of numerics, string-based types, and binary-based types are converted to the `L` (List) type, which can be sent empty to update a list. This is unlike V1, where an empty list isn't sent over the wire.
In V1, collection types, such as List, HashSet, and arrays are treated the same. List, HashSet, and array of numerics is converted to the `NS` (number set) type.
The following example sets the conversion schema version to V2, which changes the conversion behavior between .NET types and DynamoDB data types.
```
var config = new DynamoDBContextConfig
{
Conversion = DynamoDBEntryConversion.V2
};
var contextV2 = new DynamoDBContext(client, config);
```
The following C\$1 example creates a new `DynamoDBContext` by specifying two of the preceding optional parameters, `ConsistentRead` and `SkipVersionCheck`.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context =
new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});
```
`DynamoDBContext` includes these optional parameters with each request that you send using this context.
Instead of setting these parameters at the `DynamoDBContext` level, you can specify them for individual operations you run using `DynamoDBContext`, as shown in the following C\$1 code example. The example loads a specific book item. The `Load` method of `DynamoDBContext` specifies the `ConsistentRead` and `SkipVersionCheck` optional parameters.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context = new DynamoDBContext(client);
Book bookItem = context.Load(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });
```
In this case, `DynamoDBContext` includes these parameters only when sending the `Get` request.
# Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model
Optimistic locking support in the object persistence model ensures that the item version for your application is the same as the item version on the server side before updating or deleting the item. Suppose that you retrieve an item for update. However, before you send your updates back, some other application updates the same item. Now your application has a stale copy of the item. Without optimistic locking, any update you perform will overwrite the update made by the other application.
The optimistic locking feature of the object persistence model provides the `DynamoDBVersion` tag that you can use to enable optimistic locking. To use this feature, you add a property to your class for storing the version number. You add the `DynamoDBVersion` attribute to the property. When you first save the object, the `DynamoDBContext` assigns a version number and increments this value each time you update the item.
Your update or delete request succeeds only if the client-side object version matches the corresponding version number of the item on the server side. If your application has a stale copy, it must get the latest version from the server before it can update or delete that item.
The following C\$1 code example defines a `Book` class with object persistence attributes mapping it to the `ProductCatalog` table. The `VersionNumber` property in the class decorated with the `DynamoDBVersion` attribute stores the version number value.
**Example**
```
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey] //Partition key
public int Id { get; set; }
[DynamoDBProperty]
public string Title { get; set; }
[DynamoDBProperty]
public string ISBN { get; set; }
[DynamoDBProperty("Authors")]
public List BookAuthors { get; set; }
[DynamoDBVersion]
public int? VersionNumber { get; set; }
}
```
**Note**
You can apply the `DynamoDBVersion` attribute only to a nullable numeric primitive type (such as `int?`).
Optimistic locking has the following impact on `DynamoDBContext` operations:
+ For a new item, `DynamoDBContext` assigns initial version number 0. If you retrieve an existing item, update one or more of its properties, and try to save the changes, the save operation succeeds only if the version number on the client side and the server side match. `DynamoDBContext` increments the version number. You don't need to set the version number.
+ The `Delete` method provides overloads that can take either a primary key value or an object as parameter, as shown in the following C\$1 code example.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
...
// Load a book.
Book book = context.Load(111);
// Do other operations.
// Delete 1 - Pass in the book object.
context.Delete(book);
// Delete 2 - Pass in the Id (primary key)
context.Delete(222);
```
If you provide an object as the parameter, the delete succeeds only if the object version matches the corresponding server-side item version. However, if you provide a primary key value as the parameter, `DynamoDBContext` is unaware of any version numbers, and it deletes the item without making the version check.
Note that the internal implementation of optimistic locking in the object persistence model code uses the conditional update and the conditional delete API actions in DynamoDB.
## Disabling optimistic locking
To disable optimistic locking, you use the `SkipVersionCheck` configuration property. You can set this property when creating `DynamoDBContext`. In this case, optimistic locking is disabled for any requests that you make using the context. For more information, see [Specifying optional parameters for DynamoDBContext](DotNetDynamoDBContext.md#OptionalConfigParams).
Instead of setting the property at the context level, you can disable optimistic locking for a specific operation, as shown in the following C\$1 code example. The example uses the context to delete a book item. The `Delete` method sets the optional `SkipVersionCheck` property to true, disabling version checking.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
// Load a book.
Book book = context.Load(111);
...
// Delete the book.
context.Delete(book, new DynamoDBContextConfig { SkipVersionCheck = true });
```
# Mapping arbitrary data with DynamoDB using the AWS SDK for .NET object persistence model
In addition to the supported .NET types (see [Supported data types](DotNetSDKHighLevel.md#DotNetDynamoDBContext.SupportedTypes)), you can use types in your application for which there is no direct mapping to the Amazon DynamoDB types. The object persistence model supports storing data of arbitrary types as long as you provide the converter to convert data from the arbitrary type to the DynamoDB type and vice versa. The converter code transforms data during both the saving and loading of the objects.
You can create any types on the client-side. However the data stored in the tables is one of the DynamoDB types, and during query and scan, any data comparisons made are against the data stored in DynamoDB.
The following C\$1 code example defines a `Book` class with `Id`, `Title`, `ISBN`, and `Dimension` properties. The `Dimension` property is of the `DimensionType` that describes `Height`, `Width`, and `Thickness` properties. The example code provides the converter methods `ToEntry` and `FromEntry` to convert data between the `DimensionType` and the DynamoDB string types. For example, when saving a `Book` instance, the converter creates a book `Dimension` string such as "8.5x11x.05". When you retrieve a book, it converts the string to a `DimensionType` instance.
The example maps the `Book` type to the `ProductCatalog` table. It saves a sample `Book` instance, retrieves it, updates its dimensions, and saves the updated `Book` again.
For step-by-step instructions for testing the following example, see [.NET code examples](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class HighLevelMappingArbitraryData
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
static void Main(string[] args)
{
try
{
DynamoDBContext context = new DynamoDBContext(client);
// 1. Create a book.
DimensionType myBookDimensions = new DimensionType()
{
Length = 8M,
Height = 11M,
Thickness = 0.5M
};
Book myBook = new Book
{
Id = 501,
Title = "AWS SDK for .NET Object Persistence Model Handling Arbitrary Data",
ISBN = "999-9999999999",
BookAuthors = new List { "Author 1", "Author 2" },
Dimensions = myBookDimensions
};
context.Save(myBook);
// 2. Retrieve the book.
Book bookRetrieved = context.Load(501);
// 3. Update property (book dimensions).
bookRetrieved.Dimensions.Height += 1;
bookRetrieved.Dimensions.Length += 1;
bookRetrieved.Dimensions.Thickness += 0.2M;
// Update the book.
context.Save(bookRetrieved);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
}
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey] //Partition key
public int Id
{
get; set;
}
[DynamoDBProperty]
public string Title
{
get; set;
}
[DynamoDBProperty]
public string ISBN
{
get; set;
}
// Multi-valued (set type) attribute.
[DynamoDBProperty("Authors")]
public List BookAuthors
{
get; set;
}
// Arbitrary type, with a converter to map it to DynamoDB type.
[DynamoDBProperty(typeof(DimensionTypeConverter))]
public DimensionType Dimensions
{
get; set;
}
}
public class DimensionType
{
public decimal Length
{
get; set;
}
public decimal Height
{
get; set;
}
public decimal Thickness
{
get; set;
}
}
// Converts the complex type DimensionType to string and vice-versa.
public class DimensionTypeConverter : IPropertyConverter
{
public DynamoDBEntry ToEntry(object value)
{
DimensionType bookDimensions = value as DimensionType;
if (bookDimensions == null) throw new ArgumentOutOfRangeException();
string data = string.Format("{1}{0}{2}{0}{3}", " x ",
bookDimensions.Length, bookDimensions.Height, bookDimensions.Thickness);
DynamoDBEntry entry = new Primitive
{
Value = data
};
return entry;
}
public object FromEntry(DynamoDBEntry entry)
{
Primitive primitive = entry as Primitive;
if (primitive == null || !(primitive.Value is String) || string.IsNullOrEmpty((string)primitive.Value))
throw new ArgumentOutOfRangeException();
string[] data = ((string)(primitive.Value)).Split(new string[] { " x " }, StringSplitOptions.None);
if (data.Length != 3) throw new ArgumentOutOfRangeException();
DimensionType complexData = new DimensionType
{
Length = Convert.ToDecimal(data[0]),
Height = Convert.ToDecimal(data[1]),
Thickness = Convert.ToDecimal(data[2])
};
return complexData;
}
}
}
```