# ADO.NET Extensions Reference

DynamORM exposes extension helpers mainly in:

- `DynamORM/DynamicExtensions.cs`
- `DynamORM/Helpers/DataReaderExtensions.cs`
- `DynamORM/Helpers/ReaderExtensions.cs`

## `IDbCommand` Extensions

## Connection and Transaction

- `SetConnection(this IDbCommand, IDbConnection)`
- `SetTransaction(this IDbCommand, IDbTransaction)`

These enable fluent command setup.

## `SetCommand` Overloads

Core overloads:

- `SetCommand(CommandType, int timeout, string text, params object[] args)`
- `SetCommand(int timeout, string text, params object[] args)`
- `SetCommand(CommandType, string text, params object[] args)`
- `SetCommand(string text, params object[] args)`
- `SetCommand(IDynamicQueryBuilder builder)`

Examples:

```csharp
cmd.SetCommand("SELECT * FROM users WHERE id = {0}", 19);
cmd.SetCommand(CommandType.StoredProcedure, "sp_DoWork");
cmd.SetCommand(builder);
```

## Parameter Helpers

Bulk:

- `AddParameters(DynamicDatabase, params object[] args)`
- `AddParameters(DynamicDatabase, ExpandoObject)`
- `AddParameters(DynamicDatabase, DynamicExpando)`

Single parameter helpers:

- `AddParameter(DynamicDatabase, object item)`
- `AddParameter(DynamicDatabase, string name, object item)`
- `AddParameter(IDynamicQueryBuilder, DynamicSchemaColumn? col, object value)`
- `AddParameter(IDynamicQueryBuilder, DynamicColumn item)`

Advanced overloads support explicit `ParameterDirection`, `DbType`, `size`, `precision`, `scale`.

Example:

```csharp
cmd.AddParameter("@Result", ParameterDirection.Output, DbType.String, 256, 0, 0, DBNull.Value);
cmd.AddParameter("@Name", DbType.String, 50, "Alice");
```

## Updating Existing Parameters

- `SetParameter(this IDbCommand, string parameterName, object value)`
- `SetParameter(this IDbCommand, int index, object value)`

## Execution and Conversion

- `ExecuteScalarAs<T>()`
- `ExecuteScalarAs<T>(defaultValue)`
- `ExecuteScalarAs<T>(TryParseHandler<T>)`
- `ExecuteScalarAs<T>(defaultValue, TryParseHandler<T>)`
- `ExecuteEnumeratorOf<T>(defaultValue, TryParseHandler<T>)`

These convert ADO.NET results to requested types with fallback behavior.

## Command Debugging

- `DumpToString()`
- `Dump(StringBuilder)`
- `Dump(TextWriter)`

Useful with `DynamicDatabase.DumpCommands` and custom log sinks.

## `IDataReader` and Row Helpers

From `DynamicExtensions.cs`:

- `ToList(this IDataReader)`
- `RowToDynamic(this IDataReader)`
- `RowToExpando(this IDataReader)`
- `RowToDynamic(this DataRow)`
- `RowToExpando(this DataRow)`
- upper-case variants (`RowToDynamicUpper`, `RowToExpandoUpper`)
- `GetFieldDbType(this IDataReader, int i)`

## Reader Caching

- `CachedReader(this IDataReader, int offset = 0, int limit = -1, Func<DynamicCachedReader, int, bool> progress = null)`

This creates an in-memory `DynamicCachedReader` snapshot.

## `DataReaderExtensions`

- `ToDataTable(this IDataReader, string name = null, string nameSpace = null)`

Converts current reader rows/schema to a `DataTable`.

## `ReaderExtensions` Null-Safe Accessors

Typed nullable access by column name:

- `GetBooleanIfNotNull`
- `GetByteIfNotNull`
- `GetCharIfNotNull`
- `GetDateTimeIfNotNull`
- `GetDecimalIfNotNull`
- `GetDoubleIfNotNull`
- `GetFloatIfNotNull`
- `GetGuidIfNotNull`
- `GetInt16IfNotNull`
- `GetInt32IfNotNull`
- `GetInt64IfNotNull`
- `GetStringIfNotNull`
- `GetValueIfNotNull`

Each method accepts an optional default value and returns it when DB value is null.

## `DynamicCachedReader`

`DynamicCachedReader` implements `IDataReader` and stores:

- schema metadata
- field names/types/ordinals
- full row cache (supports multi-result sets)

Construction options:

- `new DynamicCachedReader(IDataReader, offset, limit, progress)`
- `DynamicCachedReader.FromDynamicEnumerable(...)`
- `DynamicCachedReader.FromEnumerable<T>(...)`
- `DynamicCachedReader.FromEnumerable(Type, IEnumerable)`

Typical usage:

```csharp
using (var rdr = cmd.ExecuteReader())
using (var cached = rdr.CachedReader())
{
    while (cached.Read())
    {
        var row = cached.RowToDynamic();
    }
}
```

When to use it:

- You need disconnected reader semantics.
- You need multiple passes or deferred mapping.
- You need stable materialization before connection disposal.

Tradeoff:

- Higher memory use proportional to result size.