Serialization for DynamoDB
DynamoDB uses its own document model for serializing data structures, which looks similar to JSON. The LambdaSharp.DynamoDB.Serialization library is modeled after other serialization libraries, such as System.Text.Json.JsonSerializer to streamline conversions between .NET types and DynamoDB documents.
Serialization
Serializing a .NET type instance is straightforward using DynamoSerialize.Serialize<T>(T record)
.
NOTE: Serialize()
will return null
when the state of the type being serialized is not supported by DynamoDB. For example, an empty HashSet<string>
returns null
.
Example:
using LambdaSharp.DynamoDB.Serialization;
var serialized = DynamoSerializer.Serialize(new {
Active = true,
Binary = Encoding.UTF8.GetBytes("Bye"),
Name = "John Doe",
Age = 42,
MixedList = new object[] {
new {
Message = "Hello"
},
"World!"
},
Dictionary = new Dictionary<string, object> {
["Key"] = "Value"
},
StringSet = new[] { "Red", "Blue" }.ToHashSet(),
NumberSet = new[] { 123, 456 }.ToHashSet(),
BinarySet = new[] {
Encoding.UTF8.GetBytes("Good"),
Encoding.UTF8.GetBytes("Day")
}.ToHashSet(ByteArrayEqualityComparer.Instance)
});
DynamoDB Output:
{
"M": {
"Active": { "BOOL": true },
"Binary": { "B": "Qnll" },
"Name": { "S": "John Doe" },
"Age": { "N": "42" },
"MixedList": {
"L": [
{
"M": {
"Message": { "S": "Hello" }
}
},
{ "S": "World!" }
]
},
"Dictionary": {
"M": {
"Key": { "S": "Value" }
}
},
"StringSet": {
"SS": [ "Red", "Blue" ]
},
"NumberSet": {
"NS": [ "123", "456" ]
},
"BinarySet": {
"BS": [ "R29vZA==", "RGF5" ]
}
}
}
Deserialization
Deserializing a DynamoDB document is straightforward using DynamoSerialize.Deserialize<T>(Dictionary<string, AttributeValue> document)
.
NOTE: Deserialize()
will return null
when deserialized the NULL
attribute value.
NOTE: Deserialize()
may throw DynamoSerializationException
when an issue occurs during deserialization.
Serializer Options
The behavior of DynamoSerialize.Serialize<T>(...)
and DynamoSerialize.Deserialize<T>(...)
can be modified by supplying an instance of DynamoSerializerOptions
as a second parameter.
NOTE: It is recommended to create and share a single instance DynamoSerializerOptions
.
Properties
The DynamoSerializerOptions
has the following properties.
Converters
-
The
Converters
property lists additional custom converters to use when (de)serializing values. Custom converters take precedence over default converters. Default converters can be disabled entirely by setting theUseDefaultConverters
property tofalse
.Type:
List<IDynamoAttributeConverter>
Default: empty list
IgnoreNullValues
-
The
IgnoreNullValues
property controls ifnull
values are serialized as DynamoDB NULL attribute values or skipped.Type:
bool
Default:
true
UseDefaultConverters
-
The
UseDefaultConverters
property controls if the default DynamoDB converters are enabled.Type:
bool
Default:
true
The default converters are:
DynamoBoolConverter
DynamoIntConverter
DynamoLongConverter
DynamoDoubleConverter
DynamoDateTimeOffsetConverter
DynamoDecimalConverter
DynamoStringConverter
DynamoEnumConverter
DynamoByteArrayConverter
DynamoISetByteArrayConverter
DynamoISetStringConverter
DynamoISetIntConverter
DynamoISetLongConverter
DynamoISetDoubleConverter
DynamoISetDecimalConverter
DynamoIDictionaryConverter
DynamoListConverter
DynamoJsonElementConverter
DynamoObjectConverter
Serialization Attributes for DynamoDB
By default, all public properties of a class are (de)serialized by DynamoSerializer
using the property name. However, this behavior can modified by annotating the properties with the following attributes.
DynamoPropertyIgnore
-
The
DynamoPropertyIgnore
attribute causesDynamoSerializer
to ignore a property on a class. DynamoPropertyName(string Name)
-
The
DynamoPropertyName
attribute changes the name used byDynamoSerializer
when serializing the property.
class MyRecord {
//--- Properties ---
[DynamoPropertyIgnore]
public string IgnoreMe { get; set; }
[DynamoPropertyName("NewName")]
public string RenameMe { get; set; }
}