Net4x.DapperLibrary.MockSqlServer 1.9.9.8

DapperLibrary.MockSqlServer

Lightweight helpers to create and use a mocked SQL Server IDapperContext for tests and local development. This project provides a small framework around LocalDB (and optional Docker-based SQL Server containers on modern runtimes) to obtain IDapperContext instances backed by a file-based or ephemeral SQL Server instance.

Purpose

Make it easy to spin up a disposable or reusable SQL Server instance for unit and integration tests and to obtain a corresponding IDapperContext preconfigured with SQL Server defaults used by the DapperLibraries.

Features

• Create or attach a LocalDB .mdf database and return a configured IDapperContext.
• Optionally reuse a single database file across tests via the ReuseDb flag to speed test runs.
• Support for using Docker-based SQL Server containers on modern runtimes (Testcontainers) � enabled under NET6_0_OR_GREATER compilation.
• Automatic configuration of DatabaseModel defaults for SQL Server (identity initializer and datetime literal formatting).
• Helpers to create/drop/attach/detach databases programmatically.

Key types

• MockedSqlDapperContext / MockedSqlDapperContext<TSqlDapperContext>

  • Primary entry point for consumers. Provides convenience static methods and properties that wrap an internal MockedSqlUseDapperContext instance.
  • Exposes GetInstance() overloads to obtain a ready-to-use IDapperContext (optionally accepting a logger and a custom path).
  • Exposes Use() and UseOnce() methods that populate the global DapperContextFactory ContextCreator so application code can request contexts via factory APIs.
  • Runtime-specific behavior: on modern runtimes it implements IDisposable / IAsyncDisposable to release Docker containers.

• MockedSqlUseDapperContext

  • Internal helper that encapsulates the logic used by MockedSqlDapperContext to provision LocalDB instances or to fall back to Docker containers when requested.
  • Tracks flags such as ReuseDb, UseMaster and UseDocker to modify provisioning behavior.

• LocalDbEnsurerInternal<T> and LocalDbInternal<T>

  • Responsible for creating and ensuring LocalDB instances exist, creating .mdf files, attaching/detaching databases, and returning an opened SqlConnection or IDapperContext rooted at the LocalDB instance.
  • LocalDbInternal contains helpers to create, drop and detach databases, and to map file paths used for created databases.

Usage examples

Obtain a context for tests:

// Simple: get an IDapperContext backed by LocalDB
using var context = MockedSqlDapperContext.GetInstance();

// Get instance with a logger
var ctx = MockedSqlDapperContext.GetInstance(myLogger);

// Get instance using a specific file path
var ctx2 = MockedSqlDapperContext.GetInstance(myLogger, "C:\\temp\\testdb.mdf");

Control reuse and lifecycle:

// When true, the same .mdf file may be reused across calls to speed up tests
MockedSqlDapperContext.ReuseDb = true;

// When false, each call will dispose any reused context and create a fresh database
MockedSqlDapperContext.ReuseDb = false;

// When false, a non-master database file will be used per GetInstance() call
MockedSqlDapperContext.UseMaster = false;

Register context creation for code that consumes the DapperContextFactory:

// Register the context creator so code calling DapperContextFactory.Instance.CreateContext() gets a mocked context
MockedSqlDapperContext.Use();

// Register once (adds a disposal handler)
MockedSqlDapperContext.UseOnce();

Docker support (modern runtimes only):

// On .NET 6+ you can opt into using Testcontainers if LocalDB is not available
MockedSqlDapperContext.UseDapperContext.UseDocker = true;
var ctx = MockedSqlDapperContext.GetInstance();

Multi-targeting notes

• The project includes conditional compilation to support multiple frameworks. LocalDB-based helpers target .NET Framework and older runtimes; Docker-based Testcontainers support is compiled under NET6_0_OR_GREATER.
• The repository contains different build outputs for net40/net45/net461 and modern targets; pick the appropriate compiled asset for your application runtime.

Behavior & best practices

• The code aims to avoid leaving dangling LocalDB files: when ReuseDb is disabled, the helper will attempt to clean up created .mdf and .ldf files when appropriate.
• Use UseMaster to control whether created databases are attached to the LocalDB master or created as separate files.
• For reliable integration tests in CI (where LocalDB may not be present), enable UseDocker on supported runtimes to provision a SQL Server container instead.
• Be mindful of permissions and available disk space when creating .mdf files.

Where to look in the codebase

• DbContexts/MockedSqlDapperContext.* � the high-level context wrappers used by tests.
• Internals/SqlServer/LocalDbEnsurerInternal.cs and LocalDbInternal.cs � LocalDB provisioning, creation, attach/detach and helper functions.
• Internals/MockedSqlUseDapperContext.cs � the glue between high-level APIs and the LocalDB/Docker provisioning logic.

This README summarizes usage and integration points. Inspect the source code and XML docs for detailed implementation and further customization.