SqlCommandDto & Related Types

SqlCommandDto is the standard Data‑Transfer Object used to describe a SQL command in the Maestro framework. It carries the command text, timeout, type, connection string, and a collection of parameters. Two supporting types – SqlCommandParameterDtoCollection and SqlCommandParameterDto – make it safe and convenient to build parameterised queries.

SqlCommandDto

Represents a complete SQL command ready for execution.

Properties

Name	Type	Default	Description
`CommandText`	`string?`	`null`	The SQL statement (`SELECT`, `INSERT`, `UPDATE`, etc.).
`CommandType`	`CommandType`	`Text`	Usually `Text`; set to `StoredProcedure` when calling a stored procedure.
`Parameters`	`SqlCommandParameterDtoCollection`	Empty collection	All SQL parameters to merge into the command.

SqlCommandParameterDto

Describes a single SQL parameter that will be safely sent to the database.

Properties

Name	Type	Description
`ParameterName`	`string?`	The parameter name (e.g., `"@@MinSales"`). If it doesn’t start with @@, the collection automatically prefixes it.
`ParameterValue`	`object?`	The value that will be sent to the server. Can be `null`.
`SqlDbType`	`SqlDbType`	The SQL Server data type (e.g., `NVarChar`, `Int`, `Decimal`, `Bit`).
`Size`	`int?`	Optional size for variable‑length types like `NVarChar`.
`IsNullable`	`bool?`	Allows explicit control over nullability of the ADO.NET parameter.

SqlCommandParameterDtoCollection

A strongly‑typed list that enforces unique, normalised parameter names. It provides several Add overloads for ease of use, plus typed helpers for common data types.

All parameter names are automatically normalised: leading and trailing whitespace is removed, and a missing @@ prefix is added. Duplicate names throw an InvalidOperationException.

Add(SqlCommandParameterDto param)

Adds an already‑constructed parameter object. The parameter name is normalised automatically.

cmd.Parameters.Add(new SqlCommandParameterDto
{
    ParameterName = "Id",
    ParameterValue = 123,
    SqlDbType = SqlDbType.Int
});

Add(string name, object? value, SqlDbType dbType, int? size, bool? isNullable)

Adds a parameter with full control over type, size, and nullability. The name is normalised automatically.

cmd.Parameters.Add("Id", 123, SqlDbType.Int, null, false);

AddInt(string name, int? value, bool? isNullable = null)

Shorthand for adding an integer parameter. SqlDbType.Int is set automatically.

cmd.Parameters.AddInt("Age", 30);

AddString(string name, string? value, int? size = null, bool? isNullable = null)

Shorthand for adding a string parameter. SqlDbType.NVarChar is set automatically. Provide a size for fixed‑width columns.

cmd.Parameters.AddString("Name", "John", 100);

AddBool(string name, bool? value, bool? isNullable = null)

Shorthand for adding a boolean (bit) parameter. SqlDbType.Bit is set automatically.

cmd.Parameters.AddBool("IsActive", true);

Complete Example

Building a parameterised query with a mix of convenience methods:

// Build a complete SqlCommandDto
SqlCommandDto cmd = new SqlCommandDto
{
    CommandText = @"SELECT Id, Name, Age, IsActive
                    FROM QS.Customers
                    WHERE Age > @MinAge AND IsActive = @Active",
    CommandType = CommandType.Text,
    CheckSafety = true,
    SkipCRUDOperations = false
};

// Use typed convenience methods
cmd.Parameters.AddInt("MinAge", 25);
cmd.Parameters.AddBool("Active", true);

// Or the full Add overload for more control
cmd.Parameters.Add("Name", "John%", SqlDbType.NVarChar, size: 100, isNullable: true);

// Execute via QSAppContext
DataTable dt = await QSAppContext.ExecuteSelectCommandToDataTableAsync(cmd);