Skip to content
Purview Dev logo

Consumer Requirements

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.

Experimental. Purview.Containers.* is an experimental project: the public API, the defaults and these requirements can change between prereleases, and there is no production support guarantee. Treat every version as a preview and pin the exact package version you build against.

The WSL Containers backend package is multi-target. It ships Windows builds (net10.0-windows10.0.19041.0 and net11.0-windows10.0.19041.0, the implementations, built on the Microsoft.WSL.Containers projection) and platform-neutral builds (net10.0 and net11.0, facades). A Windows-targeting project binds the matching implementation directly; any other project binds the facade, which builds on every platform and, on a Windows host, loads the implementation at run time. That is what lets a net10.0 or net11.0 test project that references the WSL backend (or the umbrella Purview.Containers, which also brings Docker) run on WSLC on a developer’s Windows machine and on Docker in a Linux CI job with no configuration change. This page is the authoritative statement of that contract, of the workarounds that exist for it, and of how each of them is verified.

.NET 8 and .NET 9 are not supported. The lowest consumer is .NET 10, and a .NET 11 consumer binds the net11.0 assets, which are compiled with runtime-async=on and can use the .NET 11 library surface.

The WSLC SDK-only path keeps its existing prerequisites. Entry-point/user/label overrides, reuse, file copy and Dockerfile builds additionally require the installed wslc CLI on PATH; named networks, aliases, Linux capabilities and host loopback use the managed SDK (3.0.5+). The CLI operates in the SDK-owned session/store, not the user’s default CLI session. Missing CLI support fails explicitly, without switching backends. See Capabilities and Cancellation for operation deadlines, resource ownership and native cancellation limits.

Package Target framework Notes
Purview.Containers net10.0 and net11.0, any platform The umbrella: brings Purview.Containers.Core plus both backends. One reference; no target-framework requirement beyond .NET 10.
Purview.Containers.Core net10.0 and net11.0, any platform Backend-neutral abstractions (namespace Purview.Containers).
Purview.Containers.<Module> net10.0 and net11.0, any platform Service modules. Restore anywhere; needs a backend package to actually run.
Purview.Containers.Wsl net10.0, net11.0, net10.0-windows10.0.19041.0 and net11.0-windows10.0.19041.0 The WSL Containers backend: portable facades plus the Windows implementations. The requirements on this page are its contract.
Purview.Containers.Docker net10.0 and net11.0, any platform The Docker backend (Testcontainers). Needs a reachable Docker daemon, not a Windows target framework.
Purview.Containers.Environment net10.0 and net11.0, any platform Standalone Docker-compatible CLI bind-sharing resolver; no Aspire, Testcontainers or WSLC dependency.
Purview.Containers.Aspire net10.0 and net11.0, any platform Optional adapter requiring Aspire 13.6.5+ and the Environment package; no backend dependency.

The standalone resolver requires a reachable Linux-container daemon through its selected CLI, working credential helpers on PATH, and client write access to bind-source directories for verification markers. Preload alpine:3.19 offline or set CONTAINER_ENVIRONMENT_PROBE_IMAGE. Windows WSL fallback only queries already-running distributions; remote hosts require a genuinely shared filesystem and explicit CONTAINER_ENVIRONMENT_PATH_MAPPINGS. No snapshot fallback or endpoint rewriting is performed. See the resolver guide and Aspire guide. The portable package contracts are exercised by just verify-consumers cases 22 and 23.

Everything below describes the WSL Containers backend. A consumer of a different backend (for example Purview.Containers.Docker) needs only a portable net10.0 or net11.0 project: the abstractions and the service modules are portable assets. For how to use and switch between the backends, see Backends: WSLC or Docker.

For Windows bind mounts targeting a local WSL2 Docker Engine, the Docker backend automatically translates drive paths after verifying the daemon’s identity. No consumer configuration is required; the owning distribution’s default user must be able to run docker info against /var/run/docker.sock and use wslpath. See WSL2 bind mounts for the detection boundary.

Most projects need nothing at all: a net10.0 or net11.0 project binds the facade and gets automatic backend selection. A Windows-targeting project can be explicit:

<PropertyGroup>
<TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
<PlatformTarget>x64</PlatformTarget> <!-- or arm64 -->
<WindowsSdkPackageVersion>10.0.26100.80</WindowsSdkPackageVersion>
</PropertyGroup>

The last two lines are optional for most projects: the packages ship MSBuild defaults that supply them (see What the packages do for you). They are shown here because being explicit makes the requirements visible to the next person who reads your project file, and because the defaults only fill in a value when you have not chosen one.

# Requirement Why it exists
1 .NET 10 or .NET 11 Purview.Containers.Wsl ships lib/net10.0/ and lib/net11.0/ (facades) and lib/net10.0-windows10.0.19041/ and lib/net11.0-windows10.0.19041/ (implementations). Purview.Containers and the service modules ship lib/net10.0/ and lib/net11.0/ too. Anything older — including .NET 8 and .NET 9 — is unsupported.
2 A Windows-specific target framework that names the OS version (net10.0-windows10.0.19041.0 or net11.0-windows10.0.19041.0) — only when you want the implementation bound directly; a platform-neutral project binds the facade and still runs WSLC on a Windows host The Microsoft.WSL.Containers projection only ships Windows assets. net10.0-windows on its own is not enough.
3 64-bit (PlatformTarget x64/arm64, or a matching RuntimeIdentifier) The native wslcsdk.dll ships for win-x64 and win-arm64 only.
4 WindowsSdkPackageVersion at least 10.0.26100.80 The projection is compiled against Microsoft.Windows.SDK.NET 10.0.26100.79; the pack the SDK resolves for a 10.0.19041.0 target framework is older.
5 A Windows 11 (22H2 or later) or Windows Server 2025 host with WSL Containers to actually run containers The library drives WSLC; it never installs or updates WSL for you. Windows 10 and Windows Server 2022 are not supported by WSL Containers.

Purview.Containers.Wsl ships net10.0 and net11.0 facades and net10.0-windows10.0.19041.0 and net11.0-windows10.0.19041.0 implementations, so it restores on any .NET 10+ project. A .NET 11 consumer binds the net11.0 assets, which are compiled with runtime-async=on; a .NET 10 consumer keeps the net10.0 assets. The repository’s own SDK is .NET 11 (global.json pins 11.0.100), but that is a build-time detail, not a consumer requirement.

2. A Windows-specific target framework (optional)

Section titled “2. A Windows-specific target framework (optional)”

The recommended choice is a platform-neutral target framework. It binds the portable facade and gives you the automatic “WSLC on a Windows machine, Docker everywhere else” behaviour:

<TargetFramework>net10.0</TargetFramework> <!-- portable facade; auto-selects WSLC or Docker -->
<TargetFramework>net11.0</TargetFramework> <!-- same, with the runtime-async assets -->

A Windows target framework binds the implementation directly (no run-time load):

<TargetFramework>net10.0-windows10.0.19041.0</TargetFramework> <!-- implementation; correct -->
<TargetFramework>net11.0-windows10.0.19041.0</TargetFramework> <!-- implementation; correct -->
<TargetFramework>net10.0-windows</TargetFramework> <!-- fails: platform version defaults to 7.0 -->

net10.0-windows resolves its platform version to 7.0, which is older than the 10.0.19041.0 the implementation was built against, so NuGet selects no compile assets for it. Always spell out the version. (The Microsoft.WSL.Containers package itself is net8.0-windows10.0.19041.0, which a net10.0-windows10.0.19041.0 or net11.0-windows10.0.19041.0 project consumes without issue.)

The native WSL Containers SDK is shipped for win-x64 and win-arm64 only. A 32-bit (x86) consumer builds but cannot load wslcsdk.dll at runtime, so the packages fail the build instead:

error PCC0002: Purview.Containers.Wsl requires a 64-bit (x64 or arm64) consumer ...

Microsoft.WSL.Containers 3.0.5’s projection references Microsoft.Windows.SDK.NET 10.0.26100.79. Targeting a Windows target framework (net10.0-windows10.0.19041.0 or net11.0-windows10.0.19041.0) resolves a lower pack (10.0.19041.x) by default and the compiler rejects the mismatch:

error CS1705: Assembly 'wslcsdkcs' ... uses 'Microsoft.Windows.SDK.NET' which has a higher
version than referenced assembly 'Microsoft.Windows.SDK.NET'

Pin 10.0.26100.80 (the nearest published version) as shown above. The packages set this default for you, so you only need it if you want to override the value deliberately.

The build requirements above are host-independent. Running containers needs a Windows 11 (22H2 or later) or Windows Server 2025 host with WSL Containers installed (wsl --install --no-distribution) — see Getting Started.

Purview.Containers.Wsl ships two buildTransitive MSBuild files. NuGet imports them for direct and transitive references, so a project that references the backend package directly — or through another project that does — gets them automatically.

A service module (Purview.Containers.PostgreSql, Redis, MsSql, RabbitMq, Azurite, Nats, MySql, AzureKeyVaultEmulator, AzureServiceBusEmulator) is backend-neutral and does not bring a backend, so reference the module and Purview.Containers.Wsl (or another backend package) to run it. Use Purview.Containers.Docker to run the same module on Docker, and PURVIEW_CONTAINERS_BACKEND to choose between them.

Package path Effect
buildTransitive/Purview.Containers.Wsl.props Defaults WindowsSdkPackageVersion to 10.0.26100.80 when the consumer has not set it, and registers the wsl backend.
buildTransitive/Purview.Containers.Wsl.targets For a Windows consumer: defaults PlatformTarget to x64 when it is unset (or AnyCPU) and no RuntimeIdentifier is selected, and fails the build with PCC0001/PCC0002 when the target framework or the platform cannot be supported. For a platform-neutral consumer: copies the Windows implementation payload (the implementation, the WSLC projection, its Windows SDK dependencies and the native SDK) into wslc/ next to the output on a Windows build host, so the facade can load it at run time.

A consumer therefore only has to choose a target framework — and the portable one is best, because it runs on WSLC locally and Docker in CI with no further configuration:

<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework> <!-- auto: WSLC on Windows, Docker elsewhere -->
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.PostgreSql" Version="1.0.0-prerelease.1" />
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.1" />
</ItemGroup>
</Project>

An explicit PlatformTarget, RuntimeIdentifier or WindowsSdkPackageVersion in the consumer always wins over these defaults.

Because buildTransitive assets are framework-agnostic, NuGet no longer reports NU1202 for an incompatible target framework: restore succeeds and the failure comes from the guard targets instead. That is deliberate — PCC0001 names the required target framework, whereas an empty compile-asset set only produces CS0246 errors in your own code.

Error Raised by Meaning Fix
PCC0001 the shipped guard target The consumer’s target framework is neither .NET 10/.NET 11 on Windows 10.0.19041.0+ nor a platform-neutral .NET 10/.NET 11 framework Retarget as above.
PCC0002 the shipped guard target The consumer is not 64-bit Remove your PlatformTarget, set it to x64/arm64, or choose a matching RuntimeIdentifier.
CS1705 the C# compiler WindowsSdkPackageVersion is older than the projection requires Set WindowsSdkPackageVersion to 10.0.26100.80 or later.
CS8012 the C# compiler A referenced assembly targets a different processor (seen when a consumer forces x86) Use a 64-bit consumer.
NETSDK1100 the .NET SDK A Windows-targeted project is being built on a non-Windows operating system Set EnableWindowsTargeting (see below).
CS0234/CS0246 for Microsoft.WSL/Purview types the C# compiler The package contributed no compile assets (an unsupported target framework, or an unverified escape hatch) Fix the target framework; PCC0001 explains the same problem with a clearer message.

Workaround: building on a non-Windows CI agent

Section titled “Workaround: building on a non-Windows CI agent”

net*-windows… projects can be restored, compiled and unit-tested on Linux or macOS, provided the build opts in:

<PropertyGroup>
<EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

Without it the SDK fails with NETSDK1100 (“To build a project targeting Windows on this operating system, set the EnableWindowsTargeting property to true”).

This is exactly how this repository’s own CI works: the shared purview-dev/build workflow runs on ubuntu-latest, so src/Directory.Build.props sets EnableWindowsTargeting=true and the pipeline is filtered to [Category=Unit]. See Testing.

What it does and does not do:

  • ✅ restores the Windows targeting packs and compiles net*-windows assemblies;
  • ✅ runs unit tests that never touch the WSLC runtime;
  • ❌ does not provide WSL Containers — the WSLC integration suites need a Windows host;
  • ❌ does not make wslcsdk.dll loadable; anything that opens a session must run on Windows.

Workaround: consuming from a project older than .NET 10

Section titled “Workaround: consuming from a project older than .NET 10”

There is none. A project that targets Windows but not .NET 10 (for example net8.0-windows10.0.19041.0) cannot use these packages, and the repository verifies that no escape hatch exists. .NET 8 and .NET 9 are explicitly dropped: they are not built, tested or documented, and PCC0001 rejects them.

The historical suggestion is AssetTargetFallback, which tells NuGet to consider an additional target framework for the project’s package references:

<PropertyGroup>
<TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
<AssetTargetFallback>net10.0-windows10.0.19041.0</AssetTargetFallback>
</PropertyGroup>

It does not work here. AssetTargetFallback is not applied to netcoreapp-family packages, so the package still contributes no compile assets and the build fails in your own code with CS0234/CS0246. PCC0001 fires as well.

Even if it did compile, it would not help: the lib/ assemblies target .NET 10, so they can only be loaded by a .NET 10+ runtime. A consumer would have to move to .NET 10 to run them anyway.

If you need this library from a project you cannot retarget, keep the container work in a small .NET 10+ test project (which can reference the older project) rather than trying to consume the packages from the older project.

Multi-targeting is no longer required for the WSL Containers backend: a platform-neutral net10.0 or net11.0 target binds the portable facade. If you multi-target for other reasons, reference the package unconditionally — every inner build is supported:

<PropertyGroup>
<TargetFrameworks>net10.0;net11.0;net10.0-windows10.0.19041.0</TargetFrameworks>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.1" />
</ItemGroup>

The Windows inner build binds the implementation; the portable inner builds bind the facade. The historical pattern — multi-targeting with the reference only on the Windows inner build — still works, because the package keeps net10.0-windows10.0.19041 and net11.0-windows10.0.19041 builds, but the condition is no longer needed.

just verify-consumers packs the solution and builds twenty-five throwaway consumer projects against the produced packages, asserting every claim on this page:

Case Consumer Expected outcome
01 .NET 11 + Windows with the documented settings builds; wslcsdk.dll copied to the output
02 …with a stale WindowsSdkPackageVersion CS1705
03 …with PlatformTarget=x86 PCC0002
04 …with no settings at all builds via the shipped buildTransitive defaults
05 a module package plus the WSL Containers backend, with no settings builds; wslcsdk.dll copied (the defaults are transitive through the backend)
06 net8.0-windows + AssetTargetFallback PCC0001 — .NET 8 is unsupported and the escape hatch does not work
07 net8.0-windows PCC0001 — below the .NET 10 floor
08 plain net11.0 (platform-neutral facade) builds; the wsl registration is generated
09 …with PlatformTarget=AnyCPU builds (corrected to x64)
10 the net11.0-windows shorthand (no OS version) PCC0001
11 multi-targeting with a conditional PackageReference builds
12 multi-targeting with an unconditional PackageReference builds (both inner builds are supported)
13 a net10.0 consumer of the portable abstractions builds
14 a net10.0 consumer of the Docker backend builds; the backend registration is generated into the consumer
15 a net10.0 consumer of a service module, with no backend package builds
16 a .NET 11 Windows consumer with both backends referenced builds; both registrations are generated
17 the documented backend example on WSL Containers builds
18 the documented backend example on Docker (net10.0) builds
19 a plain net10.0 consumer of the WSL Containers backend builds; the wsl registration is generated (the portable facade)
20 a net10.0 consumer of two modules with both backends (the auto shape) builds; both registrations are generated
21 a net10.0 consumer of modules with only the umbrella Purview.Containers builds; both registrations are generated (one reference)
22 a net10.0 consumer of the standalone environment resolver builds; no backend required
23 a net10.0 consumer of the Aspire adapter builds; no backend required
24 a plain net11.0 consumer of the WSL Containers backend builds; the wsl registration is generated (the runtime-async facade)
25 a net11.0 consumer of modules with only the umbrella Purview.Containers builds; both registrations are generated (one reference)

The script is scripts/verify-consumers.ps1 and it only writes to the temp folder. It needs network access (it restores transitive dependencies from nuget.org), so it is a local/CI-explicit step rather than part of the [Category=Unit] filter.

  • Getting Started — prerequisites and the first container.
  • Packaging — what each package contains, including the buildTransitive assets.
  • Testing — the Linux CI run, the unit filter and the serial WSLC rule.
  • Modules — the service modules that inherit these defaults.