Expand docs with syntax/procedure deep dive and ADO.NET extensions

2026-02-26 07:57:45 +01:00
parent 984870f510
commit 2c25e78bef
5 changed files with 342 additions and 0 deletions
--- a/docs/ado-net-extensions.md
+++ b/docs/ado-net-extensions.md
@@ -0,0 +1,163 @@
+# 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.