Class TransactWriteExtensions

Namespace

DynaSharp

Assembly

DynaSharp.dll

The verbs of a transaction: what starts the next action after TransactWriteCommand and after every step, what all steps share, and the send. They are extension methods because they are the same on each of them.

public static class TransactWriteExtensions

Inheritance

object

TransactWriteExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Every verb that starts an action has a form with out that hands out a TransactMarker, which finds that action in a TransactionCanceledException. On a table without a sort key, pass default for it. A verb throws InvalidOperationException for action 101, because DynamoDB takes 100.

Methods

Check<TChain>(TChain, Table<Item>, AttributeValue, AttributeValue)

Adds a condition check on a table without a schema, by the values of the key: an item that takes part in the transaction without being written, which is how a write depends on another item. The step needs a condition, and it costs a write like any other action.

public static ConditionStep Check<TChain>(this TChain chain, Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey = default) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<Item>

The table, one without a schema. A table of an entity takes a generated key instead.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

sortKey AttributeValue

The sort key as it is stored, which a table with a sort key needs.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A key is empty, or the table has no sort key.

Check<TChain>(TChain, Table<Item>, AttributeValue, AttributeValue, out TransactMarker)

Adds a condition check on a table without a schema, by the values of the key, and hands out its marker.

public static ConditionStep Check<TChain>(this TChain chain, Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<Item>

The table, one without a schema. A table of an entity takes a generated key instead.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

sortKey AttributeValue

The sort key as it is stored, which a table with a sort key needs.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A key is empty, or the table has no sort key.

Check<TChain, T, TKey>(TChain, Table<T>, TKey)

Adds a condition check by a generated key: an item that takes part in the transaction without being written. The step needs a condition.

public static ConditionStep Check<TChain, T, TKey>(this TChain chain, Table<T> table, TKey key) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

key TKey

The key.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the table.

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

table or key is null.

Check<TChain, T, TKey>(TChain, Table<T>, TKey, out TransactMarker)

Adds a condition check by a generated key, and hands out its marker.

public static ConditionStep Check<TChain, T, TKey>(this TChain chain, Table<T> table, TKey key, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

key TKey

The key.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the table.

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

table or key is null.

Delete<TChain>(TChain, Table<Item>, AttributeValue, AttributeValue)

Adds a delete on a table without a schema, by the values of the key. Deleting what does not exist is no failure unless IfExists<TStep>(TStep) asks for one.

public static ConditionStep Delete<TChain>(this TChain chain, Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey = default) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<Item>

The table, one without a schema. A table of an entity takes a generated key instead.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

sortKey AttributeValue

The sort key as it is stored, which a table with a sort key needs.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A key is empty, or the table has no sort key.

Delete<TChain>(TChain, Table<Item>, AttributeValue, AttributeValue, out TransactMarker)

Adds a delete on a table without a schema, by the values of the key, and hands out its marker.

public static ConditionStep Delete<TChain>(this TChain chain, Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<Item>

The table, one without a schema. A table of an entity takes a generated key instead.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

sortKey AttributeValue

The sort key as it is stored, which a table with a sort key needs.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A key is empty, or the table has no sort key.

Delete<TChain, T, TKey>(TChain, Table<T>, TKey)

Adds a delete by a generated key. Deleting what does not exist is no failure unless IfExists<TStep>(TStep) asks for one.

public static ConditionStep Delete<TChain, T, TKey>(this TChain chain, Table<T> table, TKey key) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

key TKey

The key.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the table.

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

table or key is null.

Delete<TChain, T, TKey>(TChain, Table<T>, TKey, out TransactMarker)

Adds a delete by a generated key, and hands out its marker.

public static ConditionStep Delete<TChain, T, TKey>(this TChain chain, Table<T> table, TKey key, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

key TKey

The key.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

ConditionStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the table.

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

table or key is null.

IfExists<TStep>(TStep)

Makes this action depend on an item having its key (attribute_exists on the partition key of its table). Otherwise the whole transaction is cancelled. Version 0 says that no item has the key, so with it the next action or SendAsync throws InvalidOperationException, unless IgnoreVersion() took the version of an entity back. With Allow, version 0 asks for an item that reads as 0 besides.

public static TStep IfExists<TStep>(this TStep step) where TStep : ITransactWriteStep<TStep>, allows ref struct

Parameters

step TStep

The step, which this replaces.

Returns

TStep

The step.

Type Parameters

TStep

The type of the step.

IfNotExists<TStep>(TStep)

Makes this action depend on no item having its key (attribute_not_exists on the partition key of its table). Otherwise the whole transaction is cancelled.

public static TStep IfNotExists<TStep>(this TStep step) where TStep : ITransactWriteStep<TStep>, allows ref struct

Parameters

step TStep

The step, which this replaces.

Returns

TStep

The step.

Type Parameters

TStep

The type of the step.

Remarks

An entity with a VersionAttribute must then hold version 0, whose condition is this one and renders once: the next action or SendAsync throws InvalidOperationException for any other, unless IgnoreVersion() was called, because no item can lack its key and hold a version.

Put<TChain, T>(TChain, Table<T>, T)

Adds a put of a whole item, which replaces everything under its key. The item is written to the request here and now.

public static PutStep Put<TChain, T>(this TChain chain, Table<T> table, T item) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

item T

The item, which must hold the key attributes.

Returns

PutStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the item.

Exceptions

ArgumentNullException

table or item is null.

Put<TChain, T>(TChain, Table<T>, T, out TransactMarker)

Adds a put of a whole item, which replaces everything under its key, and hands out its marker. The item is written to the request here and now.

public static PutStep Put<TChain, T>(this TChain chain, Table<T> table, T item, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

item T

The item, which must hold the key attributes.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

PutStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the item.

Exceptions

ArgumentNullException

table or item is null.

ReturnCapacity<TChain>(TChain, ReturnConsumedCapacity)

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

public static TChain ReturnCapacity<TChain>(this TChain chain, ReturnConsumedCapacity detail = ReturnConsumedCapacity.Total) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step, which this replaces.

detail ReturnConsumedCapacity

How much detail to return.

Returns

TChain

The command or step.

Type Parameters

TChain

The type of the command or step.

ReturnMetrics<TChain>(TChain)

Asks for the size estimates of the item collections, which go to ItemCollectionMetrics. DynamoDB has them for tables with a local secondary index.

public static TChain ReturnMetrics<TChain>(this TChain chain) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step, which this replaces.

Returns

TChain

The command or step.

Type Parameters

TChain

The type of the command or step.

ReturnOldOnFailure<TStep>(TStep)

Puts the existing item on ItemFor(TransactMarker) when the condition of this action fails, which saves a read to find out why. It costs no extra capacity.

public static TStep ReturnOldOnFailure<TStep>(this TStep step) where TStep : ITransactWriteStep<TStep>, allows ref struct

Parameters

step TStep

The step, which this replaces.

Returns

TStep

The step.

Type Parameters

TStep

The type of the step.

SendAsync<TChain>(TChain, CancellationToken)

Sends the transaction. All actions take effect, or none does. The client retries with the same ClientRequestToken, so a retry after a lost response does not apply anything twice.

public static ValueTask<TransactWriteResult> SendAsync<TChain>(this TChain chain, CancellationToken cancellationToken = default) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step.

cancellationToken CancellationToken

Cancels the call.

Returns

ValueTask<TransactWriteResult>

The result. Await it once.

Type Parameters

TChain

The type of the command or step.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered, or it has no action, which DynamoDB would reject.

ObjectDisposedException

The client is disposed.

TransactionCanceledException

DynamoDB cancelled the transaction, and nothing was written. The exception says why, per action.

IdempotentParameterMismatchException

The token was used within the last 10 minutes for other actions.

ValidationException

DynamoDB rejects the request, for example because it touches one item twice; the exception shows the expressions, per action.

ResourceNotFoundException

A table does not exist.

DynamoDbException

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

Token<TChain>(TChain, string)

Sets the idempotency token of the transaction, in place of the one SendAsync<TChain>(TChain, CancellationToken) generates, so that a retry of your own does not apply the transaction twice.

public static TChain Token<TChain>(this TChain chain, string token) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step, which this replaces.

token string

The token, of 1 to 36 characters, which DynamoDB checks.

Returns

TChain

The command or step.

Type Parameters

TChain

The type of the command or step.

Remarks

A generated token is made once per send, and the client's own retries of that send carry it unchanged, so a lost response does not apply the transaction twice. A retry of your own builds and sends the transaction again, which generates a new token: for that, set one that stays the same, such as the id of the business operation. For 10 minutes DynamoDB answers a repeat with the outcome of the first and does not do it again.

Exceptions

ArgumentException

token is null or empty.

Unique<TChain, T>(TChain, Table<T>, T, out TransactMarker)

Adds a put of a claim item that makes a value unique, such as an email address: .Unique(emails, new EmailClaim(email, id), out var taken). The transaction is cancelled if the item exists.

public static PutStep Unique<TChain, T>(this TChain chain, Table<T> table, T item, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

item T

The marker item, whose key is the value that must be unique.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

PutStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the marker item.

Remarks

DynamoDB enforces uniqueness only for a primary key, so a value that must be unique gets an item of its own, whose key is that value. It is a put with attribute_not_exists on the partition key, and ReasonFor(TransactMarker) with the marker says that this was the reason. ReturnOldOnFailure<TStep>(TStep) also says who holds the value.

Exceptions

ArgumentNullException

table or item is null.

Unique<TChain, T, TKey>(TChain, Table<T>, TKey, out TransactMarker)

Adds a put of a claim item that consists of a key and nothing else, for a value that must be unique and has nothing to say beyond that: .Unique(emails, EmailClaim.Keys.Of(email), out var taken). The transaction is cancelled if the item exists.

public static PutStep Unique<TChain, T, TKey>(this TChain chain, Table<T> table, TKey key, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

key TKey

The key of the marker item, which holds the value that must be unique.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

PutStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the table.

TKey

The key. A key of another entity is a compile error.

Remarks

It is a put with attribute_not_exists on the partition key, and ReasonFor(TransactMarker) with the marker says that this was the reason. The item has no discriminator, so a typed read of it fails; it is there to exist, and to be deleted by its key.

Exceptions

ArgumentNullException

table or key is null.

Update<TChain>(TChain, Table<Item>, AttributeValue, AttributeValue)

Adds an update on a table without a schema, by the values of the key. It creates the item if none has the key, unless IfExists<TStep>(TStep) says otherwise.

public static UpdateStep Update<TChain>(this TChain chain, Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey = default) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<Item>

The table, one without a schema. A table of an entity takes a generated key instead.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

sortKey AttributeValue

The sort key as it is stored, which a table with a sort key needs.

Returns

UpdateStep

The step.

Type Parameters

TChain

The type of the command or step before this.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A key is empty, or the table has no sort key.

Update<TChain>(TChain, Table<Item>, AttributeValue, AttributeValue, out TransactMarker)

Adds an update on a table without a schema, by the values of the key, and hands out its marker.

public static UpdateStep Update<TChain>(this TChain chain, Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<Item>

The table, one without a schema. A table of an entity takes a generated key instead.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

sortKey AttributeValue

The sort key as it is stored, which a table with a sort key needs.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

UpdateStep

The step.

Type Parameters

TChain

The type of the command or step before this.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A key is empty, or the table has no sort key.

Update<TChain, T, TKey>(TChain, Table<T>, TKey)

Adds an update by a generated key. It creates the item if none has the key, unless IfExists<TStep>(TStep) says otherwise.

public static UpdateStep Update<TChain, T, TKey>(this TChain chain, Table<T> table, TKey key) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

key TKey

The key.

Returns

UpdateStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the table.

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

table or key is null.

Update<TChain, T, TKey>(TChain, Table<T>, TKey, out TransactMarker)

Adds an update by a generated key, and hands out its marker.

public static UpdateStep Update<TChain, T, TKey>(this TChain chain, Table<T> table, TKey key, out TransactMarker marker) where TChain : ITransactWriteChain<TChain>, allows ref struct where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

chain TChain

The command or step before this, which this replaces.

table Table<T>

The table.

key TKey

The key.

marker TransactMarker

What finds this action in a cancelled transaction.

Returns

UpdateStep

The step.

Type Parameters

TChain

The type of the command or step before this.

T

The type of the table.

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

table or key is null.