Voyager.DBSafeCast 3.0.0

Voyager.DBSafeCast

DBNull-aware cast helpers for shuttling values between data readers / rows and CLR types, and back to DbParameter values via DBNull.Value sentinels.

Targets netstandard2.0 / net8.0 / net10.0. Strong-named.

Why

ADO.NET surfaces missing values as DBNull.Value, not null. Every read from IDataReader / DataRow has to disambiguate three states (null, DBNull, real value) before the value is usable as a CLR type. The reverse trip — turning a CLR Nullable<T> into a parameter — needs the same discipline. Writing if (reader.IsDBNull(i)) … else (int)reader[i] on every column gets old fast.

This library is two complementary families of one-liners that absorb the ceremony.

Install

dotnet add package Voyager.DBSafeCast

The public API lives in namespace System, so it's reachable without an explicit using — extension methods on object / Nullable<T> / string / Guid / byte[] resolve at call sites in DAL code without further setup.

Reading from a data source

using var reader = command.ExecuteReader();
while (reader.Read())
{
    int        id      = reader["Id"].Cast(0);                                 // extension
    Guid       trace   = reader["TraceId"].Cast(Guid.Empty);                   // extension
    string     name    = DBSafeCast.CastEmptyString(reader["Name"]);           // DBNull → ""
    DateTime?  closed  = DBSafeCast.CastNullableDateTime(reader["ClosedAt"]);  // DBNull → null
    byte[]?    payload = DBSafeCast.CastNullByteArray(reader["Payload"]);
}

Only Cast<T> and CastTimeSpan are extension methods on the read side; the typed CastNullable* / CastEmpty* / CastNull* helpers are regular static calls (DBSafeCast.X(value)). The write-side DBNullIF* family is all extension methods.

Cast<T> falls back to invariant-culture Parse when the source column is a string and T is decimal / int / long / byte — so a SQL column that comes back as text (legacy schema or varchar(MAX)) still yields a correctly-typed scalar without explicit handling.

Writing to a data source

command.Parameters.AddWithValue("@Id",       id.DBNullIF());                   // 0    → DBNull
command.Parameters.AddWithValue("@Name",     name.DBNullIFEmpty());            // ""   → DBNull
command.Parameters.AddWithValue("@ParentId", parentId.DBNullIF(0));            // 0/null → DBNull
command.Parameters.AddWithValue("@ClosedAt", closedAt.DBNullIFMin());          // MinValue/null → DBNull
command.Parameters.AddWithValue("@TraceId",  traceId.DBNullIF());              // Guid.Empty → DBNull
command.Parameters.AddWithValue("@Payload",  bytes.DBNullIF());                // null → DBNull

Every DBNullIF* returns object — either the underlying value or DBNull.Value — so it slots straight into AddWithValue / Value = / any other parameter slot that accepts object.

Runnable demo

dotnet run --project samples/BasicUsage

Walks through five typical patterns (scalar cast, nullable cast, sentinel collapse, IDataReader round-trip, DbParameter writes) against an in-memory DataTable — no SQL Server required.

Migration from 2.x to 3.x

Bump to 3.0 is breaking. Audit consumers for these specifically.

Target frameworks

net6.0 and net472 are gone. netstandard2.0 is in; it covers .NET Framework 4.6.2+ and any other runtime implementing netstandard2.0, so most .NET Framework consumers see no change. If you were pinned to net6, either upgrade the runtime or stay on Voyager.DBSafeCast 2.x.

Removed APIs

CastNullableString carried [Obsolete("Move to CastEmptyString")] since 2023; 3.0 finishes the job.

Changed behaviour

• Culture-invariant string parsing. Cast<int>("1234", 0) / Cast<long> / Cast<byte> now use CultureInfo.InvariantCulture. Before: int.Parse(string) with the process culture. On a Polish process culture this could land on the wrong number for strings containing group separators. Only decimal was correct before.
• CastTimeSpan(string) exception type. Bad inputs now throw FormatException (was IndexOutOfRangeException / OverflowException depending on the malformation). The new parser is TimeSpan.ParseExact(value, @"hh\:mm\:ss", InvariantCulture) — also stricter about the input shape: "12.34.56" was silently accepted before; it isn't now.
• DBNullIF(this string?, string def) comparison moved from string.Compare(.., ignoreCase: true) (current culture) to StringComparison.OrdinalIgnoreCase. ASCII case-folding identical; non-ASCII sentinel comparisons (Turkish-I etc.) may now match differently.

Source-compatible cleanups

• Predefined types normalised on the public surface (Byte[] → byte[], Int32? → int?, String → string, …). Source-compat.
• DBNullIF(this int? value, int def) now actually has this — previously it was a regular static method. ABI-safe; the modifier doesn't change the binary.
• Nullable annotations added: object? for inputs that accept null / DBNull, byte[]? / string? for outputs that return null. Consumers with Nullable=enable may see new flow-analysis warnings.

Infrastructure (no consumer-visible behaviour change)

• Strong-name key, namespace System placement, and the names of every surviving public method are unchanged. Existing call sites continue to compile without code edits.
• Embedded SourceLink: stepping into library source from a debugger now works out of the box.

License

MIT

Project roadmap

docs/adr/ADR-001-modernization-roadmap.md captures the eight-phase modernization plan that landed in 3.0 (build infra → editorconfig → code refactor → MinVer → CI/CD → tests → docs → optional Compass), with the rationale for each step and the alternatives that were rejected.