Class UpdateBuilder<TEntity>

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Fluent builder for an UPDATE statement, started with CreateUpdateBuilder<TEntity>(IDataContext, Action<EntityMetadataBuilder<TEntity>>?). The columns to write are supplied with Set<TValue>(Expression<Func<TEntity, TValue>>, TValue), Set<TValue>(Expression<Func<TEntity, TValue>>, Expression<Func<TEntity, TValue>>) or Set(TEntity); the rows to change are selected with Where(Expression<Func<TEntity, bool>>). Omitting Where(Expression<Func<TEntity, bool>>) updates every row the target's global query filters allow (disable them with IgnoreFilters to reach the rest).

There is deliberately no change tracking: the terminal issues exactly one explicit command and updates only the columns named in the SET list, never "the changed properties".

public sealed class UpdateBuilder<TEntity>

Type Parameters

TEntity

The mapped entity type whose rows are updated.

Inheritance

object

UpdateBuilder<TEntity>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

EntityBuilderExtensions.AsEntityBuilder<T>(object?)

Methods

IgnoreFilters()

Disables all global query filters declared for the target entity type, so the update (in every form, including the key form) touches the unfiltered rows. Repeatable: a later call accumulates with the earlier scope.

public UpdateBuilder<TEntity> IgnoreFilters()

Returns

UpdateBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(IEnumerable<string>)

Disables the named global query filters identified by filterKeys on the target entity type. An empty or null filterKeys disables nothing. Repeatable: a later call accumulates (union) with the earlier scope.

public UpdateBuilder<TEntity> IgnoreFilters(IEnumerable<string> filterKeys)

Parameters

filterKeys IEnumerable<string>

The filter keys to disable.

Returns

UpdateBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(IEnumerable<string>, params Type[])

Disables the named global query filters identified by filterKeys only on the given entityTypes (the intersection of keys and types); an empty entityTypes means any entity type. The key list is the gate: an empty or null filterKeys disables nothing even when entity types are supplied. Repeatable: a later call accumulates (union) with the earlier scope.

public UpdateBuilder<TEntity> IgnoreFilters(IEnumerable<string> filterKeys, params Type[] entityTypes)

Parameters

filterKeys IEnumerable<string>

The filter keys to disable.

entityTypes Type[]

The entity types the disable is scoped to; empty means any entity type.

Returns

UpdateBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(params Type[])

Disables every global query filter declared for the given entity types. An empty or null entityTypes disables nothing. Repeatable: a later call accumulates (union) with the earlier scope.

public UpdateBuilder<TEntity> IgnoreFilters(params Type[] entityTypes)

Parameters

entityTypes Type[]

The entity types whose filters are disabled.

Returns

UpdateBuilder<TEntity>

This builder, for chaining.

Returning()

Switches the builder to a row-returning terminal that materialises the whole updated row through the provider's RETURNING/OUTPUT form (the equivalent of RETURNING * over the mapped columns). The predicate form is required: the key form (Update(entity)) does not expose Returning.

public UpdateReturningBuilder<TEntity, TEntity> Returning()

Returns

UpdateReturningBuilder<TEntity, TEntity>

A returning builder whose terminals produce TEntity.

Returning<TResult>(Expression<Func<TEntity, TResult>>)

Switches the builder to a row-returning terminal that materialises a projection of the updated row through the provider's RETURNING/OUTPUT form. The projection may be the identity, a single mapped property, an anonymous type, a positional constructor or a member-init; it may only reference mapped properties.

public UpdateReturningBuilder<TEntity, TResult> Returning<TResult>(Expression<Func<TEntity, TResult>> projection)

Parameters

projection Expression<Func<TEntity, TResult>>

Selects the mapped columns to return.

Returns

UpdateReturningBuilder<TEntity, TResult>

A returning builder whose terminals produce TResult.

Type Parameters

TResult

The projected row shape.

Exceptions

NotSupportedException

The projection references something other than mapped properties.

Set(TEntity)

Writes every mapped, writable column of entity. Key, identity and computed columns are excluded automatically. Combine with Where(Expression<Func<TEntity, bool>>) to select the row(s); this form does not build the filter from the entity's key (use Update<TEntity>(IDataContext, TEntity) for that).

public UpdateBuilder<TEntity> Set(TEntity entity)

Parameters

entity TEntity

The entity whose column values are written.

Returns

UpdateBuilder<TEntity>

This builder, for chaining.

Set<TValue>(Expression<Func<TEntity, TValue>>, Expression<Func<TEntity, TValue>>)

Assigns the result of an expression to a mapped column. The expression is rendered by the same translator as a SELECT projection, so it may reference other mapped columns (Set(x => x.Counter, x => x.Counter + 1), Set(x => x.UpdatedAt, x => x.CreatedAt)) and captured variables (which become parameters). A parameter-free expression is folded into a parameter.

public UpdateBuilder<TEntity> Set<TValue>(Expression<Func<TEntity, TValue>> column, Expression<Func<TEntity, TValue>> value)

Parameters

column Expression<Func<TEntity, TValue>>

Selects the mapped column to write.

value Expression<Func<TEntity, TValue>>

The value expression to evaluate.

Returns

UpdateBuilder<TEntity>

This builder, for chaining.

Type Parameters

TValue

The column's CLR type.

Exceptions

NotSupportedException

The selected column is computed, or the value expression cannot be translated.

Set<TValue>(Expression<Func<TEntity, TValue>>, TValue)

Assigns a constant value to a mapped column. The value is always bound as a parameter, never inlined into the SQL. Repeating the call for the same column replaces the earlier assignment.

public UpdateBuilder<TEntity> Set<TValue>(Expression<Func<TEntity, TValue>> column, TValue value)

Parameters

column Expression<Func<TEntity, TValue>>

Selects the mapped column to write.

value TValue

The value to write, or null for SQL NULL.

Returns

UpdateBuilder<TEntity>

This builder, for chaining.

Type Parameters

TValue

The column's CLR type.

Exceptions

NotSupportedException

The selected column is computed and cannot be written.

ToSql()

Renders the parameterised SQL this builder would execute, without executing it. Useful for diagnostics and for verifying SQL generation without a database.

public string ToSql()

Returns

string

The rendered SQL text.

Exceptions

InvalidOperationException

No assignment was specified.

NotSupportedException

The context is not database-backed (for example the in-memory provider), or the provider cannot express UPDATE.

Update()

Executes the update and returns the number of affected rows.

public int Update()

Returns

int

The number of updated rows, as reported by the provider.

Exceptions

InvalidOperationException

No assignment was specified.

NotSupportedException

The context does not support data modification, or the provider cannot express UPDATE.

UpdateAsync(CancellationToken)

Asynchronously executes the update and returns the number of affected rows.

public Task<int> UpdateAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<int>

A task producing the number of updated rows.

Exceptions

InvalidOperationException

No assignment was specified.

NotSupportedException

The context does not support data modification, or the provider cannot express UPDATE.

Where(Expression<Func<TEntity, bool>>)

Restricts the update to the rows satisfying predicate. The predicate is translated by the same expression pipeline as a SELECT WHERE; captured variables become parameters, inline literals are emitted verbatim. Repeating the call combines the predicates with and.

public UpdateBuilder<TEntity> Where(Expression<Func<TEntity, bool>> predicate)

Parameters

predicate Expression<Func<TEntity, bool>>

The condition each updated row must satisfy.

Returns

UpdateBuilder<TEntity>

This builder, for chaining.