Class QueryCommandExtensions

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Extension methods that run a QueryCommand<TResult> against raw SQL instead of the generated query, and the terminal operators that stream LOB columns through SequentialAccess: the single-column ToStream(QueryCommand<byte[]>, params ReadOnlySpan<object?>) / ToTextReader(QueryCommand<string>, params ReadOnlySpan<object?>) and the multi-column ToDataReader<TResult>(QueryCommand<TResult>, params ReadOnlySpan<object?>), with their asynchronous counterparts.

public static class QueryCommandExtensions

Inheritance

object

QueryCommandExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

PrepareFromSql<TResult>(QueryCommand<TResult>, string, PrepareFromSqlMode, CancellationToken)

Prepares the command to read the given SQL using the given caching/streaming mode.

public static IPreparedQueryCommand<TResult> PrepareFromSql<TResult>(this QueryCommand<TResult> queryCommand, string sql, PrepareFromSqlMode mode, CancellationToken cancellationToken = default)

Parameters

queryCommand QueryCommand<TResult>

The command to run.

sql string

The SQL text to execute.

mode PrepareFromSqlMode

How the prepared command is cached and whether it streams.

cancellationToken CancellationToken

A token that cancels preparation.

Returns

IPreparedQueryCommand<TResult>

The prepared command.

Type Parameters

TResult

The projected result type.

PrepareFromSql<TResult>(QueryCommand<TResult>, string, object?, PrepareFromSqlMode, CancellationToken)

Prepares the command to read the given SQL with parameters and an explicit caching/streaming mode.

public static IPreparedQueryCommand<TResult> PrepareFromSql<TResult>(this QueryCommand<TResult> queryCommand, string sql, object? @params, PrepareFromSqlMode mode, CancellationToken cancellationToken = default)

Parameters

queryCommand QueryCommand<TResult>

The command to run.

sql string

The SQL text to execute.

params object

An object whose public properties become the SQL parameters, or null.

mode PrepareFromSqlMode

How the prepared command is cached and whether it streams.

cancellationToken CancellationToken

A token that cancels preparation.

Returns

IPreparedQueryCommand<TResult>

The prepared command.

Type Parameters

TResult

The projected result type.

PrepareFromSql<TResult>(QueryCommand<TResult>, string, object?, CancellationToken)

Prepares the command to read the given SQL with parameters supplied as the public properties of params.

public static IPreparedQueryCommand<TResult> PrepareFromSql<TResult>(this QueryCommand<TResult> queryCommand, string sql, object? @params, CancellationToken cancellationToken = default)

Parameters

queryCommand QueryCommand<TResult>

The command to run.

sql string

The SQL text to execute.

params object

An object whose public properties become the SQL parameters, or null.

cancellationToken CancellationToken

A token that cancels preparation.

Returns

IPreparedQueryCommand<TResult>

The prepared command.

Type Parameters

TResult

The projected result type.

PrepareFromSql<TResult>(QueryCommand<TResult>, string, CancellationToken)

Prepares the command to read the given SQL, materializing the result as TResult.

public static IPreparedQueryCommand<TResult> PrepareFromSql<TResult>(this QueryCommand<TResult> queryCommand, string sql, CancellationToken cancellationToken = default)

Parameters

queryCommand QueryCommand<TResult>

The command to run.

sql string

The SQL text to execute.

cancellationToken CancellationToken

A token that cancels preparation.

Returns

IPreparedQueryCommand<TResult>

The prepared command.

Type Parameters

TResult

The projected result type.

ToDataReaderAsync<TResult>(QueryCommand<TResult>, params object?[])

Asynchronously opens a forward-only DbDataReader over the command's multi-column projection.

public static Task<DbDataReader> ToDataReaderAsync<TResult>(this QueryCommand<TResult> command, params object?[] parameters)

Parameters

command QueryCommand<TResult>

The command to execute.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<DbDataReader>

A task producing a reader that owns the provider reader and the per-call command until it is disposed.

Type Parameters

TResult

The projected result type; it is not materialized on this path.

Remarks

The caller owns the returned reader and must dispose it, which releases the provider reader and the per-call command; the context and its connection stay open. On PostgreSQL and SQL Server the reader uses sequential access: read columns in ascending ordinal order and do not read a column twice. On SQLite the projection is locator-free and buffered (non-sequential): FieldCount equals the projection column count and a large BLOB is read whole rather than chunked. The terminal fails closed on providers without sequential access (MySQL/MariaDB, ClickHouse) and on the in-memory provider, which has no DbDataReader.

ToDataReaderAsync<TResult>(QueryCommand<TResult>, CancellationToken, params object?[])

Asynchronously opens a forward-only DbDataReader over the command's multi-column projection.

public static Task<DbDataReader> ToDataReaderAsync<TResult>(this QueryCommand<TResult> command, CancellationToken cancellationToken, params object?[] parameters)

Parameters

command QueryCommand<TResult>

The command to execute.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<DbDataReader>

A task producing a reader that owns the provider reader and the per-call command until it is disposed.

Type Parameters

TResult

The projected result type; it is not materialized on this path.

Remarks

The caller owns the returned reader and must dispose it, which releases the provider reader and the per-call command; the context and its connection stay open. On PostgreSQL and SQL Server the reader uses sequential access: read columns in ascending ordinal order and do not read a column twice. On SQLite the projection is locator-free and buffered (non-sequential): FieldCount equals the projection column count and a large BLOB is read whole rather than chunked. The terminal fails closed on providers without sequential access (MySQL/MariaDB, ClickHouse) and on the in-memory provider, which has no DbDataReader.

ToDataReader<TResult>(QueryCommand<TResult>, params ReadOnlySpan<object?>)

Opens a forward-only DbDataReader over the command's multi-column projection.

public static DbDataReader ToDataReader<TResult>(this QueryCommand<TResult> command, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<TResult>

The command to execute.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

DbDataReader

A reader that owns the provider reader and the per-call command until it is disposed.

Type Parameters

TResult

The projected result type; it is not materialized on this path.

Remarks

The caller owns the returned reader and must dispose it, which releases the provider reader and the per-call command; the context and its connection stay open. On PostgreSQL and SQL Server the reader uses sequential access: read columns in ascending ordinal order and do not read a column twice. On SQLite the projection is locator-free and buffered (non-sequential): FieldCount equals the projection column count and a large BLOB is read whole rather than chunked. The terminal fails closed on providers without sequential access (MySQL/MariaDB, ClickHouse) and on the in-memory provider, which has no DbDataReader.

ToDataReader<TResult>(QueryCommand<TResult>, CancellationToken, params ReadOnlySpan<object?>)

Opens a forward-only DbDataReader over the command's multi-column projection.

public static DbDataReader ToDataReader<TResult>(this QueryCommand<TResult> command, CancellationToken cancellationToken, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<TResult>

The command to execute.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

DbDataReader

A reader that owns the provider reader and the per-call command until it is disposed.

Type Parameters

TResult

The projected result type; it is not materialized on this path.

Remarks

The caller owns the returned reader and must dispose it, which releases the provider reader and the per-call command; the context and its connection stay open. On PostgreSQL and SQL Server the reader uses sequential access: read columns in ascending ordinal order and do not read a column twice. On SQLite the projection is locator-free and buffered (non-sequential): FieldCount equals the projection column count and a large BLOB is read whole rather than chunked. The terminal fails closed on providers without sequential access (MySQL/MariaDB, ClickHouse) and on the in-memory provider, which has no DbDataReader.

ToStream(QueryCommand<byte[]>, params ReadOnlySpan<object?>)

Opens a streaming read of a single byte[] column.

public static Stream ToStream(this QueryCommand<byte[]> command, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<byte[]>

The command whose projection is exactly one byte[] column.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

Stream

A stream that owns the reader until it is disposed.

ToStream(QueryCommand<byte[]>, CancellationToken, params ReadOnlySpan<object?>)

Opens a streaming read of a single byte[] column.

public static Stream ToStream(this QueryCommand<byte[]> command, CancellationToken cancellationToken, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<byte[]>

The command whose projection is exactly one byte[] column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

Stream

A stream that owns the reader until it is disposed.

Remarks

On the in-memory provider the value is already materialized: the returned read-only MemoryStream wraps it, and a missing row or a NULL value yields Null.

ToStream(QueryCommand<Stream>, params ReadOnlySpan<object?>)

Opens a streaming read of a binary column selected by name as a Stream.

public static Stream ToStream(this QueryCommand<Stream> command, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<Stream>

The command whose projection is a single streaming binary column.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

Stream

A stream that owns the reader and the per-call command until it is disposed.

ToStream(QueryCommand<Stream>, CancellationToken, params ReadOnlySpan<object?>)

Opens a streaming read of a binary column selected by name as a Stream.

public static Stream ToStream(this QueryCommand<Stream> command, CancellationToken cancellationToken, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<Stream>

The command whose projection is a single streaming binary column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

Stream

A stream that owns the reader and the per-call command until it is disposed.

ToStreamAsync(QueryCommand<byte[]>, params object?[])

Asynchronously opens a streaming read of a single byte[] column.

public static Task<Stream> ToStreamAsync(this QueryCommand<byte[]> command, params object?[] parameters)

Parameters

command QueryCommand<byte[]>

The command whose projection is exactly one byte[] column.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<Stream>

A task producing a stream that owns the reader until it is disposed.

ToStreamAsync(QueryCommand<byte[]>, CancellationToken, params object?[])

Asynchronously opens a streaming read of a single byte[] column.

public static Task<Stream> ToStreamAsync(this QueryCommand<byte[]> command, CancellationToken cancellationToken, params object?[] parameters)

Parameters

command QueryCommand<byte[]>

The command whose projection is exactly one byte[] column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<Stream>

A task producing a stream that owns the reader until it is disposed.

Remarks

On the in-memory provider the value is already materialized: the returned read-only MemoryStream wraps it, and a missing row or a NULL value yields Null.

ToStreamAsync(QueryCommand<Stream>, params object?[])

Asynchronously opens a streaming read of a binary column selected by name as a Stream.

public static Task<Stream> ToStreamAsync(this QueryCommand<Stream> command, params object?[] parameters)

Parameters

command QueryCommand<Stream>

The command whose projection is a single streaming binary column.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<Stream>

A task producing a stream that owns the reader and the per-call command until it is disposed.

ToStreamAsync(QueryCommand<Stream>, CancellationToken, params object?[])

Asynchronously opens a streaming read of a binary column selected by name as a Stream.

public static Task<Stream> ToStreamAsync(this QueryCommand<Stream> command, CancellationToken cancellationToken, params object?[] parameters)

Parameters

command QueryCommand<Stream>

The command whose projection is a single streaming binary column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<Stream>

A task producing a stream that owns the reader and the per-call command until it is disposed.

ToTextReader(QueryCommand<TextReader>, params ReadOnlySpan<object?>)

Opens a streaming read of a text column selected by name as a TextReader.

public static TextReader ToTextReader(this QueryCommand<TextReader> command, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<TextReader>

The command whose projection is a single streaming text column.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

TextReader

A text reader that owns the reader and the per-call command until it is disposed.

ToTextReader(QueryCommand<TextReader>, CancellationToken, params ReadOnlySpan<object?>)

Opens a streaming read of a text column selected by name as a TextReader.

public static TextReader ToTextReader(this QueryCommand<TextReader> command, CancellationToken cancellationToken, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<TextReader>

The command whose projection is a single streaming text column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

TextReader

A text reader that owns the reader and the per-call command until it is disposed.

ToTextReader(QueryCommand<string>, params ReadOnlySpan<object?>)

Opens a streaming read of a single string column.

public static TextReader ToTextReader(this QueryCommand<string> command, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<string>

The command whose projection is exactly one string column.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

TextReader

A text reader that owns the reader until it is disposed.

ToTextReader(QueryCommand<string>, CancellationToken, params ReadOnlySpan<object?>)

Opens a streaming read of a single string column.

public static TextReader ToTextReader(this QueryCommand<string> command, CancellationToken cancellationToken, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<string>

The command whose projection is exactly one string column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Returns

TextReader

A text reader that owns the reader until it is disposed.

Remarks

On the in-memory provider the value is already materialized: the returned StringReader wraps it, and a missing row or a NULL value yields Null.

ToTextReaderAsync(QueryCommand<TextReader>, params object?[])

Asynchronously opens a streaming read of a text column selected by name as a TextReader.

public static Task<TextReader> ToTextReaderAsync(this QueryCommand<TextReader> command, params object?[] parameters)

Parameters

command QueryCommand<TextReader>

The command whose projection is a single streaming text column.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<TextReader>

A task producing a text reader that owns the reader and the per-call command until it is disposed.

ToTextReaderAsync(QueryCommand<TextReader>, CancellationToken, params object?[])

Asynchronously opens a streaming read of a text column selected by name as a TextReader.

public static Task<TextReader> ToTextReaderAsync(this QueryCommand<TextReader> command, CancellationToken cancellationToken, params object?[] parameters)

Parameters

command QueryCommand<TextReader>

The command whose projection is a single streaming text column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<TextReader>

A task producing a text reader that owns the reader and the per-call command until it is disposed.

ToTextReaderAsync(QueryCommand<string>, params object?[])

Asynchronously opens a streaming read of a single string column.

public static Task<TextReader> ToTextReaderAsync(this QueryCommand<string> command, params object?[] parameters)

Parameters

command QueryCommand<string>

The command whose projection is exactly one string column.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<TextReader>

A task producing a text reader that owns the reader until it is disposed.

ToTextReaderAsync(QueryCommand<string>, CancellationToken, params object?[])

Asynchronously opens a streaming read of a single string column.

public static Task<TextReader> ToTextReaderAsync(this QueryCommand<string> command, CancellationToken cancellationToken, params object?[] parameters)

Parameters

command QueryCommand<string>

The command whose projection is exactly one string column.

cancellationToken CancellationToken

A token that cancels opening the reader.

parameters object[]

The positional parameter values bound to the query.

Returns

Task<TextReader>

A task producing a text reader that owns the reader until it is disposed.

Remarks

On the in-memory provider the value is already materialized: the returned StringReader wraps it, and a missing row or a NULL value yields Null.

WithSql<TResult>(QueryCommand<TResult>, string)

Overrides the command's generated SQL with sql and no parameters.

public static QueryCommand<TResult> WithSql<TResult>(this QueryCommand<TResult> queryCommand, string sql)

Parameters

queryCommand QueryCommand<TResult>

The command to override.

sql string

The SQL text to execute.

Returns

QueryCommand<TResult>

The same command, with the raw-SQL override attached.

Type Parameters

TResult

The projected result type.

WithSql<TResult>(QueryCommand<TResult>, string, object?)

Overrides the command's generated SQL with sql, taking the SQL parameters from the public properties of params.

public static QueryCommand<TResult> WithSql<TResult>(this QueryCommand<TResult> queryCommand, string sql, object? @params)

Parameters

queryCommand QueryCommand<TResult>

The command to override.

sql string

The SQL text to execute.

params object

An object whose public properties become the SQL parameters, or null.

Returns

QueryCommand<TResult>

The same command, with the raw-SQL override attached.

Type Parameters

TResult

The projected result type.

WriteCsvAsync<TResult>(QueryCommand<TResult>, Stream, CsvStreamOptions?, CancellationToken, params object?[])

Asynchronously writes the command's Select result as CSV to destination.

public static Task WriteCsvAsync<TResult>(this QueryCommand<TResult> command, Stream destination, CsvStreamOptions? options = null, CancellationToken cancellationToken = default, params object?[] parameters)

Parameters

command QueryCommand<TResult>

The command to execute.

destination Stream

The stream that receives the UTF-8 CSV; it stays open.

options CsvStreamOptions

The CSV dialect options, or null for the defaults.

cancellationToken CancellationToken

A token that cancels the write.

parameters object[]

The positional parameter values bound to the query.

Returns

Task

A task that completes when the CSV has been written.

Type Parameters

TResult

The projected result type; it is not materialized on this path.

WriteCsv<TResult>(QueryCommand<TResult>, Stream, CsvStreamOptions?, CancellationToken, params ReadOnlySpan<object?>)

Writes the command's Select result as CSV to destination.

public static void WriteCsv<TResult>(this QueryCommand<TResult> command, Stream destination, CsvStreamOptions? options = null, CancellationToken cancellationToken = default, params ReadOnlySpan<object?> parameters)

Parameters

command QueryCommand<TResult>

The command to execute.

destination Stream

The stream that receives the UTF-8 CSV; it stays open.

options CsvStreamOptions

The CSV dialect options, or null for the defaults.

cancellationToken CancellationToken

A token that cancels the write.

parameters ReadOnlySpan<object>

The positional parameter values bound to the query.

Type Parameters

TResult

The projected result type; it is not materialized on this path.