LambdaSharp.DynamoDB.Serialization 1.0.0

dotnet add package LambdaSharp.DynamoDB.Serialization --version 1.0.0
NuGet\Install-Package LambdaSharp.DynamoDB.Serialization -Version 1.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="LambdaSharp.DynamoDB.Serialization" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add LambdaSharp.DynamoDB.Serialization --version 1.0.0
#r "nuget: LambdaSharp.DynamoDB.Serialization, 1.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install LambdaSharp.DynamoDB.Serialization as a Cake Addin
#addin nuget:?package=LambdaSharp.DynamoDB.Serialization&version=1.0.0

// Install LambdaSharp.DynamoDB.Serialization as a Cake Tool
#tool nuget:?package=LambdaSharp.DynamoDB.Serialization&version=1.0.0

LambdaSharp.DynamoDB.Serialization

This package contains interfaces and classes used for serializing data structures to AttributeValue instances used by Amazon DynamoDB. The LambdaSharp.DynamoDB.Serialization package is modeled after other serialization libraries, such as System.Text.Json.JsonSerializer to streamline conversions between .NET types and DynamoDB documents.

Visit LambdaSharp.NET to learn more about building serverless .NET solutions on AWS.

Serialization

Serializing a .NET type instance is straightforward using DynamoSerialize.Serialize<T>(T item).

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.

<dl>

<dt><code>Converters</code></dt> <dd>

The <code>Converters</code> 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 <code>UseDefaultConverters</code> property to <code>false</code>.

<em>Type:</em> <code>List<IDynamoAttributeConverter></code>

<em>Default:</em> empty list

</dd>

<dt><code>IgnoreNullValues</code></dt> <dd>

The <code>IgnoreNullValues</code> property controls if <code>null</code> values are serialized as DynamoDB NULL attribute values or skipped.

<em>Type:</em> <code>bool</code>

<em>Default:</em> <code>true</code>

</dd>

<dt><code>UseDefaultConverters</code></dt> <dd>

The <code>UseDefaultConverters</code> property controls if the default DynamoDB converters are enabled.

<em>Type:</em> <code>bool</code>

<em>Default:</em> <code>true</code>

The default converters are:

  • DynamoBoolConverter
  • DynamoIntConverter
  • DynamoLongConverter
  • DynamoDoubleConverter
  • DynamoDateTimeOffsetConverter
  • DynamoFloatConverter
  • DynamoDecimalConverter
  • DynamoStringConverter
  • DynamoEnumConverter
  • DynamoByteArrayConverter
  • DynamoISetByteArrayConverter
  • DynamoISetStringConverter
  • DynamoISetIntConverter
  • DynamoISetLongConverter
  • DynamoISetDoubleConverter
  • DynamoISetDecimalConverter
  • DynamoIDictionaryConverter
  • DynamoListConverter
  • DynamoJsonElementConverter
  • DynamoObjectConverter

</dd>

</dl>

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.

<dl>

<dt><code>DynamoPropertyIgnore</code></dt> <dd>

The <code>DynamoPropertyIgnore</code> attribute causes <code>DynamoSerializer</code> to ignore a property on a class.

</dd>

<dt><code>DynamoPropertyName(string Name)</code></dt> <dd>

The <code>DynamoPropertyName</code> attribute changes the name used by <code>DynamoSerializer</code> when serializing the property.

</dd>

</dl>

class MyRecord {

    //--- Properties ---

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

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

License

Copyright (c) 2018-2022 LambdaSharp (λ#)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.1 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on LambdaSharp.DynamoDB.Serialization:

Package Downloads
LambdaSharp.DynamoDB.Native

Serverless .NET for AWS - DynamoDB Native Library

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0 7,362 5/22/2022
0.8.4 1,722 3/10/2022
0.8.3.5 604 3/4/2022
0.8.3.4 410 7/15/2021
0.8.3.3 12,982 7/15/2021