Class Item

Namespace

DynaSharp

Assembly

DynaSharp.dll

A DynamoDB item without a schema: attribute names and their values. Everything DynaSharp reads is one of these, and it goes wherever the API takes attributes, since it is an IReadOnlyDictionary<TKey, TValue>.

public sealed class Item : IReadOnlyDictionary<string, AttributeValue>, IReadOnlyCollection<KeyValuePair<string, AttributeValue>>, IEnumerable<KeyValuePair<string, AttributeValue>>, IEnumerable, IEquatable<Item>, IDynamoDbDocument<Item>

Inheritance

object

Item

Implements

IReadOnlyDictionary<string, AttributeValue>

IReadOnlyCollection<KeyValuePair<string, AttributeValue>>

IEnumerable<KeyValuePair<string, AttributeValue>>

IEnumerable

IEquatable<Item>

IDynamoDbDocument<Item>

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Examples

await shop.Put(new Item { ["pk"] = "USER#alice", ["sk"] = "PROFILE", ["name"] = "Alice" }).SendAsync(ct);

Item? profile = await shop.Get("USER#alice", "PROFILE").ItemAsync(ct);
string? name = profile?.GetString("name");

Remarks

Build one with an initializer, new Item { ["pk"] = "user-1", ["age"] = 42 }; values convert implicitly, see AttributeValue. The indexer sets or replaces an attribute, Add(string, AttributeValue) refuses a name that exists, and Remove(string) takes one out.

Read one with the indexer, which throws for a missing attribute, or with the getters such as GetString(string) and GetNumber<T>(string), which return null for a missing attribute and for the DynamoDB null value. Use ContainsKey(string) and IsNull to tell those two apart. A value of another type throws an exception that names the attribute. Exception messages never contain the value, so they are safe to log. ToString() is another matter: it prints the item.

Attributes have no order in DynamoDB. An item built by hand enumerates in insertion order; a read item enumerates in an order that can differ between items with the same attributes, so never rely on it. Equals(Item?) ignores the order and is the only sanctioned comparison; the text of ToString() does not ignore it.

Items are mutable, compare by content and change their hash with their content, so do not use them as dictionary keys or in a hash set. Writing into a read item affects that item alone, even though the items of a page share their attribute names. A map inside an item (GetMap(string)) is part of an immutable AttributeValue, so writing into it throws; copy it with Item(IEnumerable<KeyValuePair<string, AttributeValue>>), change the copy and store it with FromMap(IEnumerable<KeyValuePair<string, AttributeValue>>). Reading from several threads is safe; writing is not, as with a dictionary.

Names and values are kept in two arrays, and items read from one response or with the same attributes share the names. A read item therefore costs little more than its values, at any size. An item built by hand is cheap at the usual sizes, but above 32 attributes it costs more than a Dictionary<TKey, TValue> of known capacity, since it then has a lookup index of its own. An import job that writes large items can keep using dictionaries.

Constructors

Item()

Initializes a new instance of the Item class, without attributes.

public Item()

Item(IEnumerable<KeyValuePair<string, AttributeValue>>)

Initializes a new instance of the Item class with a copy of some attributes, in their order.

public Item(IEnumerable<KeyValuePair<string, AttributeValue>> attributes)

Parameters

attributes IEnumerable<KeyValuePair<string, AttributeValue>>

The attributes, for example another item or a dictionary. The values themselves are immutable and not copied.

Exceptions

ArgumentNullException

attributes or a name is null.

ArgumentException

A name occurs twice, or a value has None.

Item(int)

Initializes a new instance of the Item class, without attributes but with room for them.

public Item(int capacity)

Parameters

capacity int

The number of attributes to expect. The item grows beyond it.

Exceptions

ArgumentOutOfRangeException

capacity is negative.

Properties

Count

Gets the number of attributes.

public int Count { get; }

Property Value

int

this[string]

Gets or sets an attribute. Setting replaces an existing attribute or adds a new one.

public AttributeValue this[string name] { get; set; }

Parameters

name string

The attribute name, compared ordinally. DynamoDB attribute names are case sensitive.

Property Value

AttributeValue

The value.

Exceptions

ArgumentNullException

name is null.

KeyNotFoundException

Getting an attribute the item does not have. The message names the attribute.

ArgumentException

Setting a value that has None.

InvalidOperationException

Setting on a map that is part of an AttributeValue.

Keys

Gets the attribute names. The order carries no meaning for a read item.

public IEnumerable<string> Keys { get; }

Property Value

IEnumerable<string>

Values

Gets the values, in the order of Keys.

public IEnumerable<AttributeValue> Values { get; }

Property Value

IEnumerable<AttributeValue>

Methods

Add(string, AttributeValue)

Adds an attribute, so that collection initializers work too: new Item { { "pk", "user-1" } }.

public void Add(string name, AttributeValue value)

Parameters

name string

The attribute name.

value AttributeValue

The value.

Exceptions

ArgumentNullException

name is null.

ArgumentException

The item has an attribute with this name, or value has None.

InvalidOperationException

This is a map that is part of an AttributeValue.

ContainsKey(string)

Determines whether the item has an attribute, including one with the DynamoDB null value.

public bool ContainsKey(string key)

Parameters

key string

The attribute name.

Returns

bool

true if the item has the attribute.

Exceptions

ArgumentNullException

key is null.

Equals(Item?)

Compares two items by content: the same names with equal values, in any order.

public bool Equals(Item? other)

Parameters

other Item

The other item.

Returns

bool

true if both have the same content.

Equals(object?)

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

From<T>(T)

Copies a mapped value into an item, through the attributes the value would be stored with. This is how a mapped entity reaches an API that takes attributes, such as the request API.

public static Item From<T>(T value) where T : IDynamoDbDocument<T>

Parameters

value T

The value.

Returns

Item

A new item with the attributes of value, which also holds what the type adds by itself: its keys and its discriminator.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

value is null.

GetBinary(string)

Gets a binary attribute.

public ReadOnlyMemory<byte>? GetBinary(string name)

Parameters

name string

The attribute name.

Returns

ReadOnlyMemory<byte>?

The bytes, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

GetBinarySet(string)

Gets a binary set attribute.

public IReadOnlyList<ReadOnlyMemory<byte>>? GetBinarySet(string name)

Parameters

name string

The attribute name.

Returns

IReadOnlyList<ReadOnlyMemory<byte>>

The elements, in no meaningful order, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

GetBool(string)

Gets a boolean attribute.

public bool? GetBool(string name)

Parameters

name string

The attribute name.

Returns

bool?

The boolean, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

GetEnumerator()

Gets an enumerator over the attributes.

public Item.Enumerator GetEnumerator()

Returns

Item.Enumerator

The enumerator.

GetHashCode()

Gets a hash of the content that does not depend on the order, and changes when the item does.

public override int GetHashCode()

Returns

int

The hash.

GetList(string)

Gets a list attribute.

public IReadOnlyList<AttributeValue>? GetList(string name)

Parameters

name string

The attribute name.

Returns

IReadOnlyList<AttributeValue>

The elements in order, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

GetMap(string)

Gets a map attribute as a read-only Item, for nested access such as item.GetMap("address")?.GetString("city"). It compiles like any item, but writing into it throws InvalidOperationException: copy it with Item(IEnumerable<KeyValuePair<string, AttributeValue>>), change the copy and store that.

public Item? GetMap(string name)

Parameters

name string

The attribute name. A dot has no special meaning: attribute names may contain dots.

Returns

Item

The map, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

GetNumberSet(string)

Gets a number set attribute as text, which keeps numbers beyond the range or precision of .NET types.

public IReadOnlyList<string>? GetNumberSet(string name)

Parameters

name string

The attribute name.

Returns

IReadOnlyList<string>

The elements, in no meaningful order, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

GetNumber<T>(string)

Gets a number attribute, parsed with the invariant culture.

public T? GetNumber<T>(string name) where T : struct, INumberBase<T>

Parameters

name string

The attribute name.

Returns

T?

The number, or null if the attribute is missing or has the DynamoDB null value. Exponent notation such as 1E+2 is accepted, also for integer types.

Type Parameters

T

The target number type, for example int or decimal.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

FormatException

The text cannot be represented as T. The message names the attribute, not the text.

OverflowException

The number is outside the range of T, has a fractional part and T is an integer type, or T is decimal and cannot hold its exact value, which takes 28 to 29 significant digits at most, where DynamoDB has 38. A binary floating-point type counts a number that rounds to infinity, and NaN, as out of range; it rounds any other number to the nearest value it holds, and one below its range reads as 0. The message names the attribute, not the number.

GetString(string)

Gets a string attribute.

public string? GetString(string name)

Parameters

name string

The attribute name.

Returns

string

The string, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

GetStringSet(string)

Gets a string set attribute.

public IReadOnlyList<string>? GetStringSet(string name)

Parameters

name string

The attribute name.

Returns

IReadOnlyList<string>

The elements, in no meaningful order, or null if the attribute is missing or has the DynamoDB null value.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

The attribute has another type. The message names the attribute.

Is<T>()

Gets whether the item is of an entity: its discriminator attribute, _type or the AttributeName the type names, holds the type's discriminator value. It is the test a mixed read sorts items by, for an item that is already read, such as an image of a stream record from a table of several entities: if (image.Is<Order>()) { var order = image.To<Order>(); }.

public bool Is<T>() where T : IDynamoDbDiscriminated<T>

Returns

bool

true if the item holds the discriminator of T.

Type Parameters

T

The entity. One without a discriminator, with [Discriminator(OptOut = true)], does not compile, because nothing in its items tells them from others.

Remarks

It looks at that one attribute and reads nothing else, so an item that says it is a T can still fail To<T>() on another attribute. The comparison is ordinal. An item without the attribute, with the DynamoDB null value there or with a value that is not a string is not of the type, as it is of no type to a mixed read.

Exceptions

ArgumentException

T is written by hand and claims a discriminator that its DynaSharp.Mapping.DynamoDbEntityInfo does not have.

Remove(string)

Removes an attribute. The others keep their order.

public bool Remove(string name)

Parameters

name string

The attribute name.

Returns

bool

true if the item had the attribute.

Exceptions

ArgumentNullException

name is null.

InvalidOperationException

This is a map that is part of an AttributeValue.

ToString()

Returns the item in DynamoDB JSON, for example {"pk":{"S":"a"},"n":{"N":"1"}}. It contains the data of the item, so do not log it where that is a concern.

public override string ToString()

Returns

string

The DynamoDB JSON text, with U+FFFD for a lone surrogate, which no write takes.

To<T>()

Reads the item as a mapped value, the way a response carrying these attributes is read.

public T To<T>() where T : IDynamoDbDocument<T>

Returns

T

The value.

Type Parameters

T

The type to read.

Exceptions

DynamoDbMappingException

An attribute is missing or cannot be converted, or the item is of another type.

TryGetValue(string, out AttributeValue)

Gets an attribute if the item has it.

public bool TryGetValue(string key, out AttributeValue value)

Parameters

key string

The attribute name.

value AttributeValue

The value, or default if the item does not have the attribute.

Returns

bool

true if the item has the attribute.

Exceptions

ArgumentNullException

key is null.