Class InsertReturningBuilder<TEntity, TResult>

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Fluent terminal for an INSERT that returns the written rows or generated key through the provider's RETURNING/OUTPUT form or its scalar identity function, started with Returning(), Returning<TResult>(Expression<Func<TEntity, TResult>>), ReturningIdentity<TKey>(Expression<Func<TEntity, TKey>>), ReturningIdentity<TKey>() or ReturningKey<TKey>().

The returned rows are materialised with the same projection pipeline as a query: the entity form returns TEntity, the projection form returns the projected shape. The builder is single-use, like the InsertBuilder<TEntity> it is created from, and every terminal reads the result through Single() or ToList().

public sealed class InsertReturningBuilder<TEntity, TResult>

Type Parameters

TEntity

The mapped entity type inserted.

TResult

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

Inheritance

object

InsertReturningBuilder<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 inserted 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. Providers without OUTPUT INTO reject the statement with NotSupportedException when it renders.

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.

NotSupportedException

The builder has no explicit output columns (the identity-function form).

OutputIntoTableVariable(string, string)

Writes the inserted 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>); INSERT ... 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.

NotSupportedException

The builder has no explicit output columns (the identity-function form).

OutputIntoThenOutput(string)

Writes the inserted 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 InsertReturningBuilder<TEntity, TResult> OutputIntoThenOutput(string targetTable)

Parameters

targetTable string

The raw (unquoted) target table name.

Returns

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

NotSupportedException

The builder has no explicit output columns (the identity-function form).

Single()

Executes the insert and returns the single returned row (or generated key).

public TResult Single()

Returns

TResult

The materialized row or key.

Exceptions

InvalidOperationException

The insert writes more than one row; use ToList().

NotSupportedException

The provider cannot return the requested value, or the context is read-only.

SingleAsync(CancellationToken)

Asynchronously executes the insert and returns the single returned row (or generated key).

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

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<TResult>

A task producing the materialized row or key.

Exceptions

InvalidOperationException

The insert writes more than one row; use ToListAsync(CancellationToken).

NotSupportedException

The provider cannot return the requested value, or the context is read-only.

ToList()

Executes the insert and returns every returned row (or key). A multi-row insert returns one entry per row where the provider supports RETURNING/OUTPUT; the scalar identity-function fallback yields a single entry.

public IReadOnlyList<TResult> ToList()

Returns

IReadOnlyList<TResult>

The materialized rows or keys, in result-set order.

Exceptions

NotSupportedException

The provider cannot return the requested value, or the context is read-only.

ToListAsync(CancellationToken)

Asynchronously executes the insert and returns every returned row (or key). A multi-row insert returns one entry per row where the provider supports RETURNING/OUTPUT; the scalar identity-function fallback yields a single entry.

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

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<IReadOnlyList<TResult>>

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

Exceptions

NotSupportedException

The provider cannot return the requested value, 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.