Struct PutCommand<T>

Namespace

DynaSharp

Assembly

DynaSharp.dll

A PutItem under construction, which replaces the whole item under its key. Chain the options and end with SendAsync(CancellationToken) in one expression.

public readonly ref struct PutCommand<T> : IConditional<PutCommand<T>>, IRetryable<PutCommand<T>> where T : IDynamoDbDocument<T>

Type Parameters

T

How the item is written and read.

Implements

IConditional<PutCommand<T>>

IRetryable<PutCommand<T>>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Examples

await orders.Put(order).IfNotExists().SendAsync(ct);

var replaced = await orders.Put(order).ReturnOld().SendAsync(ct);

Remarks

See GetCommand<T> for what a command is and what it cannot do.

Methods

If(ExpressionHandler)

Adds a condition in the grammar of DynamoDB, for what the conditions of handles do not cover: .If($"attribute_exists({Attr("pk")}) AND size({Attr("tags")}) < {10}"). An interpolated Attr stands for an attribute name and any other interpolated value for a value. The put happens only if the condition holds, and a second condition means both must hold.

public PutCommand<T> If(ExpressionHandler condition)

Parameters

condition ExpressionHandler

The condition.

Returns

PutCommand<T>

The command, which replaces this one.

IfExists()

Puts only if an item has this key (attribute_exists on the partition key), which makes it a replacement that creates nothing. With Allow, version 0 asks for an item that reads as 0 besides. Otherwise an entity with a VersionAttribute at version 0 says that no item has the key, so SendAsync throws InvalidOperationException for it, unless IgnoreVersion() was called.

public PutCommand<T> IfExists()

Returns

PutCommand<T>

The command, which replaces this one.

IfNotExists()

Puts only if no item has this key (attribute_not_exists on the partition key), which turns the replacing put into a create. An entity with a VersionAttribute must then hold version 0, whose condition is this one and renders once, also with Allow, where this alone says that the key is free. No item can lack its key and hold a version, so SendAsync throws InvalidOperationException for any other, unless IgnoreVersion() was called.

public PutCommand<T> IfNotExists()

Returns

PutCommand<T>

The command, which replaces this one.

If<TCondition>(TCondition)

Adds a condition. The put happens only if it holds, and a second condition means both must hold.

public PutCommand<T> If<TCondition>(TCondition condition) where TCondition : ICondition

Parameters

condition TCondition

The condition.

Returns

PutCommand<T>

The command, which replaces this one.

Type Parameters

TCondition

The type of the condition.

Exceptions

ArgumentNullException

condition is null.

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 PutCommand<T> MaxAttempts(int attempts)

Parameters

attempts int

The number of attempts.

Returns

PutCommand<T>

The command, which replaces this one.

Exceptions

ArgumentOutOfRangeException

attempts is below 1.

ReturnCapacity(ReturnConsumedCapacity)

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

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

Parameters

detail ReturnConsumedCapacity

How much detail to return.

Returns

PutCommand<T>

The command, which replaces this one.

ReturnMetrics()

Asks for the size estimate of the item collection, which goes to ItemCollectionMetrics. DynamoDB has it for tables with a local secondary index.

public PutCommand<T> ReturnMetrics()

Returns

PutCommand<T>

The command, which replaces this one.

ReturnOld()

Returns the item this put replaced in Item (ALL_OLD). There is none if no item had the key.

public PutCommand<T> ReturnOld()

Returns

PutCommand<T>

The command, which replaces this one.

ReturnOldOnFailure()

Puts the existing item on Item when a condition fails, or on Item with TrySendAsync(CancellationToken), which saves a read to find out why. It costs no extra capacity.

public PutCommand<T> ReturnOldOnFailure()

Returns

PutCommand<T>

The command, which replaces this one.

SendAsync(CancellationToken)

Sends the command. A retry repeats the same put, which is safe unless ReturnOld() or a condition depends on the first one having failed: after a lost response the retry finds the item the first one wrote, so IfNotExists() fails, ReturnOld() returns that item, and IfExists() or an If judges it instead of what was there before. For an entity with a VersionAttribute the same goes: the retry finds the version it wrote and fails its own condition.

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

Parameters

cancellationToken CancellationToken

Cancels the call.

Returns

ValueTask<WriteResult<T>>

The result. Await it once.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered, or it asks for IfNotExists() of an entity with a version above 0 or for IfExists() of one at version 0 without Allow.

ObjectDisposedException

The client is disposed.

ConditionalCheckFailedException

A condition did not hold, so nothing was written.

ValidationException

DynamoDB rejects the request; the exception shows the expressions.

ResourceNotFoundException

The table does not exist.

DynamoDbMappingException

The returned item cannot be read as T. The write has happened.

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 item.

public string ToRequestJson()

Returns

string

The request body.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered, or it asks for IfNotExists() of an entity with a version above 0 or for IfExists() of one at version 0 without Allow.

TrySendAsync(CancellationToken)

Sends the command as SendAsync(CancellationToken) does, and takes a failed condition as an answer instead of throwing ConditionalCheckFailedException: ConditionMet is then false, nothing was written, and with ReturnOldOnFailure() Item is the item the condition saw. It is for a write whose failed condition is routine, such as an event that is old news, and no exception is thrown for it.

public ValueTask<WriteResult<T>> TrySendAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels the call.

Returns

ValueTask<WriteResult<T>>

The result. Await it once.

Remarks

The request is the one SendAsync(CancellationToken) sends, and every other error throws as there. ReturnOldOnFailure() stays a choice: without it a failed condition gives no item. ReturnOld() gives nothing on a failed condition, because DynamoDB returns nothing then.

A retry of the client after a lost response meets what its first attempt wrote, and a condition that rules out the write's own result then fails. That is the same answer a second delivery of the same change gets, and on the wire the two cannot be told apart, so ConditionMet does not say which. Compare the item of ReturnOldOnFailure() with what the put sent: the same version or time means that the change is stored, by this call or an earlier one.

Inside RetryOnConflictAsync a failed condition of this method is no conflict, so the delegate does not run again. The span of a failed condition is no error, and carries dynasharp.condition_met = false.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered, or it asks for IfNotExists() of an entity with a version above 0 or for IfExists() of one at version 0 without Allow.

ObjectDisposedException

The client is disposed.

ValidationException

DynamoDB rejects the request; the exception shows the expressions.

ResourceNotFoundException

The table does not exist.

DynamoDbMappingException

The returned item, or the item a failed condition saw, cannot be read as T. The write has happened only in the first case.

DynamoDbException

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