164 lines
4.2 KiB
Markdown
164 lines
4.2 KiB
Markdown
# 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.
|