Interface IRawCommandExecutor

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Executes a raw parameterised command (not only SELECT) and exposes its result sets, output parameters and return value. This is the foundation of stored-procedure support: the same ProcedureParameter shape carries input, output and structured parameters.

public interface IRawCommandExecutor

Extension Methods

EntityBuilderExtensions.AsEntityBuilder<T>(object?)

Remarks

The default interface implementations throw NotSupportedException, so a provider that cannot run a given command rejects it without declaring the role; the in-memory context rejects both raw commands and stored procedures through these defaults. IDataContext inherits this role. SQLite and ClickHouse reject stored procedures before opening a connection through SupportsStoredProcedures (the DataContext capability gate), not through the default implementation.

SQL injection. The command text is executed verbatim, without parameterisation by the planner. Never concatenate untrusted input; pass values through ProcedureParameter.

Return values. ReturnValue is populated only for a stored-procedure command type issued through ExecuteProcedure(string, params IReadOnlyList<ProcedureParameter>), and only where the provider has a return status (SQL Server). Text commands are provider-dependent and typically do not set it — use an Output parameter instead.

Open reader. The returned ProcedureResult keeps the command and reader open until disposed. On SQL Server without MARS an open reader blocks other commands on the same connection; dispose the result before issuing another command on the context.

Scalars and NULL. A scalar Read<T>() of SQL NULL returns default; read through a nullable T (for example int?) to observe the NULL.

Methods

ExecuteProcedure(string, params IReadOnlyList<ProcedureParameter>)

Executes the stored procedure name with parameters and returns a ProcedureResult owning the reader and command.

ProcedureResult ExecuteProcedure(string name, params IReadOnlyList<ProcedureParameter> parameters)

Parameters

name string

The procedure name, passed to the provider as-is.

parameters IReadOnlyList<ProcedureParameter>

The procedure parameters (input, output, input/output and return value).

Returns

ProcedureResult

The result, which must be disposed to release the reader and command.

Remarks

The name is not escaped, quoted or parameterised; never pass untrusted input as the name. Parameter names are supplied without the provider's prefix. PostgreSQL maps this to a CALL (procedures only; call functions through ExecuteRaw(string, params IReadOnlyList<ProcedureParameter>)). A return value is populated only where the provider has one (SQL Server).

ExecuteProcedureAsync(string, params IReadOnlyList<ProcedureParameter>)

Asynchronously executes the stored procedure name with parameters, using default for the cancellation token. Convenience overload of ExecuteProcedureAsync(string, IReadOnlyList<ProcedureParameter>, CancellationToken).

Task<ProcedureResult> ExecuteProcedureAsync(string name, params IReadOnlyList<ProcedureParameter> parameters)

Parameters

name string

The procedure name, passed to the provider as-is.

parameters IReadOnlyList<ProcedureParameter>

The procedure parameters (input, output, input/output and return value).

Returns

Task<ProcedureResult>

A task producing the result, which must be disposed to release the reader and command.

ExecuteProcedureAsync(string, IReadOnlyList<ProcedureParameter>, CancellationToken)

Asynchronously executes the stored procedure name with parameters and returns a ProcedureResult owning the reader and command. See ExecuteProcedure(string, params IReadOnlyList<ProcedureParameter>).

Task<ProcedureResult> ExecuteProcedureAsync(string name, IReadOnlyList<ProcedureParameter> parameters, CancellationToken cancellationToken = default)

Parameters

name string

The procedure name, passed to the provider as-is.

parameters IReadOnlyList<ProcedureParameter>

The procedure parameters (input, output, input/output and return value).

cancellationToken CancellationToken

Cancels execution.

Returns

Task<ProcedureResult>

A task producing the result, which must be disposed to release the reader and command.

ExecuteRaw(string, params IReadOnlyList<ProcedureParameter>)

Executes sql with parameters and returns a ProcedureResult owning the reader and command.

ProcedureResult ExecuteRaw(string sql, params IReadOnlyList<ProcedureParameter> parameters)

Parameters

sql string

The command text to execute.

parameters IReadOnlyList<ProcedureParameter>

The parameters referenced by sql.

Returns

ProcedureResult

The result, which must be disposed to release the reader and command.

ExecuteRawAsync(string, params IReadOnlyList<ProcedureParameter>)

Asynchronously executes sql with parameters, using default for the cancellation token. Convenience overload of ExecuteRawAsync(string, IReadOnlyList<ProcedureParameter>, CancellationToken).

Task<ProcedureResult> ExecuteRawAsync(string sql, params IReadOnlyList<ProcedureParameter> parameters)

Parameters

sql string

The command text to execute.

parameters IReadOnlyList<ProcedureParameter>

The parameters referenced by sql.

Returns

Task<ProcedureResult>

A task producing the result, which must be disposed to release the reader and command.

ExecuteRawAsync(string, IReadOnlyList<ProcedureParameter>, CancellationToken)

Asynchronously executes sql with parameters and returns a ProcedureResult owning the reader and command.

Task<ProcedureResult> ExecuteRawAsync(string sql, IReadOnlyList<ProcedureParameter> parameters, CancellationToken cancellationToken = default)

Parameters

sql string

The command text to execute.

parameters IReadOnlyList<ProcedureParameter>

The parameters referenced by sql.

cancellationToken CancellationToken

Cancels execution.

Returns

Task<ProcedureResult>

A task producing the result, which must be disposed to release the reader and command.