Class QueryCommand

Namespace

Rinku

Assembly

Rinku.dll

A reusable SQL query or stored procedure. Declare one in a static readonly field and call Query or Execute on it. Use QueryBuilder when values are supplied in several steps.

public class QueryCommand : IQueryCommand, ICache, IDisposable

Inheritance

object

QueryCommand

Implements

IQueryCommand

ICache

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BuilderStarter.StartBuilder(QueryCommand)

BuilderStarter.StartBuilder(QueryCommand, DbCommand)

BuilderStarter.StartBuilder(QueryCommand, DbCommand, params Span<(string, object)>)

BuilderStarter.StartBuilder(QueryCommand, IDbCommand)

BuilderStarter.StartBuilder(QueryCommand, IDbCommand, params Span<(string, object)>)

BuilderStarter.StartBuilder(QueryCommand, params Span<(string, object)>)

Caster.Parse<T>(object?)

Remarks

One instance can be shared across threads. Dispose it when it has a shorter lifetime than the application.

Constructors

QueryCommand(QueryFactory)

Defines a command from a custom QueryFactory.

protected QueryCommand(QueryFactory factory)

Parameters

factory QueryFactory

QueryCommand(QueryFactory, CommandType)

Defines a command from a custom QueryFactory and command type.

protected QueryCommand(QueryFactory factory, CommandType commandType)

Parameters

factory QueryFactory

The query factory to use. The command takes ownership of its mapper.

commandType CommandType

How the provider reads the text.

QueryCommand(string, char)

Defines a reusable command from a SQL template.

public QueryCommand(string query, char variableChar = '\0')

Parameters

query string

The SQL, optionally carrying conditional markers.

variableChar char

The character that marks a variable, @ when left unset.

QueryCommand(string, IEnumerable<string>, CommandType)

Defines a command with an explicit list of parameters. Use this overload for a stored procedure or for SQL that binds parameters by position.

public QueryCommand(string commandText, IEnumerable<string> variableNames, CommandType commandType = CommandType.StoredProcedure)

Parameters

commandText string

The SQL text or stored procedure name.

variableNames IEnumerable<string>

The parameter names in binding order. Each parameter is required.

commandType CommandType

How the provider reads the text.

Examples

static readonly QueryCommand Renumber =
    new("dbo.RenumberTracks", ["albumId", "moved"], CommandType.StoredProcedure);

Renumber.Execute(cnn, new { albumId = 1, moved = 0 });

Fields

CommandType

How the provider reads this command's text. Text for SQL, which is what a template is, and StoredProcedure for a command whose text names a procedure.

public readonly CommandType CommandType

Field Value

CommandType

Mapper

public readonly Mapper Mapper

Field Value

Mapper

Parameters

Gets the parameter settings used by this command.

public readonly QueryParameters Parameters

Field Value

QueryParameters

QueryText

Gets the SQL template used by this command.

public readonly QueryText QueryText

Field Value

QueryText

StartBaseHandlers

public readonly int StartBaseHandlers

Field Value

int

StartBoolCond

public readonly int StartBoolCond

Field Value

int

StartSpecialHandlers

public readonly int StartSpecialHandlers

Field Value

int

Methods

Dispose()

Releases resources used by this command. The command cannot be used after disposal.

public void Dispose()

FromProc(string, IDbConnection, bool)

Creates a command for a stored procedure by reading its parameter details from the database.

public static QueryCommand FromProc(string procedureName, IDbConnection connection, bool inputOutputHasDefault = true)

Parameters

procedureName string

The procedure to call.

connection IDbConnection

The connection to ask, opened for the question if it is not already.

inputOutputHasDefault bool

Whether provider-derived input/output parameters may be omitted.

Returns

QueryCommand

Examples

static readonly QueryCommand Renumber = QueryCommand.FromProc("dbo.RenumberTracks", cnn);

Renumber.Execute(cnn, new { albumId = 1 });

Remarks

This call queries the database. Call it once when the command is declared. To avoid that query, name the parameters with QueryCommand(string, IEnumerable<string>, CommandType).

GetCachedParameterAccessors()

Gets the parameter types and accessor kinds currently held by this command.

public (Type ParameterType, ParameterAccessorKinds Accessors)[] GetCachedParameterAccessors()

Returns

(Type ParameterType, ParameterAccessorKinds Accessors)[]

GetDirectAccessor(nint, Type)

Gets the accessor used to bind the supplied parameter type directly to a database command.

public DirectAccessor GetDirectAccessor(nint handle, Type type)

Parameters

handle nint

type Type

Returns

DirectAccessor

GetUseWithAccessor(nint, Type)

Gets the accessor used by UseWith for the supplied parameter type.

public UseWithAccessor GetUseWithAccessor(nint handle, Type type)

Parameters

handle nint

type Type

Returns

UseWithAccessor

InvalidateParameterAccessor(Type, ParameterAccessorKinds)

Removes the selected accessors for parameterType.

public ParameterAccessorKinds InvalidateParameterAccessor(Type parameterType, ParameterAccessorKinds accessors)

Parameters

parameterType Type

accessors ParameterAccessorKinds

Returns

ParameterAccessorKinds

The accessor kinds that were present and removed.

InvalidateParser(ITypeParser)

Removes one parser from this command. It is also removed from the global cache when nothing else uses it.

public int InvalidateParser(ITypeParser parser)

Parameters

parser ITypeParser

Returns

int

The number of this command's cache entries that referenced parser.

InvalidateParser(ITypeParser, QueryParserInvalidationScope)

Removes one parser from this command using the selected scope.

public int InvalidateParser(ITypeParser parser, QueryParserInvalidationScope scope)

Parameters

parser ITypeParser

scope QueryParserInvalidationScope

Returns

int

The number of this command's cache entries that referenced parser.

InvalidateParsers()

Removes every parser held by this command. A parser is also removed from the global cache when nothing else uses it.

public int InvalidateParsers()

Returns

int

The number of cache entries removed.

InvalidateParsers(QueryParserInvalidationScope)

Removes every parser held by this command using the selected scope.

public int InvalidateParsers(QueryParserInvalidationScope scope)

Parameters

scope QueryParserInvalidationScope

Returns

int

The number of cache entries this command held when invalidation began.

NeedToCache(object?[])

Checks whether any supplied parameter still needs database parameter details.

public bool NeedToCache(object?[] variables)

Parameters

variables object[]

Returns

bool

false when every used parameter is already cached.

NeedToCache(Span<bool>)

Checks whether any used parameter still needs database parameter details.

public bool NeedToCache(Span<bool> usageMap)

Parameters

usageMap Span<bool>

Returns

bool

false when every used parameter is already cached.

SetCommand(DbCommand, object?, Span<bool>)

Sets cmd's text and parameters for one run, reading the values from a parameter object matched to keys by name, and records which keys were used in usageMap.

public bool SetCommand(DbCommand cmd, object? parameterObj, Span<bool> usageMap)

Parameters

cmd DbCommand

The command to fill.

parameterObj object

The object whose members supply the values.

usageMap Span<bool>

Filled with which keys ended up used, so the result can be read back correctly.

Returns

bool

true when the command is ready to run.

SetCommand(DbCommand, object?[])

Sets cmd's text and parameters for one run from a pre-built values array, the same array a QueryBuilder holds.

public bool SetCommand(DbCommand cmd, object?[] variables)

Parameters

cmd DbCommand

The command to fill.

variables object[]

The values for this run, one slot per key.

Returns

bool

true when the command is ready to run.

SetCommand(IDbCommand, object?, Span<bool>)

Sets cmd's text and parameters for one run, reading the values from a parameter object matched to keys by name, and records which keys were used in usageMap.

public bool SetCommand(IDbCommand cmd, object? parameterObj, Span<bool> usageMap)

Parameters

cmd IDbCommand

The command to fill.

parameterObj object

The object whose members supply the values.

usageMap Span<bool>

Filled with which keys ended up used, so the result can be read back correctly.

Returns

bool

true when the command is ready to run.

SetCommand(IDbCommand, object?[])

Sets cmd's text and parameters for one run from a pre-built values array, the same array a QueryBuilder holds.

public bool SetCommand(IDbCommand cmd, object?[] variables)

Parameters

cmd IDbCommand

The command to fill.

variables object[]

The values for this run, one slot per key.

Returns

bool

true when the command is ready to run.

SetCommand<T>(DbCommand, T, Span<bool>)

Sets cmd's text and parameters for one run, reading the values from a parameter object matched to keys by name, and records which keys were used in usageMap.

public bool SetCommand<T>(DbCommand cmd, T parameterObj, Span<bool> usageMap) where T : notnull

Parameters

cmd DbCommand

The command to fill.

parameterObj T

The object whose members supply the values.

usageMap Span<bool>

Filled with which keys ended up used, so the result can be read back correctly.

Returns

bool

true when the command is ready to run.

Type Parameters

T

SetCommand<T>(DbCommand, ref T, Span<bool>)

Sets cmd's text and parameters for one run, reading the values from a parameter object matched to keys by name, and records which keys were used in usageMap.

public bool SetCommand<T>(DbCommand cmd, ref T parameterObj, Span<bool> usageMap) where T : notnull

Parameters

cmd DbCommand

The command to fill.

parameterObj T

The object whose members supply the values.

usageMap Span<bool>

Filled with which keys ended up used, so the result can be read back correctly.

Returns

bool

true when the command is ready to run.

Type Parameters

T

SetCommand<T>(IDbCommand, T, Span<bool>)

Sets cmd's text and parameters for one run, reading the values from a parameter object matched to keys by name, and records which keys were used in usageMap.

public bool SetCommand<T>(IDbCommand cmd, T parameterObj, Span<bool> usageMap) where T : notnull

Parameters

cmd IDbCommand

The command to fill.

parameterObj T

The object whose members supply the values.

usageMap Span<bool>

Filled with which keys ended up used, so the result can be read back correctly.

Returns

bool

true when the command is ready to run.

Type Parameters

T

SetCommand<T>(IDbCommand, ref T, Span<bool>)

Sets cmd's text and parameters for one run, reading the values from a parameter object matched to keys by name, and records which keys were used in usageMap.

public bool SetCommand<T>(IDbCommand cmd, ref T parameterObj, Span<bool> usageMap) where T : notnull

Parameters

cmd IDbCommand

The command to fill.

parameterObj T

The object whose members supply the values.

usageMap Span<bool>

Filled with which keys ended up used, so the result can be read back correctly.

Returns

bool

true when the command is ready to run.

Type Parameters

T

TryGetCachedParser(Type, object?[], out ITypeParser, int)

Gets a cached parser for a runtime result type and parameter values.

public bool TryGetCachedParser(Type type, object?[] usageMap, out ITypeParser parser, int resultSetIndex = 0)

Parameters

type Type

usageMap object[]

parser ITypeParser

resultSetIndex int

Returns

bool

TryGetCachedParser(Type, Span<bool>, out ITypeParser, int)

Gets a cached parser for a runtime result type and parameter usage.

public bool TryGetCachedParser(Type type, Span<bool> usageMap, out ITypeParser parser, int resultSetIndex = 0)

Parameters

type Type

usageMap Span<bool>

parser ITypeParser

resultSetIndex int

Returns

bool

TryGetCachedParser<T>(object?[], out ITypeParser<T>, int)

Gets a parser held for the supplied parameter values and result set.

public bool TryGetCachedParser<T>(object?[] usageMap, out ITypeParser<T> parser, int resultSetIndex = 0)

Parameters

usageMap object[]

parser ITypeParser<T>

resultSetIndex int

Returns

bool

Type Parameters

T

TryGetCachedParser<T>(Span<bool>, out ITypeParser<T>, int)

Gets a parser held for the supplied parameter usage and result set.

public bool TryGetCachedParser<T>(Span<bool> usageMap, out ITypeParser<T> parser, int resultSetIndex = 0)

Parameters

usageMap Span<bool>

parser ITypeParser<T>

resultSetIndex int

Returns

bool

Type Parameters

T

UpdateCache(IDbCommand)

Reads parameter details from cmd and stores them for later runs. Call this after execution when a custom command needs to teach this command its parameter details.

public void UpdateCache(IDbCommand cmd)

Parameters

cmd IDbCommand

UpdateCacheAsync(IDbCommand, CancellationToken)

Learns from a command that has just run.

public Task UpdateCacheAsync(IDbCommand cmd, CancellationToken ct = default)

Parameters

cmd IDbCommand

ct CancellationToken

Returns

Task

UpdateParamCache(int, DbParamInfo)

Sets the database details for one parameter by its zero based index. Use this for parameters that are bound by position.

public bool UpdateParamCache(int variableIndex, DbParamInfo paramInfo)

Parameters

variableIndex int

paramInfo DbParamInfo

Returns

bool

true if variableIndex names a bindable parameter.

UpdateParamCache(string, DbParamInfo)

Sets the database details for one parameter. Use this when the required type or size cannot be inferred from a value.

public bool UpdateParamCache(string paramName, DbParamInfo paramInfo)

Parameters

paramName string

paramInfo DbParamInfo

Returns

bool

true if paramName names a bindable parameter.

UpdateParseCache(bool[], ITypeParser, int)

Stores a runtime parser in this command's existing parser cache.

public void UpdateParseCache(bool[] usageMap, ITypeParser cache, int resultSetIndex = 0)

Parameters

usageMap bool[]

cache ITypeParser

resultSetIndex int

UpdateParseCache<T>(bool[], ITypeParser<T>, int)

Stores a parser for the supplied parameter usage and result set.

public void UpdateParseCache<T>(bool[] usageMap, ITypeParser<T> cache, int resultSetIndex = 0)

Parameters

usageMap bool[]

cache ITypeParser<T>

resultSetIndex int

Type Parameters

T