Class UpdateReturningBuilder<TEntity, TResult>

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Fluent terminal for an UPDATE that returns the updated rows through the provider's RETURNING/OUTPUT form, started with Returning() or Returning<TResult>(Expression<Func<TEntity, TResult>>). The returned rows are materialised with the same projection pipeline as a query; every terminal reads the result through Single() or ToList().

public sealed class UpdateReturningBuilder<TEntity, TResult>

Type Parameters

TEntity

The mapped entity type whose rows are updated.

TResult

The materialized row type (the entity or a projection).

Inheritance

object

UpdateReturningBuilder<TEntity, TResult>

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

OutputInto(string)

Writes the updated rows into targetTable through SQL Server's OUTPUT ... INTO clause instead of returning them to the client. The target must already exist with columns whose names match the selected output columns.

public OutputIntoBuilder OutputInto(string targetTable)

Parameters

targetTable string

The raw (unquoted) target table name.

Returns

OutputIntoBuilder

An output-into terminal whose Execute writes the rows and returns the affected-row count.

Exceptions

ArgumentException

targetTable is null or empty.

OutputIntoTableVariable(string, string)

Writes the updated rows into a table variable through SQL Server's OUTPUT ... INTO clause instead of returning them to the client. The batch declares the variable from columnDefinitions, writes the selected output columns into it and reads them back: DECLARE @t TABLE (<definitions>); UPDATE ... OUTPUT ... INTO @t (...); SELECT ... FROM @t;. Providers without OUTPUT INTO reject the statement with NotSupportedException when it renders.

public OutputIntoBuilder OutputIntoTableVariable(string variableName, string columnDefinitions)

Parameters

variableName string

The table-variable name, including the leading @; never bracketed or quoted.

columnDefinitions string

The trusted column-definition text of the DECLARE @t TABLE (...) declaration; embedded verbatim and never parameterised.

Returns

OutputIntoBuilder

An output-into terminal whose Execute writes the rows and returns the affected-row count.

Exceptions

ArgumentException

variableName is not a bare table-variable name, or columnDefinitions is null or empty.

OutputIntoThenOutput(string)

Writes the updated rows into targetTable and also returns them to the client through a second OUTPUT clause (SQL Server). Chain a row terminal such as ToList() on the returned builder.

public UpdateReturningBuilder<TEntity, TResult> OutputIntoThenOutput(string targetTable)

Parameters

targetTable string

The raw (unquoted) target table name.

Returns

UpdateReturningBuilder<TEntity, TResult>

A returning builder that writes into the target and returns the same rows to the client.

Exceptions

ArgumentException

targetTable is null or empty.

Single()

Executes the update and returns the single updated row.

public TResult Single()

Returns

TResult

The materialized row.

Exceptions

InvalidOperationException

The update touched no row, or more than one; use ToList().

NotSupportedException

The provider cannot return updated rows, or the context is read-only.

SingleAsync(CancellationToken)

Asynchronously executes the update and returns the single updated row.

public Task<TResult> SingleAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<TResult>

A task producing the materialized row.

Exceptions

InvalidOperationException

The update touched no row, or more than one; use ToListAsync(CancellationToken).

NotSupportedException

The provider cannot return updated rows, or the context is read-only.

ToList()

Executes the update and returns every updated row.

public IReadOnlyList<TResult> ToList()

Returns

IReadOnlyList<TResult>

The materialized rows, in result-set order.

Exceptions

NotSupportedException

The provider cannot return updated rows, or the context is read-only.

ToListAsync(CancellationToken)

Asynchronously executes the update and returns every updated row.

public Task<IReadOnlyList<TResult>> ToListAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<IReadOnlyList<TResult>>

A task producing the materialized rows, in result-set order.

Exceptions

NotSupportedException

The provider cannot return updated rows, or the context is read-only.

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

NotSupportedException

The context is not database-backed (for example the in-memory provider), or the provider cannot return updated rows.