DynamORM/docs/ado-net-extensions.md

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:

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:

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:

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.