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 the UseDefaultConverters property to false.

Type: List<IDynamoAttributeConverter>

Default: empty list

IgnoreNullValues

The IgnoreNullValues property controls if null 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 causes DynamoSerializer to ignore a property on a class.
DynamoPropertyName(string Name): The DynamoPropertyName attribute changes the name used by DynamoSerializer when serializing the property.

class MyRecord {

    //--- Properties ---

    [DynamoPropertyIgnore]
    public string IgnoreMe { get; set; }

    [DynamoPropertyName("NewName")]
    public string RenameMe { get; set; }
}