Skip to content
Purview Dev logo

Containers

Experimental

Throwaway Linux containers for .NET integration tests — on WSL Containers with no Docker installation, or on Docker.

azurite containers csharp docker dotnet integration-testing mysql nats nuget postgresql rabbitmq redis sql-server testcontainers testing windows wsl wsl-containers wslc All topics →
Experimental. This project is an experiment: the public API, defaults and packaging can change between prereleases, and there is no production support guarantee. Read the documentation before adopting it.

The problem

A Testcontainers-style library for .NET with one API and two interchangeable backends: Microsoft WSL Containers (WSLC) with no Docker installation, or Docker through Testcontainers. Containers are created through backend-neutral abstractions (Purview.Containers.Core) and the backend is resolved at run time, so the same test code runs on WSLC (Purview.Containers.Wsl) or Docker (Purview.Containers.Docker) unchanged. The WSLC backend talks to the WSLC managed C# API directly — no wslc.exe, no docker CLI, no Docker.DotNet. Typed service modules add PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, and NATS, each with its own defaults, configuration, readiness wait strategy, and connection-string helper. The umbrella package Purview.Containers brings the abstractions plus both backends in a single reference.

From the repository

Testcontainers-style library for .NET (net10.0): run throwaway Linux containers in integration tests on Microsoft WSL Containers (WSLC) with no Docker install, or on Docker. Add one package, write your test code once: zero configuration between Windows dev (WSLC) and Linux CI (Docker). Seven service modules.

Why it became a project

Integration tests that use real infrastructure on Windows needed a Docker daemon installed and running first. WSL Containers makes the container runtime a Windows feature, so the same throwaway-container workflow could be built straight on its managed API — and the same abstractions could fall back to Docker wherever WSLC is not available, which is why the library grew a portable net10.0 facade and a Docker backend rather than staying Windows-only.

Acknowledgments

Containers builds on the work of others.

  • Testcontainers for .NET

    The Docker backend is driven by Testcontainers and the module connection-string shapes follow it; Purview.Containers is not affiliated with or endorsed by the Testcontainers project.

  • Microsoft WSL Containers

    The managed C# API behind WSLC that the WSL Containers backend is built against directly, with no wslc.exe or docker CLI.

Where it fits

Use it when

You want real PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, or NATS instances in integration tests, and you want the same suite to run on WSL Containers on a Windows developer machine and on Docker in CI without changing a line of test code.

It may not fit when

You need a container runtime other than WSL Containers or Docker, or you require API stability: the public API, defaults, and packaging rules can change between prereleases and there is no production support guarantee.

Use cases

Concrete examples of what Containers does, and who each one is for.

Developer

The same test on WSL Containers or Docker

Your integration suite needs real infrastructure, but the machines it runs on differ: a Windows developer laptop with WSL Containers and a Linux CI runner with a Docker daemon.

csharp
await using var container = new ContainerBuilder()
    .WithImage("docker.io/library/redis:latest")
    .WithPortBinding(6379, assignRandomHostPort: true)
    .WithWaitStrategy(Wait.ForTcpPort(6379))
    .Build();

await container.StartAsync();
ushort port = container.GetMappedPublicPort(6379);

What you get: The test never names a backend. Automatic selection prefers WSLC where it is usable and falls through to Docker everywhere else; PURVIEW_CONTAINERS_BACKEND pins one (wsl or docker) when a job should fail loudly instead of falling back.

One API, two backends: the same builder, wait strategies, and connection-string helpers run on both Purview.Containers.Wsl and Purview.Containers.Docker with no code change.

Read Backends: WSL Containers or Docker →
Developer

Zero-config tests that pick a backend themselves

You want real PostgreSQL and Redis in your tests and would rather not choose a container runtime, add a backend package explicitly, or write any registration or environment configuration.

csharp
await using var postgres = new PostgreSqlBuilder().WithDatabase("app").Build();
await postgres.StartAsync();                         // waits for pg_isready

await using var connection = new NpgsqlConnection(postgres.GetConnectionString());
await connection.OpenAsync();

What you get: Add the umbrella Purview.Containers to a plain net10.0 project: each backend package's buildTransitive assets generate the registration in your assembly, so WSLC is used on a Windows machine and Docker everywhere else with no code or configuration.

Each backend package ships buildTransitive assets that generate a module initializer in the consumer's assembly, so no registration line and no environment variable are required; those assets flow transitively through the umbrella.

Read Using it in your tests (auto) →
Developer

A typed service module instead of a bare image

You need a throwaway PostgreSQL (or Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS) and do not want to look up its image, port, environment, and readiness probe every time.

csharp
await using var postgres = new PostgreSqlBuilder()
    .WithDatabase("tests")
    .WithPassword("postgres")
    .Build();

await postgres.StartAsync();   // returns once pg_isready succeeds

What you get: The module supplies the default image, port mapping, and readiness wait strategy, so StartAsync() returns once the instance is genuinely ready, and GetConnectionString() points at the mapped host port — the same shape Testcontainers modules use.

Seven service modules ship (PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS), and a module contributes only its image, ports, environment, wait strategy, and connection string — never the shared runtime.

Read Modules →
Architect

One Windows prerequisite, Docker in CI

You want integration tests that use real infrastructure on Windows developer machines and CI agents, without making Docker Desktop a requirement of the minimum Windows toolchain.

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

What you get: The abstractions and modules are portable net10.0, so a platform-neutral project binds the WSLC facade on Windows and behaves as Docker-only everywhere else; ProbeAllAsync() reports exactly which runtime a machine has before a test runs.

Purview.Containers.Wsl ships a portable net10.0 facade and a net10.0-windows10.0.19041.0 implementation, and the repository builds twenty-one throwaway consumer projects to prove the target-framework contract and the PCC0001/PCC0002 guards.

Read Consumer Requirements →
Contributor

Add a service module

You want to add a module for another service, or fix one of the existing seven, and need to know exactly what a module is allowed to contribute.

What you get: A module supplies only the default image, ports, environment, its own WithXxx configuration, a wait strategy, and connection-string helpers; the generic builder snapshots the accumulated state into an immutable configuration, so modules never duplicate container runtime infrastructure.

Every module references Purview.Containers.Core only — never a backend package — which is what lets one module package run on WSLC or Docker, and each module has its own unit and integration test project to prove itself.

Read Contributing a module →

Packages

11 packages

Purview.ContainersnugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.AzuritenugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.CorenugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.DockernugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.MsSqlnugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.MySqlnugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.NatsnugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.PostgreSqlnugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.RabbitMqnugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.RedisnugetInstall ↓—1.0.0-prerelease.13—
Purview.Containers.WslnugetInstall ↓—1.0.0-prerelease.13—

Install

Purview.Containers primary

.NET CLI
dotnet add package Purview.Containers

Purview.Containers.Core

.NET CLI
dotnet add package Purview.Containers.Core

Purview.Containers.Wsl

.NET CLI
dotnet add package Purview.Containers.Wsl

Purview.Containers.Docker

.NET CLI
dotnet add package Purview.Containers.Docker

Purview.Containers.PostgreSql

.NET CLI
dotnet add package Purview.Containers.PostgreSql

Purview.Containers.Redis

.NET CLI
dotnet add package Purview.Containers.Redis

Purview.Containers.MsSql

.NET CLI
dotnet add package Purview.Containers.MsSql

Purview.Containers.MySql

.NET CLI
dotnet add package Purview.Containers.MySql

Purview.Containers.RabbitMq

.NET CLI
dotnet add package Purview.Containers.RabbitMq

Purview.Containers.Azurite

.NET CLI
dotnet add package Purview.Containers.Azurite

Purview.Containers.Nats

.NET CLI
dotnet add package Purview.Containers.Nats

Agent skills

Containers authors agent skills for coding agents. They are installed explicitly with the skills CLI and are not part of any package.

Skills are installed explicitly with the skills CLI. Nothing ships them inside a NuGet package, and no build writes into your agent's directories: installation is a decision you make. Use whichever package manager you already have.

npm

Terminal window
npx skills add purview-dev/containers

bun

Terminal window
bunx skills add purview-dev/containers

pnpm

Terminal window
pnpm dlx skills add purview-dev/containers

yarn

Terminal window
yarn dlx skills add purview-dev/containers
  • Installs at project level by default. Add -g for a user-level install, or -a <agent> to target one agent.
  • To match the release you use, pin a commit or tag by appending #<ref> to any command above (for example npx skills add purview-dev/containers#<ref>).
  • The CLI records what it installed in skills-lock.json; restore it with the same runner:
Terminal window
npx skills experimental_install
  • purview-containers-capabilities

    Use when configuring Testcontainers-style capabilities on Purview.Containers Docker or WSLC: entrypoint, user, labels, exec overrides, file copy, resource mappings, one-shot exit waits, managed networks and DNS aliases, Dockerfile image builds, reusable containers, cancellation deadlines, and the WSLC SDK versus CLI capability boundary.

    1 file
  • purview-containers-consumer-requirements

    Use when a project consuming Purview.Containers will not build - PCC0001 or PCC0002, CS1705 for Microsoft.Windows.SDK.NET, CS0234/CS0246 for Microsoft.WSL types, NETSDK1100 on a Linux build agent - or when choosing the target framework and platform for a consumer of the WSL Containers backend.

    1 file
  • purview-containers-lifecycle

    Use when reasoning about a Purview.Containers container's lifecycle or readiness - StartAsync, StopAsync and DisposeAsync semantics, cleanup guarantees and why there is no restart, the Wait strategy family and started-versus-ready, and WSL Containers networking, port mapping and the default-bridge DNS limitations and managed network aliases.

    1 file
  • purview-containers-quickstart

    Use when adding throwaway containers to a .NET test suite with Purview.Containers - which package to reference, how the WSL Containers and Docker backends are selected automatically, running a generic container with ContainerBuilder, using a typed service module, and getting a connection string.

    1 file
  • purview-containers-testing

    Use when organising or running a test suite that uses Purview.Containers - the Unit and Integration tiers, why test modules must run serially under WSL Containers, pinning or skipping a backend, running Docker and WSLC contract suites in hosted CI and the full WSLC matrix, and verifying the consumer contract.

    1 file