Table of Contents

Struct DynamoDbWriter

Namespace
DynaSharp.Serialization
Assembly
DynaSharp.dll

Writes DynamoDB JSON: attribute values in their typed form, such as {"S":"abc"} or {"N":"42"}, and items, which are JSON objects that map attribute names to attribute values.

public readonly ref struct DynamoDbWriter
Inherited Members

Remarks

This is the only code that produces DynamoDB JSON. AttributeValue, entities mapped by the source generator and custom converters (IDynamoDbConverter<T>) all write through it, so each rule of the format is implemented once: numbers travel as text, binary values as base64, null as {"NULL":true}.

Each method that writes a value writes one complete attribute value, type descriptor included. Inside a map or an item, write the attribute name first; inside a list, write the values one after another. Lists, maps, sets and items are written with matching start and end calls: 

writer.WriteStartItem();
writer.WriteAttributeName("pk"u8);
writer.WriteString("USER#42");
writer.WriteAttributeName("roles"u8);
writer.WriteStartStringSet();
writer.WriteStringSetElement("admin");
writer.WriteEndSet();
writer.WriteEndItem();
// {"pk":{"S":"USER#42"},"roles":{"SS":["admin"]}}

Calls that break the JSON structure, such as a value inside a map without an attribute name, throw InvalidOperationException. DynamoDB rules beyond the JSON structure are enforced by DynamoDB, which rejects the request with a validation error: for example an empty set, a set with duplicates, or an item larger than 400 KB.

Constructors

DynamoDbWriter(Utf8JsonWriter)

Initializes a new instance of the DynamoDbWriter struct over a JSON writer. DynaSharp creates writers for its own requests; use this to test a custom converter. Flush or dispose json before reading its output.

public DynamoDbWriter(Utf8JsonWriter json)

Parameters

json Utf8JsonWriter

The destination.

Exceptions

ArgumentNullException

json is null.

Methods

WriteAttributeName(ReadOnlySpan<byte>)

Writes the name of the next attribute in a map or item.

public void WriteAttributeName(ReadOnlySpan<byte> utf8Name)

Parameters

utf8Name ReadOnlySpan<byte>

The attribute name as UTF-8, typically a literal such as "pk"u8.

WriteAttributeName(string)

Writes the name of the next attribute in a map or item.

public void WriteAttributeName(string name)

Parameters

name string

The attribute name.

Exceptions

ArgumentNullException

name is null.

ArgumentException

name holds a lone surrogate, which is not text.

WriteBinary(ReadOnlySpan<byte>)

Writes a binary value, {"B":"..."}, encoded as base64.

public void WriteBinary(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The bytes, possibly none (allowed except in key attributes).

WriteBinarySetElement(ReadOnlySpan<byte>)

Writes an element of a binary set, encoded as base64.

public void WriteBinarySetElement(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The bytes.

WriteBool(bool)

Writes a boolean value, {"BOOL":true} or {"BOOL":false}.

public void WriteBool(bool value)

Parameters

value bool

The boolean.

WriteEndItem()

Ends an item started with WriteStartItem().

public void WriteEndItem()

WriteEndList()

Ends a list value started with WriteStartList().

public void WriteEndList()

WriteEndMap()

Ends a map value started with WriteStartMap().

public void WriteEndMap()

WriteEndSet()

Ends a set started with WriteStartStringSet(), WriteStartNumberSet() or WriteStartBinarySet().

public void WriteEndSet()

WriteNull()

Writes the null value, {"NULL":true}.

public void WriteNull()

Remarks

An attribute with the null value exists in the item; it is not the same as a missing attribute. To leave an attribute out, do not write it at all.

WriteNumber(string)

Writes a number value, {"N":"..."}, from its textual representation, sent unchanged.

public void WriteNumber(string value)

Parameters

value string

The number as text, for example "42" or "-1.5E-10". DynamoDB validates the format.

Exceptions

ArgumentNullException

value is null.

ArgumentException

value is empty.

WriteNumberSetElement(string)

Writes an element of a number set from its textual representation, sent unchanged.

public void WriteNumberSetElement(string value)

Parameters

value string

The number as text. DynamoDB validates the format.

Exceptions

ArgumentNullException

value is null.

ArgumentException

value is empty.

WriteNumberSetElement<T>(T)

Writes an element of a number set, formatted with the invariant culture.

public void WriteNumberSetElement<T>(T value) where T : INumberBase<T>

Parameters

value T

The number.

Type Parameters

T

Any .NET number type.

Exceptions

ArgumentOutOfRangeException

value is NaN or infinite; DynamoDB cannot store either.

ArgumentException

T is char, which is text: it belongs in a string set.

WriteNumber<T>(T)

Writes a number value, {"N":"..."}, formatted with the invariant culture. A char counts as a number type in .NET but not here: it is written as the string value it is, as everywhere in DynaSharp.

public void WriteNumber<T>(T value) where T : INumberBase<T>

Parameters

value T

The number. DynamoDB stores up to 38 significant digits, with a magnitude of zero or from 1E-130 to 9.9999999999999999999999999999999999999E+125. It rejects anything else with a validation error; a double can be outside that range.

Type Parameters

T

Any .NET number type, for example int, decimal or double.

Exceptions

ArgumentOutOfRangeException

value is NaN or infinite; DynamoDB cannot store either.

WriteStartBinarySet()

Starts a binary set, {"BS":[. Write the elements with WriteBinarySetElement(ReadOnlySpan<byte>), then call WriteEndSet().

public void WriteStartBinarySet()

Remarks

DynamoDB rejects empty sets and sets with duplicates. Write a set attribute only if it has elements.

WriteStartItem()

Starts an item: a plain JSON object of attribute names and values, as used for Item or Key in requests. Unlike a map, it has no type descriptor. Call WriteEndItem() at the end.

public void WriteStartItem()

WriteStartList()

Starts a list value, {"L":[. Write the elements as values, then call WriteEndList().

public void WriteStartList()

Remarks

Elements may have different types. Empty lists are allowed.

WriteStartMap()

Starts a map value, {"M":{. Write attribute names and values, then call WriteEndMap().

public void WriteStartMap()

Remarks

Empty maps are allowed. Attribute names must be unique within the map.

WriteStartNumberSet()

Starts a number set, {"NS":[. Write the elements with WriteNumberSetElement<T>(T) or WriteNumberSetElement(string), then call WriteEndSet().

public void WriteStartNumberSet()

Remarks

DynamoDB rejects empty sets and sets with numerically equal elements. Write a set attribute only if it has elements.

WriteStartStringSet()

Starts a string set, {"SS":[. Write the elements with WriteStringSetElement(string), then call WriteEndSet().

public void WriteStartStringSet()

Remarks

DynamoDB rejects empty sets and sets with duplicates. Write a set attribute only if it has elements.

WriteString(ReadOnlySpan<byte>)

Writes a string value, {"S":"..."}, from UTF-8 text, for example formatted into a stack buffer.

public void WriteString(ReadOnlySpan<byte> utf8Value)

Parameters

utf8Value ReadOnlySpan<byte>

The string as UTF-8. Invalid UTF-8 sequences are replaced with U+FFFD.

WriteString(string)

Writes a string value, {"S":"..."}.

public void WriteString(string value)

Parameters

value string

The string. Empty strings are allowed except in key attributes, which DynamoDB validates.

Exceptions

ArgumentNullException

value is null; write WriteNull() instead.

ArgumentException

value holds a lone surrogate, which is not text, and would otherwise be stored as U+FFFD.

WriteStringSetElement(ReadOnlySpan<byte>)

Writes an element of a string set from UTF-8 bytes, without a transcoding step: a plain JSON string without type descriptor.

public void WriteStringSetElement(ReadOnlySpan<byte> utf8Value)

Parameters

utf8Value ReadOnlySpan<byte>

The string as UTF-8.

WriteStringSetElement(string)

Writes an element of a string set: a plain JSON string without type descriptor.

public void WriteStringSetElement(string value)

Parameters

value string

The string.

Exceptions

ArgumentNullException

value is null.

ArgumentException

value holds a lone surrogate, which is not text, and would otherwise be stored as U+FFFD.