Skip to content
Purview Dev logo

Backends: WSL Containers or Docker

Experimental Containers Reviewed 2026-11-11 purview-dev/containers Star on GitHub 3 azurite containers csharp docker dotnet integration-testing mysql nats nuget postgresql rabbitmq redis sql-server testcontainers testing windows wsl wsl-containers wslc

Experimental. This project is an experiment: the public API, defaults and packaging can change between prereleases, and there is no production support guarantee.

Purview.Containers has one API and two interchangeable backends. The same test code, the same service modules (Purview.Containers.PostgreSql, Redis, MsSql, RabbitMq, Azurite, Nats, MySql, AzureKeyVaultEmulator, AzureServiceBusEmulator), and the same connection-string accessors run on either runtime — you choose which one by the package you reference, and can override it in code or from the environment.

  • **Purview.Containers** — the umbrella: Core plus both backends, for one reference with automatic selection.
  • **Purview.Containers.Core** — the backend-neutral abstractions (the API you code against); usually arrives transitively.
  • **Purview.Containers.Wsl** — throwaway containers on Microsoft WSL Containers (WSLC), the Windows runtime with no Docker installation.
  • **Purview.Containers.Docker** — throwaway containers on any reachable Docker daemon, driven by Testcontainers.
Package Use it when
Purview.Containers The umbrella: Core + both backends. One reference, zero config — WSLC on Windows, Docker elsewhere (auto). Recommended default.
Purview.Containers.Core The backend-neutral abstractions (the API). Reference it explicitly with one or both backends when you want a minimal dependency surface; otherwise it arrives transitively.
Purview.Containers.Wsl WSL Containers only — a Windows dev machine with no Docker.
Purview.Containers.Docker Docker only — any platform, CI, Linux/macOS.

Service modules (Purview.Containers.PostgreSql, Redis, …) are backend-neutral: add any backend package (or the umbrella) alongside one to run it.

WSL Containers Docker
Package Purview.Containers.Wsl Purview.Containers.Docker
Prerequisite Windows 11 (22H2 or later) or Windows Server 2025 with WSL Containers (wsl --install --no-distribution) any reachable Docker daemon (Docker Desktop, Docker Engine in WSL2, a VM, or a CI runner)
Host OS Windows only Windows, Linux, macOS
Project target framework net10.0 or net11.0, any platform (portable facade), or net10.0-windows10.0.19041.0/net11.0-windows10.0.19041.0, x64 or arm64 (implementation bound directly) net10.0 or net11.0, any platform
How containers run the managed SDK, with wslc CLI fallback for SDK-missing features the Docker Engine API via Testcontainers
Images a shared store (%LOCALAPPDATA%\Purview\WslContainers\images) reused across runs; the location is configurable the daemon’s own image store
Leak protection session disposal plus a process-exit hook the Testcontainers resource reaper (Ryuk)
Disposal cleanup WithCleanUp (default true) stops and deletes the container WithCleanUp (default true) delegates to Testcontainers, which also removes anonymous volumes
Volume cleanup opt-in via ContainerCleanup.CleanUpVolumesOnExit / PURVIEW_CONTAINERS_CLEAN_VOLUMES; CleanUpVolumesOnTerminate overrides per runtime opt-in via the same shared switch; removes volumes the backend created
Check the host wsl --version, wslc version docker info
Typical fit local Windows development without Docker Desktop, fastest cold start CI runners, non-Windows hosts, teams already running Docker

Windows bind mounts with Docker Engine in WSL2

Section titled “Windows bind mounts with Docker Engine in WSL2”

When a Windows process connects to a Docker Engine inside a local WSL2 distribution over loopback TCP, the Docker backend automatically translates Windows drive paths in WithBindMount to paths in that distribution. No environment variable or code change is needed:

await using var container = new ContainerBuilder()
.WithImage("alpine:3.19")
.WithBindMount(@"P:\project\data", "/data", readOnly: true)
.Build();

The backend verifies the connected daemon’s identity against the engines in running WSL distributions, then asks the matching distribution’s wslpath to translate the source. It does not assume the default distribution or hard-code /mnt, so a custom drive mount root is honoured. Read-only and writable mounts, including single-file mounts, retain their requested access mode.

The owning distribution must have docker and wslpath available to its default user, and that user must be able to query the engine through /var/run/docker.sock. If no local daemon matches, sources are left unchanged rather than guessed. Docker Desktop, non-loopback remote daemons, native Linux paths and named volumes are unaffected. Once an engine is identified, a failed path translation is reported rather than silently sending an invalid Windows source to Linux.

This behaviour applies to containers created through Purview.Containers.Docker; it does not intercept other libraries or direct docker CLI invocations.

By default WSLC images are pulled once into a shared store under the local profile:

%LOCALAPPDATA%\Purview\WslContainers\images

To put the image store somewhere else — a different drive, a project-local cache, or a per-run folder — set the process-wide environment variable (works for every consumer shape, including a platform-neutral net10.0 or net11.0 facade):

Terminal window
$env:PURVIEW_CONTAINERS_STORAGE_PATH = 'D:\wslc-images' # PowerShell
Terminal window
export PURVIEW_CONTAINERS_STORAGE_PATH=/mnt/d/wslc-images # bash / WSL / CI

Or configure the backend in code:

using Purview.Containers;
using Purview.Containers.Wsl;
ContainerBackends.Use(new WslContainerBackend(WslContainerRuntimeOptions.Default with
{
StoragePath = @"D:\wslc-images",
StorageMode = StorageMode.Shared,
}));

StorageMode.Shared (the default) keeps a stable, warm image store at StoragePath (or the default above when it is unset); StorageMode.PerSession gives each session a throwaway store under %LOCALAPPDATA%\Purview\WslContainers\sessions\{name}. The full WslContainerRuntimeOptions set (CPU, memory, GPU, session name, StoragePath, StorageMode, timeout, CleanUpVolumesOnTerminate) is honoured on both a platform-neutral net10.0 or net11.0 consumer — where the facade forwards it to the Windows build at run time — and a Windows target framework. The pre-rename WSL_CONTAINERS_STORAGE_PATH is still honoured as a fallback.

WSLC named volumes are retained by default, matching Docker. Set ContainerCleanup.CleanUpVolumesOnExit = true (or PURVIEW_CONTAINERS_CLEAN_VOLUMES=true) to delete the volumes the library created when the process exits or the session terminates; WslContainerRuntimeOptions.CleanUpVolumesOnTerminate overrides the shared switch for one runtime, and CleanUpAsync performs the cleanup explicitly. Containers are deleted first; the shared image store and host bind mounts are untouched.

Switch between them without touching test code:

Section titled “Switch between them without touching test code:”
Terminal window
# auto (the default) | wsl | docker | <any registered backend name>
export PURVIEW_CONTAINERS_BACKEND=docker # bash / zsh / CI
Terminal window
$env:PURVIEW_CONTAINERS_BACKEND = 'wsl' # PowerShell

Each backend reports its own readiness, so a missing runtime is a clear message instead of a timeout deep inside a test.

WSL Containers:

Terminal window
wsl --version # WSL itself
wslc version # the WSLC runtime
using Purview.Containers.Wsl;
var info = await new WslContainerBackend().GetInfoAsync();
Console.WriteLine($"{info.Name}: usable={info.IsUsable} version={info.Version}");
if (!info.IsUsable)
{
Console.WriteLine(string.Join("; ", info.MissingComponents));
}

Docker:

Terminal window
docker info
using Purview.Containers.Docker;
var info = await new DockerContainerBackend().GetInfoAsync();
Console.WriteLine($"{info.Name}: usable={info.IsUsable} version={info.Version}");
if (!info.IsUsable)
{
Console.WriteLine(string.Join("; ", info.MissingComponents));
}

ContainerBackends.ProbeAllAsync() reports every registered backend at once, which is the quickest way to answer “what can this machine run?”:

foreach (var backend in await ContainerBackends.ProbeAllAsync())
{
Console.WriteLine($"{backend.Name}: usable={backend.IsUsable} version={backend.Version}");
}

The test body never names a backend, so it is identical on both runtimes:

using Purview.Containers;
using Purview.Containers.Waiting;
public class CacheTests
{
[Test]
public async Task Cache_IsReachableOnItsMappedPort()
{
await using var container = new ContainerBuilder()
.WithImage("redis:7")
.WithPortBinding(6379, assignRandomHostPort: true)
.WithWaitStrategy(Wait.ForTcpPort(6379))
.Build();
await container.StartAsync();
ushort port = container.GetMappedPublicPort(6379);
await Assert.That(port).IsGreaterThan((ushort)0);
}
}

The package reference decides which runtime executes it. Three project shapes cover every case.

Terminal window
dotnet add package Purview.Containers.Wsl
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework><!-- WSLC only -->
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.1" />
</ItemGroup>
</Project>

This project runs WSLC on a Windows host. A platform-neutral net10.0 or net11.0 project binds the portable facade; a Windows target framework (net10.0-windows10.0.19041.0 or net11.0-windows10.0.19041.0, x64 or arm64) binds the implementation directly. WindowsSdkPackageVersion is supplied by the package. A project older than .NET 10 (including .NET 8 and .NET 9) fails the build with PCC0001, and a 32-bit Windows consumer with PCC0002; see Consumer Requirements.

On a non-Windows host this project has no usable backend (the facade reports wsl unavailable). To also run on Docker there, add Purview.Containers.Docker or use the umbrella — see Option 3.

Terminal window
dotnet add package Purview.Containers.Docker
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.Docker" Version="1.0.0-prerelease.1" />
</ItemGroup>
</Project>

That project restores and builds on Linux, macOS and Windows — no Windows target framework, no WindowsSdkPackageVersion, no Docker Desktop licence requirement beyond the daemon you already run.

Section titled “Option 3 — both backends, automatic selection (recommended)”

Add the umbrella Purview.Containers: it brings Core plus both backends, so auto selects WSLC on a machine that can run it and Docker otherwise — no multi-targeting and no conditional references:

Terminal window
dotnet add package Purview.Containers
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework><!-- WSLC on Windows, Docker elsewhere -->
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers" Version="1.0.0-prerelease.1" />
</ItemGroup>
</Project>

auto probes the registered backends in priority order (wsl before docker) and uses the first that is usable, so this one project runs on WSLC on a developer’s Windows machine and on Docker in a Linux CI job. A Windows target framework is still supported when you want the implementation bound at compile time, but it is not required.

Prefer the explicit form? Reference Purview.Containers.Core plus both backends instead of the umbrella:

Terminal window
dotnet add package Purview.Containers.Core
dotnet add package Purview.Containers.Wsl
dotnet add package Purview.Containers.Docker

If your code needs a Windows-only API the portable facade does not expose (for example WslContainer, or WslContainerBackend(runtime) to pin a specific WSLC session), guard it with #if WINDOWS — defined by the SDK only for a Windows target framework — so a portable target still compiles:

#if WINDOWS
using Purview.Containers.Wsl;
#endif
// ...
#if WINDOWS
var backend = new WslContainerBackend(runtimeForIsolation);
#else
var backend = new DockerContainerBackend();
#endif

A module is backend-neutral, so only the backend package line changes:

Terminal window
dotnet add package Purview.Containers.PostgreSql # the module
dotnet add package Purview.Containers # ...or Purview.Containers.Wsl / Purview.Containers.Docker
using Npgsql;
using Purview.Containers.PostgreSql;
await using var postgres = new PostgreSqlBuilder()
.WithDatabase("tests")
.WithUsername("postgres")
.WithPassword("postgres")
.Build();
await postgres.StartAsync(); // ready when pg_isready succeeds, on either backend
await using var connection = new NpgsqlConnection(postgres.GetConnectionString());
await connection.OpenAsync();

Selection is resolved once per process, in this order:

# Rule How to set it Behaviour
1 Pinned instance ContainerBackends.Use(new DockerContainerBackend()), or WithBackend(...) on one builder used as-is: never probed, never substituted
2 Named backend PURVIEW_CONTAINERS_BACKEND=wsl|docker|<name>, or ContainerBackends.Use(ContainerBackendSelection.Named("docker")) probed; a missing or unusable backend fails with its own diagnostics and no fallback
3 Automatic detection the default (auto) every registered backend is probed in auto-priority order (wsl at 0, docker at 100); the first available and compatible one wins, so WSLC is preferred over Docker
using Purview.Containers;
// Automatic detection (the default)...
var container = new ContainerBuilder().WithImage("alpine:3.19").Build();
// ...or pin it for this builder only.
var pinned = new ContainerBuilder()
.WithBackend(new DockerContainerBackend())
.WithImage("alpine:3.19")
.Build();
// ...or pin it for the process.
ContainerBackends.Use(ContainerBackendSelection.Named("docker"));

Build() never needs a backend: it validates the configuration and returns a container that resolves the backend when it starts. That is what lets the same test suite run on whichever runtime the machine has.

To fail loudly instead of falling back — the usual choice in CI — name the backend:

PURVIEW_CONTAINERS_BACKEND=docker # if Docker is not reachable, the test fails and says why

A hosted Linux runner already has a Docker daemon, so nothing has to be started alongside your tests — reference Purview.Containers.Docker in a net10.0 test project and run dotnet test:

name: tests
on: [push, pull_request]
jobs:
integration-linux:
name: Integration tests (Docker)
runs-on: ubuntu-latest
env:
# Optional. "auto" (the default) also selects Docker when WSL Containers is absent.
PURVIEW_CONTAINERS_BACKEND: docker
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: 10.0.x
- run: dotnet restore
- run: dotnet build --configuration Release --no-restore
- run: dotnet test --configuration Release --no-build
  • On a Linux job, target a platform-neutral framework (net10.0 or net11.0). The WSL Containers package is portable — its net10.0 and net11.0 facades load the WSLC implementation on a Windows host and report wsl as unavailable elsewhere — so one test project can reference both backends and auto selects WSLC on a Windows developer machine and Docker on the Linux runner.
  • Keep your integration tests in their own project or category if you want the fast unit tests to stay runtime-free; both can run in the same job.
  • Pinning PURVIEW_CONTAINERS_BACKEND=docker makes a runner without a usable daemon fail loudly with the probe report instead of quietly selecting something else.

For a Windows job that should exercise WSLC, use a windows-2025 runner (Windows Server 2025 with nested virtualisation). The WSL build with wslc is in the pre-release channel and its directory is not on PATH:

integration-windows:
name: Integration tests (WSL Containers)
runs-on: windows-2025
timeout-minutes: 30
env:
PURVIEW_CONTAINERS_BACKEND: wsl
PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl
WSL_UTF8: "1"
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: 11.0.x
- name: Install WSL Containers
shell: pwsh
run: |
wsl --update --pre-release
wsl --version
$env:PATH = "C:\Program Files\WSL;$env:PATH"
& 'C:\Program Files\WSL\wslc.exe' version
- run: dotnet restore
- run: dotnet build --configuration Release --no-restore
- run: dotnet test --configuration Release --no-build --retry-failed-tests 2 --retry-failed-tests-delay 5s

windows-2025 is the only hosted runner that supports WSL Containers: Windows Server 2022 and Windows 10 are not supported. Windows runners bill at 2×, and a cold runner has to pull every image, so run the fast contract suite on pull requests and the full service-module matrix nightly or on demand. If you run on a self-hosted Windows runner instead, keep PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl so a host without WSLC fails rather than silently skipping every test.

Container integration tests depend on the host’s runtime. Retry at the test-project level with Microsoft.Testing.Platform’s retry extension rather than with an assembly-level attribute: install Microsoft.Testing.Extensions.Retry in the integration test project and pass --retry-failed-tests 2 --retry-failed-tests-delay 5s. A retry restarts the test host, so WSLC gets a fresh session and Testcontainers gets a fresh resource reaper, and the delay gives the previous host time to release its image-store VHD.

Capability WSL Containers Docker
Random host ports ✅ native (windowsPort=0) ✅ assigned by the daemon
Fixed host ports ✅ ✅
IPv6 host mapping ❌ IPv4 loopback only ✅
UDP port mappings ❌ ContainerNotSupportedException ✅
Bind mounts of host directories ✅ ✅
Named volumes ✅ (session VHD) ✅ (Docker volumes)
GPU exposure ✅ (EnableGPU session setting) depends on the daemon and host runtime
ExecOptions.WorkingDirectory / Timeout ✅ ✅
ExecOptions.Environment ✅ ✅
Entrypoint/user/labels, copy, builds ✅ CLI fallback ✅ Testcontainers
Networks/aliases, Linux capabilities, host loopback ✅ managed SDK (3.0.5) ✅ Testcontainers
Reuse session-scoped, explicit name Testcontainers reuse
Log tailing polled until the container stops polled until the container stops
Leak protection session disposal + process-exit hook Testcontainers resource reaper (Ryuk)
Disposal cleanup WithCleanUp, default true WithCleanUp, default true, anonymous volumes removed
Volume cleanup opt-in via ContainerCleanup.CleanUpVolumesOnExit (session override available) opt-in via the same shared switch
Image store shared WSLC store, warm across runs the daemon’s store
Lifetime cost one process-wide session, cheap start first pull per image, per daemon

Unsupported options throw ContainerNotSupportedException rather than being ignored, so a difference between backends never turns into a silently weaker test.

See Capabilities and Cancellation for shared APIs, managed deadlines, resource ownership and the synchronous-native-call cancellation limitation.

No container backend is registered. — no backend package is referenced by the test project (and the assembly that would register it was never loaded). Add one: dotnet add package Purview.Containers.Docker or dotnet add package Purview.Containers.Wsl.

No usable container backend was found (selection: auto). — every registered backend failed its probe; the report names each one and why:

No usable container backend was found (selection: auto).
wsl: unavailable (Sdk; SdkNeedsUpdate)
docker: unavailable (HttpRequestException: Connection refused)
Install or fix a backend, or set PURVIEW_CONTAINERS_BACKEND to one of: wsl, docker.

Fix the runtime it names (for WSLC: wsl --install --no-distribution; for Docker: start the daemon, or point DOCKER_HOST at it), or pin the backend that does work.

The selected container backend 'docker' is not usable: … — you named a backend that cannot run here. This is intentional: a named backend never falls back to another one, so a CI job cannot pass by silently using the wrong runtime.

The container backend 'docker' is not registered. Registered backends: wsl. — the selection names a backend whose package is not referenced by the project.

PCC0001 / PCC0002 — a build-time guard from the WSL Containers backend package: the consuming project is neither .NET 10 nor .NET 11 (Windows or platform-neutral), or is a 32-bit Windows consumer. See Consumer Requirements, or switch the project to the Docker backend.

The same image is pulled twice — expected when both runtimes are used: WSLC and Docker keep separate image stores.

  • Getting Started — install, first container, first typed module.
  • Consumer Requirements — the target-framework contract, the guards and the workarounds.
  • Architecture — how resolution and registration work internally.
  • Modules — the service modules and their readiness strategies.