Struct DeleteCommand<T>

Namespace

DynaSharp

Assembly

DynaSharp.dll

A DeleteItem under construction. Deleting what does not exist is no error unless IfExists() asks for one. Chain the options and end with SendAsync(CancellationToken) in one expression.

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

Type Parameters

T

How the returned item is read.

Implements

IConditional<DeleteCommand<T>>

IRetryable<DeleteCommand<T>>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Examples

var deleted = await orders.Delete(Order.Keys.Of("alice", 1)).ReturnOld().SendAsync(ct);
if (!deleted.HasItem)
{
    Console.WriteLine("There was no such order.");
}

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. An interpolated Attr stands for an attribute name and any other interpolated value for a value. The delete happens only if the condition holds, and a second condition means both must hold.

public DeleteCommand<T> If(ExpressionHandler condition)

Parameters

condition ExpressionHandler

The condition.

Returns

DeleteCommand<T>

The command, which replaces this one.

IfExists()

Deletes only if an item has this key (attribute_exists on the partition key), so that a missing item fails. With Allow, version 0 asks for an item that reads as 0 besides. Otherwise version 0, of an entity or of IfVersion(0), says that no item has the key, so with it SendAsync throws InvalidOperationException, unless IgnoreVersion() took the version of the entity back.

public DeleteCommand<T> IfExists()

Returns

DeleteCommand<T>

The command, which replaces this one.

If<TCondition>(TCondition)

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

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

Parameters

condition TCondition

The condition.

Returns

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

Parameters

attempts int

The number of attempts.

Returns

DeleteCommand<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 DeleteCommand<T> ReturnCapacity(ReturnConsumedCapacity detail = ReturnConsumedCapacity.Total)

Parameters

detail ReturnConsumedCapacity

How much detail to return.

Returns

DeleteCommand<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 DeleteCommand<T> ReturnMetrics()

Returns

DeleteCommand<T>

The command, which replaces this one.

ReturnOld()

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

public DeleteCommand<T> ReturnOld()

Returns

DeleteCommand<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 DeleteCommand<T> ReturnOldOnFailure()

Returns

DeleteCommand<T>

The command, which replaces this one.

SendAsync(CancellationToken)

Sends the command. A retry repeats the delete, which is safe unless ReturnOld() or a condition depends on the first one having failed.

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, a delete by key of an entity with a VersionAttribute has neither IfVersion nor IgnoreVersion, or version 0 stands beside IfExists() without Allow.

ObjectDisposedException

The client is disposed.

ConditionalCheckFailedException

A condition did not hold, so nothing was deleted.

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 delete 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 key and the values.

public string ToRequestJson()

Returns

string

The request body.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered.

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 deleted, 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 delete 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, a delete by key of an entity with a VersionAttribute has neither IfVersion nor IgnoreVersion, or version 0 stands beside IfExists() 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 delete has happened only in the first case.

DynamoDbException

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