Struct GetCommand<T>

Namespace

DynaSharp

Assembly

DynaSharp.dll

A GetItem under construction. Chain the options and end with ItemAsync(CancellationToken) or SendAsync(CancellationToken) in one expression.

public readonly ref struct GetCommand<T> : IRetryable<GetCommand<T>> where T : IDynamoDbDocument<T>

Type Parameters

T

How the item is read.

Implements

IRetryable<GetCommand<T>>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Examples

Order? order = await orders.Get(Order.Keys.Of("alice", 1)).ItemAsync(ct);

var result = await orders.Get(Order.Keys.Of("alice", 1)).Consistent().SendAsync(ct);
if (result.Found)
{
    Console.WriteLine(result.Item!.Total);
}

Remarks

Build and send in one expression. A command is a ref struct: the compiler keeps it from being stored in a field, captured in a lambda or kept across an await. Compute values first, or put the chain into a method that returns the command.

Each call uses the command up. Every clause returns a new command and the one it was called on is spent, so reusing a command throws InvalidOperationException. To send the same request twice, build it twice.

Methods

Consistent()

Asks for a strongly consistent read, which sees every write that succeeded before it and costs twice the capacity. A read is eventually consistent otherwise, and can miss a very recent write.

public GetCommand<T> Consistent()

Returns

GetCommand<T>

The command, which replaces this one.

ItemAsync(CancellationToken)

Sends the command and returns the item, or null if none has the key: var order = await orders.Get(key).ItemAsync(ct);. It is the same request as SendAsync(CancellationToken), which stays for Found and the capacity. An entity that is a struct reads as its default value when there is no item, so only Found tells a miss from an item of default values.

public ValueTask<T?> ItemAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels the call.

Returns

ValueTask<T>

The item. Await it once.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered.

ObjectDisposedException

The client is disposed.

ValidationException

DynamoDB rejects the request, for example because the key does not fit the table.

ResourceNotFoundException

The table does not exist.

DynamoDbMappingException

The item cannot be read as T.

DynamoDbException

DynamoDB returns any other error; a throttling or server error only after the last attempt.

MaxAttempts(int)

Sets the number of attempts of this call including the first, in place of MaxAttempts. A retry after a lost response repeats a write that may have been applied, so 1 makes an ADD count at most once, and a lost response then reports a failure after the write was applied.

public GetCommand<T> MaxAttempts(int attempts)

Parameters

attempts int

The number of attempts.

Returns

GetCommand<T>

The command, which replaces this one.

Exceptions

ArgumentOutOfRangeException

attempts is below 1.

Project(params ReadOnlySpan<Attr>)

Reads only some attributes, given as handles: Project(Order.Attrs.Status, Order.Attrs.Total). See Project(params ReadOnlySpan<string>).

public GetCommand<T> Project(params ReadOnlySpan<Attr> attributes)

Parameters

attributes ReadOnlySpan<Attr>

The attributes. A second call adds to the first.

Returns

GetCommand<T>

The command, which replaces this one.

Exceptions

ArgumentException

A path is not valid.

Project(params ReadOnlySpan<string>)

Reads only some attributes. It saves bandwidth, not capacity: DynamoDB charges for the whole item. A read of an entity needs its discriminator and its keys, so they join the projection on their own, and it needs whatever else the entity requires, so a projection is mostly for Item.

public GetCommand<T> Project(params ReadOnlySpan<string> paths)

Parameters

paths ReadOnlySpan<string>

The names or document paths. Reserved words need no care, and a second call adds to the first.

Returns

GetCommand<T>

The command, which replaces this one.

Exceptions

ArgumentException

A path is not valid.

ReturnCapacity(ReturnConsumedCapacity)

Asks for the consumed capacity, which goes to ConsumedCapacity and the capacity metric.

public GetCommand<T> ReturnCapacity(ReturnConsumedCapacity detail = ReturnConsumedCapacity.Total)

Parameters

detail ReturnConsumedCapacity

How much detail to return.

Returns

GetCommand<T>

The command, which replaces this one.

Select<TValue, TConverter>(Attr<TValue, NullableHandleConverter<TValue, TConverter>>)

Reads one nullable attribute instead of the entity, which gives null for an item without it. See Select<TValue, TConverter>(Attr<TValue, TConverter>).

public GetSelectCommand<TValue?, NullableConverter<TValue, TConverter>> Select<TValue, TConverter>(Attr<TValue, NullableHandleConverter<TValue, TConverter>> attribute) where TValue : struct where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, NullableHandleConverter<TValue, TConverter>>

The attribute, a name or a path through maps.

Returns

GetSelectCommand<TValue?, NullableConverter<TValue, TConverter>>

The command that is left.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter of the attribute.

Exceptions

ArgumentException

The handle is a default value, its path has a list index, or it is not valid.

InvalidOperationException

The read has a Project, which has nothing to add here.

Select<TValue, TConverter>(Attr<TValue, NullableReferenceHandleConverter<TValue, TConverter>>)

Reads one nullable attribute instead of the entity, which gives null for an item without it. See Select<TValue, TConverter>(Attr<TValue, TConverter>).

public GetSelectCommand<TValue?, NullableReferenceConverter<TValue, TConverter>> Select<TValue, TConverter>(Attr<TValue, NullableReferenceHandleConverter<TValue, TConverter>> attribute) where TValue : class where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, NullableReferenceHandleConverter<TValue, TConverter>>

The attribute, a name or a path through maps.

Returns

GetSelectCommand<TValue, NullableReferenceConverter<TValue, TConverter>>

The command that is left.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter of the attribute.

Exceptions

ArgumentException

The handle is a default value, its path has a list index, or it is not valid.

InvalidOperationException

The read has a Project, which has nothing to add here.

Select<TValue, TConverter>(Attr<TValue, TConverter>)

Reads one attribute instead of the whole entity: var total = await orders.Get(key).Select(Order.Attrs.Total).SendAsync(ct);. It saves bandwidth, not capacity: DynamoDB charges for the whole item.

public GetSelectCommand<TValue, TConverter> Select<TValue, TConverter>(Attr<TValue, TConverter> attribute) where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute, a name or a path through maps. A list element cannot be read: DynamoDB returns a shortened list, in which its position is not known.

Returns

GetSelectCommand<TValue, TConverter>

The command that is left.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter of the attribute.

Remarks

Over Project. The result is the value and no entity, so a required member cannot be in the way. The discriminator of an entity is projected too, so an item of another type is told apart as a read of the entity does.

Last clause. After Select only the send is left, as after Return: Consistent(), ReturnCapacity(ReturnConsumedCapacity) and MaxAttempts(int) come before this, a second Select and a Project after it do not compile, and a Project before it throws.

A missing attribute follows the type of the handle: null for one of a nullable property, an empty set for a set, because DynamoDB has none, and otherwise a DynamoDbMappingException. Never a default, and that is where this differs from a read of the entity, which leaves a property that is not required at its initial value: an int without its attribute is 0 there and throws here, and so does a [Version] on an item without one, which code of another kind writes, with a message that points at VersionMissing.Allow. In a nested path the last handle decides, so ShipTo.At(Address.Attrs.City) throws for an item without ShipTo when City cannot be null, which reading ShipTo itself would not.

A key input. A [KeyOnly] property has no attribute and no handle. A stored property that a key of the table holds has both, and an item that an update created has only the key: a read of the entity restores the property from it, and this throws, which DYNA209 reports.

Exceptions

ArgumentException

The handle is a default value, its path has a list index, or it is not valid.

InvalidOperationException

The read has a Project, which has nothing to add here.

SendAsync(CancellationToken)

Sends the command. A missing item is not an error: Found is false.

public ValueTask<GetResult<T>> SendAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels the call.

Returns

ValueTask<GetResult<T>>

The result. Await it once.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered.

ObjectDisposedException

The client is disposed.

ValidationException

DynamoDB rejects the request, for example because the key does not fit the table.

ResourceNotFoundException

The table does not exist.

DynamoDbMappingException

The item cannot be read as T.

DynamoDbException

DynamoDB returns any other error; a throttling or server error only after the last attempt.

ToRequestJson()

Renders the body this command would send, as DynamoDB JSON, without sending it. It ends the command, and is meant for tests and debugging. The text contains the key and the values.

public string ToRequestJson()

Returns

string

The request body.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered.