From f3c00c186976703a7c49aef47cde8b0c9416e274 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Wed, 18 Nov 2026 14:44:01 +0000 Subject: [PATCH 01/14] build: move to Purview.BuildSdk 2.2.0 and the Supported framework set BuildSdk 2.2.0 makes runtime-async and the C# 15 updated memory-safety rules opt-in, so enable both explicitly for the net11.0 builds. Select the Supported target-framework set (net10.0;net11.0) repo-wide and derive the WSL backend's portable and Windows targets from it. Guard the memory-safety rules alongside runtime-async in BuildFeatureTests, and update the docs that described them as SDK defaults. Also bumps the purview.build and dotnet-inspect tools. --- .config/dotnet-tools.json | 4 +-- .editorconfig | 2 +- AGENTS.md | 22 +++++++------ docs/wiki/Architecture.md | 10 +++--- docs/wiki/Contributing.md | 7 +++-- global.json | 2 +- src/Directory.Build.props | 33 +++++++++++++++----- src/src/Directory.Build.props | 5 +-- src/src/Wsl/Wsl.csproj | 10 +++++- src/tests/Wsl.UnitTests/BuildFeatureTests.cs | 29 ++++++++++++++--- 10 files changed, 89 insertions(+), 35 deletions(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index bc9bc27..ec846e1 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -10,14 +10,14 @@ "rollForward": false }, "dotnet-inspect": { - "version": "0.27.0", + "version": "0.28.0", "commands": [ "dotnet-inspect" ], "rollForward": false }, "purview.build": { - "version": "0.9.0", + "version": "0.9.2", "commands": [ "purview-build" ], diff --git a/.editorconfig b/.editorconfig index a9b39cb..b0390ec 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,4 +1,4 @@ -# Purview.BuildSdk 2.0.0 - managed file, do not edit +# Purview.BuildSdk 2.2.0 - managed file, do not edit # # This file is written by Purview.BuildSdk and is replaced whenever the SDK version changes. The version # on the first line is how the SDK recognises a file it owns: a .editorconfig without that marker is diff --git a/AGENTS.md b/AGENTS.md index 2ee30fc..e90dfc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -131,20 +131,22 @@ whenever a target framework, a backend package or the `buildTransitive` assets c dropped): `Purview.Containers.Core` (abstractions) and the service modules target **`net10.0` and `net11.0`** on any platform. `Purview.Containers.Wsl` is **multi-target**: `net10.0`/`net11.0` (portable facades) and `net10.0-windows10.0.19041.0`/`net11.0-windows10.0.19041.0` (the WSLC implementations). - Purview.BuildSdk's `Current` target-framework set supplies the `net10.0;net11.0` list to the library - subtree, while `src/Directory.Build.props` pins that set to `net11.0-windows10.0.19041.0` for - `src/tests` so the WSLC tests bind the implementation; `Wsl.csproj` adds the Windows - builds with a platform-identifier condition (never a literal TFM). The Docker integration projects + `src/Directory.Build.props` selects Purview.BuildSdk's `Supported` target-framework set + (`PurviewTargetFrameworkSet=Supported`, `net10.0;net11.0` in BuildSdk 2.2.0) for every project that + declares no target of its own, and pins that set to `net11.0-windows10.0.19041.0` for `src/tests` so + the WSLC tests bind the implementation. `Wsl.csproj` derives its four targets from the same set (each + supported framework plus its `-windows10.0.19041.0` build) and selects files with a + platform-identifier condition (never a literal TFM). The Docker integration projects declare `net10.0` directly so they run on Linux **and** keep the lowest supported framework under test. The contract, the failures that enforce it and the CI workarounds are documented in [Consumer Requirements](docs/wiki/Consumer-Requirements.md); update that page whenever a target framework, the `buildTransitive` defaults, the payload layout or the `PCC0001`/`PCC0002` guards change. -- The `net11.0` library builds are compiled with `runtime-async=on` (`PurviewRuntimeAsync=false` opts out): - Purview.BuildSdk applies it to every `net11.0`+ target together with the C# 15 - `updated-memory-safety-rules` tier (`MemorySafetyRules=2`), so the repository does not repeat either - switch. The runtime manages suspension instead of compiler-generated state machines, which lowers async - overhead and makes live stack traces name the real methods. `Wsl.UnitTests/BuildFeatureTests.cs` guards - it. The `net10.0` builds keep the classic state machines. Because `closed` hierarchies require +- The `net11.0` builds are compiled with `runtime-async=on` and the C# 15 + `updated-memory-safety-rules` tier. Purview.BuildSdk 2.2.0 makes both **opt-in**, so + `src/Directory.Build.props` sets `PurviewRuntimeAsync=true` and `MemorySafetyRules=2` explicitly; do not + remove them. The runtime manages suspension instead of compiler-generated state machines, which lowers + async overhead and makes live stack traces name the real methods. `Wsl.UnitTests/BuildFeatureTests.cs` + guards both. The `net10.0` builds keep the classic state machines. Because `closed` hierarchies require `System.Runtime.CompilerServices.IsClosedTypeAttribute` and C# unions require `UnionAttribute` (both .NET 11 runtime types), neither is used: no public hierarchy here is closed anyway — `WaitStrategy`, `ContainerException` and the backend interfaces are documented extension points. diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md index 9d66cfb..8a4d034 100644 --- a/docs/wiki/Architecture.md +++ b/docs/wiki/Architecture.md @@ -53,16 +53,18 @@ Microsoft types (`Session`, `Container`, `Process`, `ContainerSettings`, …) ar ## Target frameworks Every package ships `net10.0` and `net11.0` assets. **.NET 8 and .NET 9 are dropped**; the contract is in -[Consumer Requirements](Consumer-Requirements.md). Purview.BuildSdk's `Current` target-framework set -supplies that pair; the repository does not hand-maintain it. +[Consumer Requirements](Consumer-Requirements.md). Purview.BuildSdk's `Supported` target-framework set +(selected in `src/Directory.Build.props`) supplies that pair; the repository does not hand-maintain it, +and the WSL backend derives its Windows builds from the same set. - `net10.0` is the floor. A consumer that has not moved to .NET 11 keeps the classic compiler-generated async state machines and the .NET 10 library surface. - `net11.0` is compiled with `runtime-async=on` and the C# 15 updated memory-safety rules (`MemorySafetyRules=2`). The runtime manages suspension and resumption instead of compiler-generated state machines, which lowers async overhead and makes live stack traces (profiler, `new StackTrace()`, - debugger) name the real methods. `PurviewRuntimeAsync=false` opts out for a local experiment; - `Wsl.UnitTests/BuildFeatureTests.cs` guards that the shipped default is on. + debugger) name the real methods. Purview.BuildSdk 2.2.0 makes both features opt-in, so + `src/Directory.Build.props` enables them (`PurviewRuntimeAsync=true`, `MemorySafetyRules=2`); + `Wsl.UnitTests/BuildFeatureTests.cs` guards that both are on in the shipped build. - The WSL Containers backend uses the same split for its Windows builds, and a single implementation payload serves both portable targets because a .NET 11 process loads a .NET 10 assembly. diff --git a/docs/wiki/Contributing.md b/docs/wiki/Contributing.md index b5160b2..a9a762a 100644 --- a/docs/wiki/Contributing.md +++ b/docs/wiki/Contributing.md @@ -7,9 +7,10 @@ request. - Windows with **WSL Containers** for integration tests; see [Getting Started](Getting-Started.md). - .NET SDK 11 (pinned in `global.json` as `11.0.100`). -- The library projects split by framework: Purview.BuildSdk's `Current` target-framework set gives the - backend-neutral abstractions and the service modules `net10.0;net11.0` (the `net11.0` build adds - `runtime-async=on` and the C# 15 updated memory-safety rules). +- The library projects split by framework: Purview.BuildSdk's `Supported` target-framework set + (selected in `src/Directory.Build.props`) gives the backend-neutral abstractions and the service + modules `net10.0;net11.0` (the `net11.0` build adds `runtime-async=on` and the C# 15 updated + memory-safety rules, both opted into explicitly in `src/Directory.Build.props`). `src/src/Wsl/Wsl.csproj` is multi-target (`net10.0`/`net11.0` facades plus `net10.0-windows10.0.19041.0`/`net11.0-windows10.0.19041.0` implementations) because the WSL Containers projection is Windows-only. `src/tests` pins the same set to diff --git a/global.json b/global.json index a12bdeb..4a0ba47 100644 --- a/global.json +++ b/global.json @@ -5,7 +5,7 @@ "allowPrerelease": false }, "msbuild-sdks": { - "Purview.BuildSdk": "2.0.0" + "Purview.BuildSdk": "2.2.0" }, "test": { "runner": "Microsoft.Testing.Platform" diff --git a/src/Directory.Build.props b/src/Directory.Build.props index f8d7df9..3a67fdc 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -3,17 +3,36 @@ Purview.Containers true + Supported <_PurviewIsTestSubtree Condition="$([System.String]::Copy('$(MSBuildProjectDirectory)').Replace('\', '/').Contains('/src/tests/'))" >true - net11.0-windows10.0.19041.0 + net11.0-windows10.0.19041.0 + + true + 2 x64 10.0.26100.80 true diff --git a/src/src/Directory.Build.props b/src/src/Directory.Build.props index 80c534b..84b0486 100644 --- a/src/src/Directory.Build.props +++ b/src/src/Directory.Build.props @@ -6,8 +6,9 @@ net10.0 and net11.0: .NET 10 is the lowest consumer that is still supported (.NET 8 and .NET 9 are deliberately dropped), and the net11.0 build lets a .NET 11 consumer bind the .NET 11 assembly instead (runtime-async compilation, .NET 11 library APIs and C# 15 features). That list - is Purview.BuildSdk's `Current` target-framework set - the default when a project declares no - target of its own - so this file must not restate it. Only the WSL Containers backend is + is Purview.BuildSdk's `Supported` target-framework set, selected in the parent + src/Directory.Build.props for every project that declares no target of its own, so this file + must not restate it. Only the WSL Containers backend is Windows-only, so it adds its own Windows target frameworks in its project file. The parent Directory.Build.props still owns the repo-wide identity (NamespacePrefix), the SDK diff --git a/src/src/Wsl/Wsl.csproj b/src/src/Wsl/Wsl.csproj index 39aefdc..866d048 100644 --- a/src/src/Wsl/Wsl.csproj +++ b/src/src/Wsl/Wsl.csproj @@ -19,9 +19,17 @@ platform-neutral consumer gets the facade. The approach rests on the extracted and tested result that the WSLC projection is a net8.0-windows asset loadable by a net10.0 or net11.0 process. + + The list is derived from Purview.BuildSdk's `Supported` set (selected in src/Directory.Build.props) + rather than restated: each supported framework contributes its portable build and its + -windows10.0.19041.0 build, so this package always targets exactly what the other packages do. + The payload target below and the pack manifest still name net10.0 (the lowest supported build) + and fail fast if the set moves. --> - net10.0;net10.0-windows10.0.19041.0;net11.0;net11.0-windows10.0.19041.0 + + $(PurviewTargetFrameworksSupported);$([MSBuild]::Unescape($(PurviewTargetFrameworksSupported.Replace(';', '-windows10.0.19041.0;'))))-windows10.0.19041.0 WSL Containers (WSLC) backend for Purview.Containers: run WSLC-native throwaway Linux containers from any .NET 10 or .NET 11 project, with automatic Docker fallback. wsl;wslc;containers;linux;windows;testing;integration;testcontainers MIT diff --git a/src/tests/Wsl.UnitTests/BuildFeatureTests.cs b/src/tests/Wsl.UnitTests/BuildFeatureTests.cs index 761cceb..cb8c103 100644 --- a/src/tests/Wsl.UnitTests/BuildFeatureTests.cs +++ b/src/tests/Wsl.UnitTests/BuildFeatureTests.cs @@ -5,13 +5,18 @@ namespace Purview.Containers.Wsl; /// /// Guards the build shape of the net11.0 assembly documented in -/// docs/wiki/Consumer-Requirements.md. The net11.0 build is compiled with -/// runtime-async=on (Purview.BuildSdk's PurviewRuntimeAsync default), which removes the -/// compiler-generated state machines: async methods carry no , -/// the runtime tracks suspension instead, and live stack traces name the real methods. +/// docs/wiki/Consumer-Requirements.md. Purview.BuildSdk 2.2.0 makes both .NET 11 features +/// opt-in, so src/Directory.Build.props enables them explicitly; these tests fail if that +/// opt-in is lost. /// public class BuildFeatureTests { + /// + /// PurviewRuntimeAsync=true compiles with runtime-async=on, which removes the + /// compiler-generated state machines: async methods carry no + /// , the runtime tracks suspension instead, and live stack + /// traces name the real methods. + /// [Test] public async Task Net11AssemblyUsesRuntimeAsync() { @@ -21,4 +26,20 @@ public async Task Net11AssemblyUsesRuntimeAsync() await Assert.That(stateMachine).IsNull(); } + + /// + /// MemorySafetyRules=2 compiles with the C# 15 updated-memory-safety-rules feature, + /// which marks the module with MemorySafetyRulesAttribute. + /// + [Test] + public async Task Net11AssemblyUsesUpdatedMemorySafetyRules() + { + var assembly = typeof(WslContainer).Assembly; + var marked = assembly + .ManifestModule.GetCustomAttributesData() + .Concat(assembly.GetCustomAttributesData()) + .Any(a => a.AttributeType.Name == "MemorySafetyRulesAttribute"); + + await Assert.That(marked).IsTrue(); + } } From efa2d8d3e20c103427b9327ad3d3479cabd893bc Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Wed, 18 Nov 2026 14:44:04 +0000 Subject: [PATCH 02/14] build(deps): bump dependencies to their latest releases Aspire.Hosting 17.0.0, Testcontainers 4.17.0, Microsoft.Extensions.Telemetry.Abstractions 11.0.0, Purview.Telemetry.SourceGenerator 6.0.1, SourceLink 11.0.100, TUnit 1.87.0 and the test-only clients. Every shipped dependency still ships a net10.0 asset, so the .NET 10 floor is unchanged. --- Directory.Packages.props | 36 +++++++++++++++--------------- README.md | 2 +- docs/wiki/Consumer-Requirements.md | 2 +- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/Directory.Packages.props b/Directory.Packages.props index 4534c24..9089c6d 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -29,7 +29,7 @@ 3.0.5 10.0.26100.80 - 1.76.0 + 1.87.0 @@ -38,20 +38,20 @@ .NET 10 servicing line on purpose: the .NET 8/.NET 9 lines are no longer supported, and a component declares the lowest band a consumer on the oldest supported framework can take. --> - + - + - + - - - + + + @@ -62,21 +62,21 @@ package is licensed under the Microsoft Testing Platform Tools terms, which permit use in OSI-approved open-source projects; it never ships in a Purview package. --> - - + + - - + + - + - - + + - - + + diff --git a/README.md b/README.md index a4be38a..46087aa 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ for inspection, and `.WithAutoRemove()` is opted into separately. See referencing the umbrella package, Testcontainers or WSLC. It verifies native paths, running WSL translations and explicit shared-remote mappings against the daemon using two-way file markers. `Purview.Containers.Aspire` adds opt-in `builder.AddContainerEnvironment()` integration for any -Aspire AppHost. Both target `net10.0` and `net11.0`; the adapter requires Aspire 13.6.5 or later. +Aspire AppHost. Both target `net10.0` and `net11.0`; the adapter requires Aspire 17.0.0 or later. These are separate from the existing Docker backend's automatic WSL2 path handling. Docker Engine inside a WSL distribution is not Microsoft WSL Containers. See the [environment package guide](src/src/Environment/Sdk/README.md) and diff --git a/docs/wiki/Consumer-Requirements.md b/docs/wiki/Consumer-Requirements.md index 22c2f4a..c5afdaa 100644 --- a/docs/wiki/Consumer-Requirements.md +++ b/docs/wiki/Consumer-Requirements.md @@ -35,7 +35,7 @@ for operation deadlines, resource ownership and native cancellation limits. | `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. | +| `Purview.Containers.Aspire` | `net10.0` and `net11.0`, any platform | Optional adapter requiring Aspire 17.0.0+ 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. From 38aba640117f2944c37dc7d0b909301294466b54 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Wed, 18 Nov 2026 15:03:02 +0000 Subject: [PATCH 03/14] fix: report a missing Docker daemon clearly and order the AutoSample build Testcontainers returns a null endpoint when no daemon is discovered, so every Docker call site failed with a bare NullReferenceException. Resolve it in one place (DockerEndpoint) and throw a ContainerBackendUnavailableException that says how to fix it; GetInfoAsync also names the endpoint on a timeout or refused ping. AutoSample copies Wsl's net10.0-windows output but nothing ordered that build first, so a parallel solution build could fail with "The Windows implementation is not built". Add a build-only project reference. --- .../AutoSample/AutoSample.csproj | 17 +++++++++ src/src/Docker/DockerContainer.cs | 13 ++----- src/src/Docker/DockerContainerBackend.cs | 38 ++++++++++++------- src/src/Docker/DockerEndpoint.cs | 34 +++++++++++++++++ src/src/Docker/DockerFileCopy.cs | 6 +-- src/src/Docker/DockerVolumeCleanup.cs | 4 +- src/src/Docker/WslDockerHost.cs | 8 ++-- 7 files changed, 85 insertions(+), 35 deletions(-) create mode 100644 src/src/Docker/DockerEndpoint.cs diff --git a/samples/getting-started/AutoSample/AutoSample.csproj b/samples/getting-started/AutoSample/AutoSample.csproj index 4b7fd83..52c2d7b 100644 --- a/samples/getting-started/AutoSample/AutoSample.csproj +++ b/samples/getting-started/AutoSample/AutoSample.csproj @@ -22,6 +22,23 @@ + + + + + - https://github.com/purview-dev/containers + + https://purview.dev/projects/containers/ From 0293f6e3e26db21579bc7a87aed53e9463143ce8 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Wed, 18 Nov 2026 15:03:16 +0000 Subject: [PATCH 06/14] docs: drop the experimental notices Remove the experimental, preview and no-support-guarantee notices from the README, wiki, package READMEs and skills. Versions stay on a -prerelease.N suffix until the stable 1.0.0, which includes the WSL Containers backend. Refresh stale version examples to prerelease.14 and describe the push-to-main build. --- AGENTS.md | 11 +++++--- README.md | 25 ++++++++----------- docs/wiki/Backends.md | 6 ++--- docs/wiki/Consumer-Requirements.md | 11 +++----- docs/wiki/Getting-Started.md | 3 --- docs/wiki/Home.md | 5 ---- docs/wiki/Release-Flow.md | 11 ++++---- docs/wiki/Using-in-Your-Tests.md | 6 ++--- skills/purview-containers-quickstart/SKILL.md | 3 --- src/src/Aspire/Sdk/README.md | 2 -- src/src/AzureKeyVaultEmulator/Sdk/README.md | 2 -- src/src/AzureServiceBusEmulator/Sdk/README.md | 2 -- src/src/Azurite/Sdk/README.md | 2 -- src/src/Containers/Sdk/README.md | 3 --- src/src/Core/Sdk/README.md | 3 --- src/src/Docker/Sdk/README.md | 3 --- src/src/Environment/Sdk/README.md | 2 -- src/src/MsSql/Sdk/README.md | 2 -- src/src/MySql/Sdk/README.md | 2 -- src/src/Nats/Sdk/README.md | 2 -- src/src/PostgreSql/Sdk/README.md | 2 -- src/src/RabbitMq/Sdk/README.md | 2 -- src/src/Redis/Sdk/README.md | 2 -- src/src/Wsl/Sdk/README.md | 2 -- 24 files changed, 32 insertions(+), 82 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e90dfc5..10bb2f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -164,8 +164,9 @@ whenever a target framework, a backend package or the `buildTransitive` assets c tests) registers explicitly instead — `WslcTest.EnsureBackendRegistered()`. - `src/Directory.Build.props` sets `EnableWindowsTargeting=true` because the shared CI agent is `ubuntu-latest`; removing it fails the pipeline with `NETSDK1100`. -- The project is **experimental**: keep the experimental notice in `README.md`, `docs/wiki/Home.md` and - the package READMEs, and keep versions on a `-prerelease.N` suffix. +- Versions stay on a `-prerelease.N` suffix until the stable 1.0.0 release, which includes the WSL + Containers backend. The docs, README and package READMEs must not carry experimental or preview + notices. ## Module rules @@ -256,8 +257,10 @@ Commit messages follow Conventional Commits enforced by the `commit-msg` lefthoo ## Versioning and releases - `package.json` is the authoritative release and package version. Do not diverge project versions by hand. -- `.github/workflows/pr.yml` builds and tests pull requests through the shared - `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled. +- `.github/workflows/pr.yml` builds and tests pull requests **and every push to `main`** through the + shared `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled (plus + the Docker and WSLC contract jobs). A push to `main` never publishes; superseded PR runs are + cancelled, `main` runs are not. - `.github/workflows/release.yml` runs the shared release pipeline with `release-mode: NuGet` on a push to a `release/**` branch (or a manual dispatch), **not** on a push to `main`. Cut a release by merging the version bump into `main`, then pushing a `release/v…` branch named after the version from it (for diff --git a/README.md b/README.md index 46087aa..0c0da21 100644 --- a/README.md +++ b/README.md @@ -34,21 +34,16 @@ Testcontainers' `WithCleanUp`: containers are removed by default, `.WithCleanUp( for inspection, and `.WithAutoRemove()` is opted into separately. See [Capabilities and Cancellation](docs/wiki/Backend-Capabilities.md) for APIs, ownership and limits. -> **Experimental.** This project is an experiment in running throwaway containers through Microsoft -> WSL Containers. The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against, and read -> [Consumer Requirements](docs/wiki/Consumer-Requirements.md) before adopting it. - -> **Status: preview.** Backend-neutral abstractions, two backends (WSL Containers and Docker), wait -> strategies, the `Image`/`Tag` parser, registry auth, observability, hardening, and **nine service -> modules** (PostgreSQL, Redis, SQL Server, RabbitMQ, Azurite, NATS, MySQL, Azure Key Vault Emulator, Azure Service Bus Emulator). On WSLC, **images are shared -> by default** (`StorageMode.Shared`): sessions reuse a stable image store -> (`%LOCALAPPDATA%\Purview\WslContainers\images`) so images are pulled once, not per session; -> `StorageMode.PerSession` provides isolation. Move the store with `PURVIEW_CONTAINERS_STORAGE_PATH` or -> `WslContainerRuntimeOptions.StoragePath`. Named volumes are retained by default; set -> `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true` (or `ContainerCleanup.CleanUpVolumesOnExit`) to delete the -> volumes the library created when the process or session ends. Runnable samples live in -> `samples/getting-started`. +**Features.** Backend-neutral abstractions, two backends (WSL Containers and Docker), wait +strategies, the `Image`/`Tag` parser, registry auth, observability, hardening, and **nine service +modules** (PostgreSQL, Redis, SQL Server, RabbitMQ, Azurite, NATS, MySQL, Azure Key Vault Emulator, Azure +Service Bus Emulator). On WSLC, **images are shared by default** (`StorageMode.Shared`): sessions reuse a +stable image store (`%LOCALAPPDATA%\Purview\WslContainers\images`) so images are pulled once, not per +session; `StorageMode.PerSession` provides isolation. Move the store with +`PURVIEW_CONTAINERS_STORAGE_PATH` or `WslContainerRuntimeOptions.StoragePath`. Named volumes are retained +by default; set `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true` (or `ContainerCleanup.CleanUpVolumesOnExit`) to +delete the volumes the library created when the process or session ends. Runnable samples live in +`samples/getting-started`. **Documentation:** [Containers documentation](https://purview.dev/docs/containers/) diff --git a/docs/wiki/Backends.md b/docs/wiki/Backends.md index d04c251..ceb1d39 100644 --- a/docs/wiki/Backends.md +++ b/docs/wiki/Backends.md @@ -224,7 +224,7 @@ dotnet add package Purview.Containers.Wsl enable - + ``` @@ -253,7 +253,7 @@ dotnet add package Purview.Containers.Docker enable - + ``` @@ -278,7 +278,7 @@ dotnet add package Purview.Containers enable - + ``` diff --git a/docs/wiki/Consumer-Requirements.md b/docs/wiki/Consumer-Requirements.md index c5afdaa..0c35c27 100644 --- a/docs/wiki/Consumer-Requirements.md +++ b/docs/wiki/Consumer-Requirements.md @@ -1,10 +1,5 @@ # Consumer Requirements -> **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 @@ -180,8 +175,8 @@ runs on WSLC locally and Docker in CI with no further configuration: net10.0 - - + + ``` @@ -269,7 +264,7 @@ unconditionally — every inner build is supported: net10.0;net11.0;net10.0-windows10.0.19041.0 - + ``` diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md index 138fec3..5490802 100644 --- a/docs/wiki/Getting-Started.md +++ b/docs/wiki/Getting-Started.md @@ -24,9 +24,6 @@ Everything runs on one of two backends; pick the one that matches your machine - The full consumer contract, every error, and the `EnableWindowsTargeting` workaround for non-Windows CI agents live in [Consumer Requirements](Consumer-Requirements.md). -> **Experimental.** The API, defaults and packaging rules can change between prereleases; there is no -> production support guarantee. - ## 1. Reference a package | Package | Use it when | diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 3891366..0582862 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -9,11 +9,6 @@ capabilities the SDK does not expose. See [Capabilities and Cancellation](Backen This wiki is the project documentation hub. The packages are published under the `Purview.Containers.*` package IDs. -> **Experimental.** This project is an experiment in running throwaway containers through Microsoft -> WSL Containers. The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against and read -> [Consumer Requirements](Consumer-Requirements.md) before adopting it. - ## Start here - [Getting Started](Getting-Started.md) diff --git a/docs/wiki/Release-Flow.md b/docs/wiki/Release-Flow.md index 924363c..05d95f8 100644 --- a/docs/wiki/Release-Flow.md +++ b/docs/wiki/Release-Flow.md @@ -9,9 +9,9 @@ applies that value to `Version` and `PackageVersion` for every project, so a rel bump — never a manual project-file edit. `package.json` also carries the repository, homepage and issue URLs that end up in each nuspec. -The project is **experimental**, so versions stay on a `-prerelease.N` suffix: consumers should pin an -exact version rather than float, and each bump can change the API or the -[consumer requirements](Consumer-Requirements.md). +Versions use a `-prerelease.N` suffix until the stable 1.0.0 release, which will include the WSL Containers +backend. Until then, consumers should pin an exact version rather than float, and each bump can change +the API or the [consumer requirements](Consumer-Requirements.md). ## Local commands @@ -48,8 +48,9 @@ the run with the failing module's output. ## GitHub Actions -- `.github/workflows/pr.yml` — pull requests build and test via the shared - `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled. +- `.github/workflows/pr.yml` — pull requests **and every push to `main`** build and test via the shared + `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled, plus the + Docker and WSLC contract jobs. A push to `main` builds only; it never publishes. - `.github/workflows/release.yml` — a push to a **`release/**` branch** (or a manual `workflow_dispatch`) calls `purview-dev/build/.github/workflows/purview-release.yml` with `release-mode: NuGet`. It evaluates release eligibility and, when eligible, builds, tests, packs, publishes to NuGet and creates the diff --git a/docs/wiki/Using-in-Your-Tests.md b/docs/wiki/Using-in-Your-Tests.md index ffc4dd4..8d7364c 100644 --- a/docs/wiki/Using-in-Your-Tests.md +++ b/docs/wiki/Using-in-Your-Tests.md @@ -13,10 +13,10 @@ a Mac) — nothing changes between them. - - + + - + ``` diff --git a/skills/purview-containers-quickstart/SKILL.md b/skills/purview-containers-quickstart/SKILL.md index 396d895..2de75b8 100644 --- a/skills/purview-containers-quickstart/SKILL.md +++ b/skills/purview-containers-quickstart/SKILL.md @@ -14,9 +14,6 @@ metadata: Throwaway Linux containers for .NET tests, behind one API, over either **WSL Containers** (no Docker installation on Windows) or **Docker** (anywhere). The same test code runs on both. -> **Experimental and prerelease.** The API, defaults and packaging rules can change between releases. -> Pin the version you adopt. - ## Which package | Package | Use it when | diff --git a/src/src/Aspire/Sdk/README.md b/src/src/Aspire/Sdk/README.md index 006112e..7b5ce60 100644 --- a/src/src/Aspire/Sdk/README.md +++ b/src/src/Aspire/Sdk/README.md @@ -1,7 +1,5 @@ # Purview.Containers.Aspire -> **Experimental.** Pin the exact prerelease version; the API and defaults may change. - Apply verified container bind-source resolution to any Aspire AppHost. ```csharp diff --git a/src/src/AzureKeyVaultEmulator/Sdk/README.md b/src/src/AzureKeyVaultEmulator/Sdk/README.md index 6c92a28..dda336a 100644 --- a/src/src/AzureKeyVaultEmulator/Sdk/README.md +++ b/src/src/AzureKeyVaultEmulator/Sdk/README.md @@ -24,8 +24,6 @@ container can hand out clients that are already wired for the emulator. [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. - The emulator is not a replacement for Azure Key Vault; it exists to make developing against it easier. ## Quick start diff --git a/src/src/AzureServiceBusEmulator/Sdk/README.md b/src/src/AzureServiceBusEmulator/Sdk/README.md index f66688b..9954da7 100644 --- a/src/src/AzureServiceBusEmulator/Sdk/README.md +++ b/src/src/AzureServiceBusEmulator/Sdk/README.md @@ -28,8 +28,6 @@ its state in SQL Server), and needs a backend package (`Purview.Containers.Wsl` which is x64 only and needs at least 2000 MB of memory in the WSLC session VM or Docker host. On ARM64, `WithSqlServerImage("mcr.microsoft.com/azure-sql-edge:latest")` is an alternative the emulator supports. SQL Server 2022 does not start on WSLC (it fails to create `/.system` as the non-root `mssql` user). -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. - The emulator is for local development and testing only; it is not a replacement for Azure Service Bus. ## Quick start diff --git a/src/src/Azurite/Sdk/README.md b/src/src/Azurite/Sdk/README.md index 4f9e232..0519b27 100644 --- a/src/src/Azurite/Sdk/README.md +++ b/src/src/Azurite/Sdk/README.md @@ -22,8 +22,6 @@ See the [Getting Started guide](https://github.com/purview-dev/containers/blob/m [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/Containers/Sdk/README.md b/src/src/Containers/Sdk/README.md index b16e3cb..8e27633 100644 --- a/src/src/Containers/Sdk/README.md +++ b/src/src/Containers/Sdk/README.md @@ -67,6 +67,3 @@ not change. - [Using it in your tests (auto)](https://github.com/purview-dev/containers/blob/main/docs/wiki/Using-in-Your-Tests.md) - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) - -> **Experimental.** The public API, defaults and packaging rules can change between prereleases; there is -> no production support guarantee. \ No newline at end of file diff --git a/src/src/Core/Sdk/README.md b/src/src/Core/Sdk/README.md index c5d9232..1c9a564 100644 --- a/src/src/Core/Sdk/README.md +++ b/src/src/Core/Sdk/README.md @@ -87,6 +87,3 @@ callers that want to apply their own policy. - [Purview.Containers.Wsl](https://www.nuget.org/packages/Purview.Containers.Wsl) — WSL Containers backend. - Documentation wiki: . - -> **Experimental.** The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against. diff --git a/src/src/Docker/Sdk/README.md b/src/src/Docker/Sdk/README.md index 878d074..a6d3024 100644 --- a/src/src/Docker/Sdk/README.md +++ b/src/src/Docker/Sdk/README.md @@ -69,6 +69,3 @@ PURVIEW_CONTAINERS_BACKEND=docker # or "auto" (the default) to probe WSLC fi store and bind mounts are untouched. - Log tailing polls the accumulated output until the container stops, because the Testcontainers API exposes no positioned log stream. - -> **Experimental.** The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against. diff --git a/src/src/Environment/Sdk/README.md b/src/src/Environment/Sdk/README.md index 505afed..a6ca33c 100644 --- a/src/src/Environment/Sdk/README.md +++ b/src/src/Environment/Sdk/README.md @@ -1,7 +1,5 @@ # Purview.Containers.Environment -> **Experimental.** Pin the exact prerelease version; the API and defaults may change. - Resolve client-side bind sources against a Docker-compatible daemon without assuming the daemon runs on the client machine. This library has no Aspire or AspireC4 dependency. diff --git a/src/src/MsSql/Sdk/README.md b/src/src/MsSql/Sdk/README.md index f0f4b7d..ab2572d 100644 --- a/src/src/MsSql/Sdk/README.md +++ b/src/src/MsSql/Sdk/README.md @@ -21,8 +21,6 @@ connection-string generation and readiness probing. [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/MySql/Sdk/README.md b/src/src/MySql/Sdk/README.md index bd02535..fd72a58 100644 --- a/src/src/MySql/Sdk/README.md +++ b/src/src/MySql/Sdk/README.md @@ -21,8 +21,6 @@ connection-string generation. [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/Nats/Sdk/README.md b/src/src/Nats/Sdk/README.md index eda60d5..e22ea31 100644 --- a/src/src/Nats/Sdk/README.md +++ b/src/src/Nats/Sdk/README.md @@ -21,8 +21,6 @@ package — bring your own client. [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/PostgreSql/Sdk/README.md b/src/src/PostgreSql/Sdk/README.md index 68af22c..fef7ef2 100644 --- a/src/src/PostgreSql/Sdk/README.md +++ b/src/src/PostgreSql/Sdk/README.md @@ -21,8 +21,6 @@ See the [Getting Started guide](https://github.com/purview-dev/containers/blob/m [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/RabbitMq/Sdk/README.md b/src/src/RabbitMq/Sdk/README.md index e5ec9ed..0473edb 100644 --- a/src/src/RabbitMq/Sdk/README.md +++ b/src/src/RabbitMq/Sdk/README.md @@ -21,8 +21,6 @@ bring your own client. [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/Redis/Sdk/README.md b/src/src/Redis/Sdk/README.md index 76c9740..9e8050b 100644 --- a/src/src/Redis/Sdk/README.md +++ b/src/src/Redis/Sdk/README.md @@ -21,8 +21,6 @@ package — bring your own client. [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/Wsl/Sdk/README.md b/src/src/Wsl/Sdk/README.md index 52eb8aa..0aeae56 100644 --- a/src/src/Wsl/Sdk/README.md +++ b/src/src/Wsl/Sdk/README.md @@ -44,8 +44,6 @@ consuming assembly. To also run the same test code on Docker in Linux CI, refere [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - Verify the host with `wsl --version` and `wslc version`. The library never installs or updates WSL itself; `WslContainerRuntime.GetInfoAsync()` reports what is missing. -- **Experimental:** this is an experiment in driving WSL Containers. The public API, defaults and - packaging rules can change between prereleases, and there is no production support guarantee. ## Quick start From 844b3d2c402cfd036941a04b06d2a984126ad1a3 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Wed, 18 Nov 2026 16:41:02 +0000 Subject: [PATCH 07/14] fix(wsl): x64 only, enforce the WSL floor, and make every failure actionable Drop ARM64: the Windows implementation was compiled for x64 yet shipped under payload/win-arm64, where it could not load. Ship payload/win-x64 only; PCC0002 now rejects any non-x64 Windows consumer, and the portable facade reports the backend unavailable in a non-x64 process so selection falls through to Docker. Add WslRequirements: the minimum WSL (MinimumWslVersion, following the SDK pin in Directory.Packages.props and stamped into the assembly) is checked at run time, and every missing component, version mismatch and HRESULT (WSL_E_OS_NOT_SUPPORTED, optional component, class not registered, missing wslcsdk.dll) is reported with its fix instead of a bare enum name. wslc is found on PATH or at %ProgramFiles%\WSL. verify-consumers gains cases 26-28 (arm64 rejected, x64 payload copied). --- .config/purview-build.json | 6 +- Directory.Packages.props | 7 + scripts/verify-consumers.ps1 | 14 ++ src/src/Wsl/Sdk/README.md | 29 ++-- .../Purview.Containers.Wsl.targets | 25 ++-- src/src/Wsl/Wsl.csproj | 36 +---- src/src/Wsl/WslCommand.cs | 46 +++++- src/src/Wsl/WslContainerBackend.Facade.cs | 5 +- src/src/Wsl/WslContainerRuntime.cs | 39 +++-- src/src/Wsl/WslPayload.cs | 31 +++- src/src/Wsl/WslRequirements.cs | 106 ++++++++++++++ .../Wsl.UnitTests/WslRequirementsTests.cs | 138 ++++++++++++++++++ 12 files changed, 402 insertions(+), 80 deletions(-) create mode 100644 src/src/Wsl/WslRequirements.cs create mode 100644 src/tests/Wsl.UnitTests/WslRequirementsTests.cs diff --git a/.config/purview-build.json b/.config/purview-build.json index 3519bd8..a1ed7c0 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -66,7 +66,7 @@ // Purview.Containers.Wsl is multi-target: lib/net10.0 and lib/net11.0 are the portable facades // (net11.0 is compiled with runtime-async), and the *-windows10.0.19041 builds are the WSLC // implementations. A portable consumer loads the Windows implementation (plus the WSLC - // projection, its Windows SDK dependencies and the native SDK) from payload// via the + // projection, its Windows SDK dependencies and the native SDK) from payload/win-x64/ via the // buildTransitive targets; one payload serves both portable targets because a .NET 11 process // loads a .NET 10 assembly. "purview.containers.wsl": [ @@ -82,8 +82,8 @@ "purview-logo-light.png", "buildTransitive/Purview.Containers.Wsl.props", "buildTransitive/Purview.Containers.Wsl.targets", - "payload/win-x64/*", - "payload/win-arm64/*" + // x64 only: the backend does not support ARM64, so no win-arm64 payload is shipped. + "payload/win-x64/*" ], "purview.containers.azurekeyvaultemulator": [ "lib/$(TFM)/Purview.Containers.AzureKeyVaultEmulator.dll", diff --git a/Directory.Packages.props b/Directory.Packages.props index 9089c6d..39bfd97 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -28,6 +28,13 @@ --> 3.0.5 + + $(MicrosoftWSLContainersVersion) 10.0.26100.80 1.87.0 diff --git a/scripts/verify-consumers.ps1 b/scripts/verify-consumers.ps1 index 668f36b..e575b83 100644 --- a/scripts/verify-consumers.ps1 +++ b/scripts/verify-consumers.ps1 @@ -37,6 +37,9 @@ 23 net10.0 + Aspire adapter -> builds, no backend required 24 plain net11.0 + WSL backend (the runtime-async facade) -> builds, wsl registration generated 25 net11.0 + umbrella Purview.Containers + modules (one ref) -> builds, both registrations generated + 26 net11 windows + PlatformTarget=arm64 -> fails PCC0002 (the backend is x64 only) + 27 net11 windows + RuntimeIdentifier=win-arm64 -> fails PCC0002 (the backend is x64 only) + 28 plain net10.0 + WSL backend (portable facade) -> builds, x64 payload (wslc/) copied .PARAMETER FeedPath Folder holding the packed .nupkg files. Defaults to /artifacts. @@ -500,6 +503,17 @@ public static class Program -Items $umbrellaItems ` -Sources @{ 'Smoke.Auto.cs' = $autoSource } ` -RequireText @('WslContainerBackend.Create()', 'DockerContainerBackend.Create()') + + New-ConsumerCase -Id '26' -Name 'net11 windows + PlatformTarget=arm64 (x64 only)' ` + -Properties "$sdkVersionarm64" -Expect 'PCC0002' + + New-ConsumerCase -Id '27' -Name 'net11 windows + RuntimeIdentifier=win-arm64 (x64 only)' ` + -Properties "$sdkVersionwin-arm64" -Expect 'PCC0002' + + New-ConsumerCase -Id '28' -Name 'plain net10.0 + WSL backend copies the x64 payload' ` + -Framework 'net10.0' ` + -Sources @{ 'Smoke.Portable.cs' = $portableSource } ` + -RequireFile 'wslcsdk.dll' ) diff --git a/src/src/Wsl/Sdk/README.md b/src/src/Wsl/Sdk/README.md index 0aeae56..df9cea5 100644 --- a/src/src/Wsl/Sdk/README.md +++ b/src/src/Wsl/Sdk/README.md @@ -5,7 +5,8 @@ throwaway Linux containers for .NET integration testing built directly on the `M 3.0.5 managed API, with **no Docker installation**, Docker.DotNet or Testcontainers dependency. Lifecycle, images, named networks and aliases, Linux capabilities and session host-loopback support all use the managed SDK. Capabilities still missing from it use a bounded `wslc` CLI fallback in the same -session: entrypoint/user/labels, reuse, file copy and Dockerfile builds require `wslc` on PATH. +session: entrypoint/user/labels, reuse, file copy and Dockerfile builds require the `wslc` CLI that +ships with WSL (found on PATH or at `%ProgramFiles%\WSL\wslc.exe`). ```bash dotnet add package Purview.Containers.Wsl @@ -29,13 +30,21 @@ consuming assembly. To also run the same test code on Docker in Linux CI, refere ## Requirements -- Windows 11 or Windows Server 2025 with **WSL Containers** (`wsl --install --no-distribution`). +- **An x64 Windows host where WSL 2 runs** (Windows 11, Windows 10 version 2004 or later with current + updates, or Windows Server 2025), with virtualisation enabled in the firmware and the Virtual Machine + Platform feature on. ARM64 and x86 are not supported. +- **WSL 3.0.5 or later** from the stable channel: `wsl --install --no-distribution` (new install) or + `wsl --update`. No `--pre-release` channel is needed. The floor follows the bundled + `Microsoft.WSL.Containers` SDK and is checked at run time; an older WSL is reported with the fix. The + library adds no Windows-version check of its own: WSL decides, and reports `WSL_E_OS_NOT_SUPPORTED`. + Tested on Windows 11 23H2 and Windows Server 2025; the full list is in the + [host requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md#host-requirements-wsl-containers-backend). - **A .NET 10 or .NET 11 project** (.NET 8 and .NET 9 are not supported). The recommended target framework is platform-neutral (`net10.0` or `net11.0`): it binds the facade and gives you automatic WSLC-or-Docker selection. A Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. Anything older than .NET 10, or a Windows TFM below Windows 10.0.19041.0, fails the build with - `PCC0001`; a 32-bit Windows consumer fails with `PCC0002`; and without the packages' MSBuild defaults a + `PCC0001`; a non-x64 (ARM64 or x86) Windows consumer fails with `PCC0002`; and without the packages' MSBuild defaults a stale `WindowsSdkPackageVersion` fails with `CS1705`. - This package supplies the `buildTransitive` defaults for `WindowsSdkPackageVersion` and `PlatformTarget` that every module package inherits, and (for a platform-neutral consumer on a Windows @@ -43,7 +52,7 @@ consuming assembly. To also run the same test code on Docker in Linux CI, refere reference and the `EnableWindowsTargeting` workaround for non-Windows CI agents are in the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - Verify the host with `wsl --version` and `wslc version`. The library never installs or updates WSL - itself; `WslContainerRuntime.GetInfoAsync()` reports what is missing. + itself; `WslContainerRuntime.GetInfoAsync()` reports what is missing and how to fix it. ## Quick start @@ -96,7 +105,7 @@ are available. Exec/stop cancellation is propagated, not returned as a successfu Synchronous native SDK calls cannot be interrupted safely. Managed waits and CLI processes are bounded, but a blocked native call can outlive cancellation. CLI creation currently rejects privileged mode combined with CLI-only features and multi-line environment values. See -[capabilities and cancellation](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backend-Capabilities.md). +[capabilities and cancellation](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Backend-Capabilities.md). `IContainer` (and `WslContainer`) exposes `StartAsync`, `StopAsync`, `ExecAsync`, `GetMappedPublicPort`, `GetMappedPublicPorts`, `GetLogsAsync(LogOutput?)` and a tailing `IAsyncEnumerable` @@ -180,9 +189,9 @@ raw command/build output. See the [project wiki](https://github.com/purview-dev/containers/blob/main/docs/wiki/Home.md): [Getting Started](https://github.com/purview-dev/containers/blob/main/docs/wiki/Getting-Started.md), -[Architecture](https://github.com/purview-dev/containers/blob/main/docs/wiki/Architecture.md), -[Lifecycle](https://github.com/purview-dev/containers/blob/main/docs/wiki/Lifecycle.md), -[Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/Networking.md) and -[Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md). +[Architecture](https://github.com/purview-dev/containers/blob/main/docs/wiki/contributing/Architecture.md), +[Lifecycle](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Lifecycle.md), +[Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Networking.md) and +[Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md). Ready-made service modules ship as `Purview.Containers.PostgreSql`, `Redis`, `MsSql`, `RabbitMq`, `Azurite`, `Nats`, `MySql` and `AzureKeyVaultEmulator`. diff --git a/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets b/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets index 908cae5..b3456b7 100644 --- a/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets +++ b/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets @@ -6,9 +6,10 @@ has been evaluated, so an explicit PlatformTarget or RuntimeIdentifier always wins. The values set here are defaults only. - PlatformTarget: wslcsdk.dll (the native WSL Containers SDK) ships for win-x64 and win-arm64 - only. A consumer left on the default AnyCPU is corrected to x64 here; an explicit x86 (32-bit) - consumer fails with PCC0002 instead of failing later at runtime with a load error. + PlatformTarget: the backend supports x64 only - the Windows implementation is compiled for x64 and + only the win-x64 native SDK (wslcsdk.dll) is deployed. A consumer left on the default AnyCPU is + corrected to x64 here; an explicit x86 or arm64 consumer fails with PCC0002 instead of failing later + at runtime with a load error. Target framework: because build and buildTransitive assets are framework-agnostic, NuGet does not reject an incompatible target framework at restore time with NU1202 - it silently @@ -23,9 +24,9 @@ --> @@ -84,14 +85,14 @@ <_PurviewContainersWslIsWindows Condition="'$(TargetPlatformIdentifier)' == 'Windows'" >true <_PurviewContainersWslPlatformTargetSupported - Condition="'$(_PurviewContainersWslIsWindows)' != 'true' OR '$(PlatformTarget)' == 'x64' OR '$(PlatformTarget)' == 'arm64' OR ('$(PlatformTarget)' == '' AND '$(RuntimeIdentifier)' != '')" + Condition="'$(_PurviewContainersWslIsWindows)' != 'true' OR '$(PlatformTarget)' == 'x64' OR ('$(PlatformTarget)' == '' AND $(RuntimeIdentifier.EndsWith('-x64')))" >true @@ -108,12 +109,8 @@ Condition="'$(TargetFramework)' != '' AND '$(OS)' == 'Windows_NT' AND '$(TargetPlatformIdentifier)' != 'Windows'" > - <_PurviewContainersWslPayloadRid - Condition="'$(RuntimeIdentifier)' == 'win-arm64' OR '$(PlatformTarget)' == 'arm64'" - >win-arm64 - <_PurviewContainersWslPayloadRid Condition="'$(_PurviewContainersWslPayloadRid)' == ''" - >win-x64 - <_PurviewContainersWslPayloadSource>$(MSBuildThisFileDirectory)..\payload\$(_PurviewContainersWslPayloadRid)\ + + <_PurviewContainersWslPayloadSource>$(MSBuildThisFileDirectory)..\payload\win-x64\ diff --git a/src/src/Wsl/Wsl.csproj b/src/src/Wsl/Wsl.csproj index 866d048..5bc73de 100644 --- a/src/src/Wsl/Wsl.csproj +++ b/src/src/Wsl/Wsl.csproj @@ -64,6 +64,9 @@ + + + + x64 10.0.26100.80 ``` @@ -76,9 +81,9 @@ file, and because the defaults only fill in a value when you have not chosen one | --- | --- | --- | | 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. | +| 3 | **x64** (`PlatformTarget` `x64`, the default, or the `win-x64` `RuntimeIdentifier`) | The Windows implementation is compiled for x64 and only the `win-x64` native `wslcsdk.dll` is deployed. ARM64 and x86 are not supported. | | 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. | +| 5 | **A host that meets the [host requirements](#host-requirements-wsl-containers-backend)** to actually run containers | The library drives WSLC; it never installs or updates WSL for you. | ### 1. .NET 10 or .NET 11 @@ -120,15 +125,22 @@ the implementation was built against, so NuGet selects no compile assets for it. 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.) -### 3. 64-bit consumers only +### 3. x64 consumers only -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: +The WSL Containers backend supports **x64 only**: the Windows implementation is compiled for x64 and +the package deploys only the `win-x64` native SDK. A Windows-target-framework consumer that is not x64 +(`PlatformTarget` `arm64` or `x86`, or a non-x64 `RuntimeIdentifier` such as `win-arm64`) would fail +to load `wslcsdk.dll` at run time, so the packages fail the build instead: ```text -error PCC0002: Purview.Containers.Wsl requires a 64-bit (x64 or arm64) consumer ... +error PCC0002: Purview.Containers.Wsl requires an x64 consumer on a Windows target framework ... ``` +Remove `PlatformTarget` (x64 is the default), set it to `x64`, or choose the `win-x64` +`RuntimeIdentifier`. A platform-neutral (`net10.0`/`net11.0`) consumer still builds anywhere; in a +non-x64 process the facade reports the backend unavailable ("supports x64 processes only"), so +automatic selection falls through to Docker. + ### 4. Windows SDK targeting pack version `Microsoft.WSL.Containers` 3.0.5's projection references `Microsoft.Windows.SDK.NET` @@ -146,10 +158,40 @@ for you, so you only need it if you want to override the value deliberately. ### 5. Host prerequisites -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 +The build requirements above are host-independent. Running containers needs a host that meets the +[host requirements](#host-requirements-wsl-containers-backend) below — see also [Getting Started](Getting-Started.md). +## Host requirements (WSL Containers backend) + +This is the authoritative list; other pages state the short form and link here. + +1. **x64 only.** The backend runs in x64 processes. ARM64 and x86 are not supported: a Windows-target + consumer fails the build with `PCC0002`, and a platform-neutral consumer in a non-x64 process sees + the backend reported unavailable, so automatic selection falls through to Docker. +2. **WSL 3.0.5 or later**, from the normal stable channel: `wsl --install --no-distribution` for a new + install, or `wsl --update`. WSL Containers has been generally available in the stable channel since + WSL 3.0.1; the `--pre-release` channel is not needed. The floor follows the bundled + `Microsoft.WSL.Containers` SDK (3.0.5) and is checked at run time: an older WSL is reported as + incompatible with "Run 'wsl --update'". +3. **Windows wherever WSL 2 runs:** Windows 11, Windows 10 version 2004 (build 19041) or later with + current updates, or Windows Server 2025. The library carries no Windows-version check of its own — + WSL decides, and an unsupported Windows is reported as `WSL_E_OS_NOT_SUPPORTED` with the fix. +4. **Virtualisation** enabled in the firmware, plus the Windows **Virtual Machine Platform** feature + (`wsl --install --no-distribution` enables it; a restart is required). +5. **The `wslc` CLI** ships with WSL and is needed only for the CLI-backed features (entrypoint, user + and label overrides, file copy, image builds and reuse). The library finds it on PATH or at + `%ProgramFiles%\WSL\wslc.exe`, so no PATH change is needed. + +Tested on Windows 11 23H2 (development) and Windows Server 2025 (the `windows-2025` CI runner); +Windows 10 and Windows Server 2022 are untested. + +A host that falls short is reported with its fix, by `WslContainerBackend.GetInfoAsync()` and in +`ContainerBackendUnavailableException`. For example: "The Virtual Machine Platform Windows feature is +not enabled… run 'wsl --install --no-distribution'…", "WSL 3.0.3 is older than WSL 3.0.5, the +minimum… Run 'wsl --update'.", or, when WSL is newer than the bundled SDK, "Update the +Purview.Containers.Wsl package…". + ## What the packages do for you `Purview.Containers.Wsl` ships two `buildTransitive` MSBuild files. NuGet imports them for **direct and @@ -194,9 +236,9 @@ always wins over these defaults. | 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`. | +| `PCC0002` | the shipped guard target | The consumer is not x64 (ARM64 and x86 are not supported) | Remove your `PlatformTarget` (x64 is the default), set it to `x64`, or choose the `win-x64` `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. | +| `CS8012` | the C# compiler | A referenced assembly targets a different processor (seen when a consumer forces `x86`) | Use an x64 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. | @@ -216,7 +258,7 @@ 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](Testing.md). +pipeline is filtered to `[Category=Unit]`. See [Testing](contributing/Testing.md). What it does and does not do: @@ -275,7 +317,7 @@ condition is no longer needed. ## Verifying these requirements -`just verify-consumers` packs the solution and builds twenty-five throwaway consumer projects against the +`just verify-consumers` packs the solution and builds twenty-eight throwaway consumer projects against the produced packages, asserting every claim on this page: | Case | Consumer | Expected outcome | @@ -305,6 +347,9 @@ produced packages, asserting every claim on this page: | 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) | +| 26 | `.NET 11` + Windows with `PlatformTarget=arm64` | `PCC0002` — the backend is x64 only | +| 27 | `.NET 11` + Windows with `RuntimeIdentifier=win-arm64` | `PCC0002` — the backend is x64 only | +| 28 | a plain `net10.0` consumer of the WSL Containers backend | builds; the x64 implementation payload (`wslc/`, including `wslcsdk.dll`) is copied to the output | 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 @@ -313,6 +358,6 @@ rather than part of the `[Category=Unit]` filter. ## Related - [Getting Started](Getting-Started.md) — prerequisites and the first container. -- [Packaging](Packaging.md) — what each package contains, including the `buildTransitive` assets. -- [Testing](Testing.md) — the Linux CI run, the unit filter and the serial WSLC rule. +- [Packaging](contributing/Packaging.md) — what each package contains, including the `buildTransitive` assets. +- [Testing](contributing/Testing.md) — the Linux CI run, the unit filter and the serial WSLC rule. - [Modules](Modules.md) — the service modules that inherit these defaults. diff --git a/docs/wiki/Contributing-Modules.md b/docs/wiki/Contributing-Modules.md index 5610232..905d3f4 100644 --- a/docs/wiki/Contributing-Modules.md +++ b/docs/wiki/Contributing-Modules.md @@ -1,18 +1,19 @@ # Contributing a module -How to add a new service module to `Purview.Containers`. +How to add a new service module to `Purview.Containers`: the configuration record, builder and +container a module provides, what it may and may not contribute, and the tests it needs. ## Files -``` -src/src/MyService/ - MyService.csproj -> PackageId Purview.Containers.MyService - MyServiceConfiguration.cs -> immutable record, module fields - MyServiceBuilder.cs -> fluent builder - MyServiceContainer.cs -> container, connection string / endpoints -src/tests/MyService.UnitTests/ -src/tests/MyService.IntegrationTests/ -``` +| Path | Purpose | +| --- | --- | +| `src/src/MyService/MyService.csproj` | The project; packs as `Purview.Containers.MyService` | +| `src/src/MyService/MyServiceConfiguration.cs` | Immutable configuration record with the module's fields | +| `src/src/MyService/MyServiceBuilder.cs` | The fluent builder | +| `src/src/MyService/MyServiceContainer.cs` | The container, with its connection string and endpoints | +| `src/src/MyService/Sdk/README.md` | The package README | +| `src/tests/MyService.UnitTests/` | Unit tests | +| `src/tests/MyService.IntegrationTests/` | Integration tests against a real container | ## Steps @@ -77,7 +78,7 @@ public class MyServiceBuilder : ContainerBuilder fluent configuration + validation - ├─ ContainerBase typed module container (delegates to the backend) - ├─ ContainerBackends + IContainerBackend backend registry and selection - ├─ Waiting / Images / Mounts / Networking / Diagnostics readiness, model, secrets - ├─ IConnectionStringProvider / ConnectionMode / ContainerConnectionStringProvider connection strings - └─ Runtime/ContainerException neutral error taxonomy - -Purview.Containers.Wsl (net10.0 + net11.0 facades, - net10.0 + net11.0 windows10.0.19041.0 implementations) - ├─ WslContainerBackend : IContainerBackend registers itself as "wsl" - ├─ WslContainerRuntime : IContainerRuntime process singleton, owns the shared session - │ ├─ SessionSettings (name, storagePath, cpu/mem, gpu, timeout) - │ ├─ SemaphoreSlim -> serialises session-mutating and container-lifecycle ops - │ ├─ ImageCatalog -> pull policies + keyed dedup of concurrent pulls - │ ├─ PortAllocator -> native random host ports (windowsPort=0) - │ └─ SessionHandle -> Microsoft.WSL.Containers.Session (internal) - ├─ WslContainer : IContainer WSLC-backed container - ├─ WslContainerSession : IContainerSession image pull + container create/start/stop/delete/exec - └─ WslResource / WslCommand / WslFileCopy owned resources; bounded CLI fallback in that same session - -IContainer : IConnectionStringProvider, IAsyncDisposable - StartAsync / StopAsync / DisposeAsync / ExecAsync / GetMappedPublicPort / - GetConnectionString / GetLogsAsync / tailing IAsyncEnumerable - CopyAsync / ReadFileAsync / WaitForExitAsync / DeleteAsync +The library is split into a backend-neutral abstraction assembly and one assembly per backend. Modules +reference the abstractions only; the backend is resolved at run time. + + +```mermaid +flowchart TB + tests([Your tests]) -- references --> umbrella[Purview.Containers] + tests -- references --> modules[Service modules] + umbrella --> core[Purview.Containers.Core] + umbrella --> wsl[Purview.Containers.Wsl] + umbrella --> docker[Purview.Containers.Docker] + modules -- references only --> core + wsl -- implements IContainerBackend --> core + docker -- implements IContainerBackend --> core + wsl -- lifecycle, images, networks --> wslcSdk[Microsoft.WSL.Containers SDK] + wsl -- entrypoint, copy, builds, reuse --> wslcCli[wslc CLI] + wslcSdk --> wslcSession[(WSLC session)] + wslcCli --> wslcSession + docker --> testcontainers[Testcontainers] --> dockerDaemon[(Docker daemon)] ``` +[LikeC4 model](../diagrams/package-architecture.c4) + + +| Package | Target frameworks | Key types | +| --- | --- | --- | +| `Purview.Containers` | `net10.0`, `net11.0` | None: the umbrella references Core, Wsl and Docker | +| `Purview.Containers.Core` | `net10.0`, `net11.0` | `IContainer`, `IContainerConfiguration`/`ContainerConfiguration` (the contract); `ContainerBuilder` (fluent configuration and validation); `ContainerBase` (typed module container); `ContainerBackends`, `IContainerBackend` (registry and selection); `IConnectionStringProvider`, `ConnectionMode`, `ContainerConnectionStringProvider`; `Runtime/ContainerException` (the neutral error taxonomy); the `Waiting`, `Images`, `Mounts`, `Networking` and `Diagnostics` namespaces | +| `Purview.Containers.Wsl` | `net10.0`, `net11.0` facades; `net10.0`/`net11.0-windows10.0.19041.0` x64 implementations | `WslContainerBackend` (registers as `wsl`); `WslContainerRuntime` (process singleton that owns the shared session); `WslContainer`; `WslContainerSession` (pull, create, start, stop, delete, exec); `WslResource`, `WslCommand`, `WslFileCopy` (owned resources and the bounded CLI fallback in the same session); `WslRequirements` (host requirements and their fixes) | +| `Purview.Containers.Docker` | `net10.0`, `net11.0` | `DockerContainerBackend` (registers as `docker`); `DockerContainer`; `DockerEndpoint` (daemon discovery) | + +Inside the WSL backend, one gate in `WslContainerRuntime` serialises every session-mutating and +container-lifecycle operation, `WslContainerSession` de-duplicates concurrent pulls of the same image, +and random host ports are allocated natively (`windowsPort=0`) and read back from the container. + +The container contract every backend implements: + +```csharp +public interface IContainer : IConnectionStringProvider, IAsyncDisposable +{ + string Id { get; } + string Name { get; } + ContainerState State { get; } + string Image { get; } + string? NetworkIp { get; } + + Task StartAsync(CancellationToken cancellationToken = default); + Task StopAsync(CancellationToken cancellationToken = default); + Task DeleteAsync(CancellationToken cancellationToken = default); + Task ExecAsync(string[] command, ExecOptions? options = null, CancellationToken cancellationToken = default); + + ushort GetMappedPublicPort(ushort containerPort); + IReadOnlyDictionary GetMappedPublicPorts(); + + Task GetLogsAsync(LogOutput? stream = null, CancellationToken cancellationToken = default); + IAsyncEnumerable GetLogsAsync(CancellationToken cancellationToken); + + Task CopyAsync(string source, string target, CancellationToken cancellationToken = default); + Task ReadFileAsync(string path, CancellationToken cancellationToken = default); + Task WaitForExitAsync(CancellationToken cancellationToken = default); +} +``` `IContainerBackend.CreateNetworkAsync` and `BuildImageAsync` return owned `IContainerResource` instances on either backend. Docker delegates to Testcontainers. WSLC networks and their deletion use the managed SDK; CLI-backed resources (image builds) target the SDK-owned session/store, while lifecycle, images and network operations remain SDK-backed. Dispose containers before networks/images. See -[Capabilities and Cancellation](Backend-Capabilities.md). +[Capabilities and Cancellation](../guide/Backend-Capabilities.md). A module (`Purview.Containers.PostgreSql`, `Purview.Containers.Redis`, …) derives its container from `ContainerBase` and references `Purview.Containers.Core` only. The backend is resolved at run time through @@ -53,7 +83,7 @@ Microsoft types (`Session`, `Container`, `Process`, `ContainerSettings`, …) ar ## Target frameworks Every package ships `net10.0` and `net11.0` assets. **.NET 8 and .NET 9 are dropped**; the contract is in -[Consumer Requirements](Consumer-Requirements.md). Purview.BuildSdk's `Supported` target-framework set +[Consumer Requirements](../Consumer-Requirements.md). Purview.BuildSdk's `Supported` target-framework set (selected in `src/Directory.Build.props`) supplies that pair; the repository does not hand-maintain it, and the WSL backend derives its Windows builds from the same set. @@ -95,7 +125,7 @@ Resolution is cached per process, so probes run once; `Reset()` (tests) and `Reg cache. Package consumers get registration from the generated module initializer in `Purview.Containers.Core.targets`; project-reference consumers register explicitly with `Register(...)`. Consumer-facing guidance (including the CI example) is in -[Backends: WSLC or Docker](Backends.md). +[Backends: WSLC or Docker](../Backends.md). ## Session lifetime model @@ -183,4 +213,4 @@ Isolated stores are transient and are removed when their session terminates. - Public surface deliberately small; WSLC types internal. - One opt-in accessor (`IWslContainerAccessor`) exposes `Inspect()` / raw handle for advanced users. -- Third-party modules subclass the generic builder (see [Modules](Modules.md)). \ No newline at end of file +- Third-party modules subclass the generic builder (see [Modules](../Modules.md)). \ No newline at end of file diff --git a/docs/wiki/Packaging.md b/docs/wiki/contributing/Packaging.md similarity index 91% rename from docs/wiki/Packaging.md rename to docs/wiki/contributing/Packaging.md index bb9c288..cb26e11 100644 --- a/docs/wiki/Packaging.md +++ b/docs/wiki/contributing/Packaging.md @@ -20,7 +20,7 @@ Each package ships exactly: | `buildTransitive/Purview.Containers.Core.props` / `.targets` | **Core (abstractions) package.** Declares the `PurviewContainersBackends` list and turns it into a generated backend initializer in the consuming assembly. | | `buildTransitive/Purview.Containers.Wsl.props` / `.targets` | **WSL Containers backend only.** Defaults `WindowsSdkPackageVersion`/`PlatformTarget` and raises `PCC0001`/`PCC0002` for unsupported consumers. | | `buildTransitive/Purview.Containers.Docker.props` | **Docker backend only.** Adds the Docker backend to the `PurviewContainersBackends` list. | -| `payload/win-x64/*`, `payload/win-arm64/*` | **WSL Containers backend only.** The Windows implementation, the WSLC projection, its Windows SDK dependencies and the native SDK. The portable facades load them at run time on a Windows host; the `buildTransitive` targets copy the matching folder to the consumer output. One payload (built from the lowest Windows target) serves both portable targets, because a .NET 11 process loads a .NET 10 assembly. | +| `payload/win-x64/*` | **WSL Containers backend only.** The Windows implementation, the WSLC projection, its Windows SDK dependencies and the native SDK. The backend is x64 only, so there is no ARM64 payload. The portable facades load them at run time on an x64 Windows host; the `buildTransitive` targets copy the folder to the consumer output. One payload (built from the lowest Windows target) serves both portable targets, because a .NET 11 process loads a .NET 10 assembly. | Portable PDBs are delivered through the `.snupkg`, never inside the `.nupkg`. The umbrella `Purview.Containers` package has no `buildTransitive` of its own: its dependencies' assets flow @@ -31,7 +31,7 @@ transitively. `Purview.Containers.Wsl` ships `lib/net10.0/` and `lib/net11.0/` (the facades), `lib/net10.0-windows10.0.19041/` and `lib/net11.0-windows10.0.19041/` (the implementations), with the `payload/` folders alongside. Every package therefore restores on a portable `net10.0` or `net11.0` project. Consumers must target .NET 10 or -.NET 11; see [Consumer Requirements](Consumer-Requirements.md). +.NET 11; see [Consumer Requirements](../Consumer-Requirements.md). ## Package metadata @@ -94,6 +94,7 @@ alongside the `Sdk/README.md`. Removing content from a package means removing th 3. Add the package to `RequiredContent` in `purview-build.json`. 4. Prove it with `just pack` and `just pipeline-pack-validate`. +> [!IMPORTANT] > **Packaging a backend or a new MSBuild asset?** NuGet only auto-imports `buildTransitive/.props` > and `buildTransitive/.targets`, so an asset named after anything else — including a shorter > product name — is shipped but never applied. A regression here is invisible to the build of this @@ -111,4 +112,4 @@ package with no rule, or a packed entry matched by no glob, fails validation. ## Related - [Release Flow](Release-Flow.md) — how packages are versioned and published. -- [Contributing Modules](Contributing-Modules.md) — the module contract a new package follows. +- [Contributing Modules](../Contributing-Modules.md) — the module contract a new package follows. diff --git a/docs/wiki/Contributing.md b/docs/wiki/contributing/README.md similarity index 86% rename from docs/wiki/Contributing.md rename to docs/wiki/contributing/README.md index a9a762a..f0bc0a9 100644 --- a/docs/wiki/Contributing.md +++ b/docs/wiki/contributing/README.md @@ -5,7 +5,7 @@ request. ## Prerequisites -- Windows with **WSL Containers** for integration tests; see [Getting Started](Getting-Started.md). +- Windows with **WSL Containers** for integration tests; see [Getting Started](../Getting-Started.md). - .NET SDK 11 (pinned in `global.json` as `11.0.100`). - The library projects split by framework: Purview.BuildSdk's `Supported` target-framework set (selected in `src/Directory.Build.props`) gives the backend-neutral abstractions and the service @@ -17,7 +17,7 @@ request. `net11.0-windows10.0.19041.0` (`src/Directory.Build.props`), which also sets `EnableWindowsTargeting=true` so the solution builds on the Linux CI agent. Do not remove that property: without it the shared pipeline fails with `NETSDK1100`. See - [Consumer Requirements](Consumer-Requirements.md). + [Consumer Requirements](../Consumer-Requirements.md). - [just](https://github.com/casey/just) for the repository recipes, and `dotnet tool restore` for the pinned local tools (CSharpier, dotnet-inspect). - [Bun](https://bun.sh) only for `just version` and the commit hook tooling; the commit hook runs @@ -41,7 +41,7 @@ just verify-consumers # build throwaway consumers against the packed p just pipeline-pack-validate # full local gate: restore, build, lint, test, pack, validate ``` -`just scrub` resets the repository (`bin`/`obj`, clean, forced restore, build-server shutdown) when a stale +`just scrub` resets the repository (build-server shutdown, `bin`/`obj` and `artifacts` deleted, forced restore) when a stale restore or compiler state is suspected. ## Commits @@ -58,9 +58,9 @@ A change is not complete until the affected documentation matches: - **`src/src//Sdk/README.md`** — the package's own README, shipped inside the `.nupkg`. Update it whenever a module's public API, defaults, readiness or endpoints change. - **`docs/wiki`** — the user-facing wiki aggregated by the purview-dev website. Update the topic page - ([Consumer Requirements](Consumer-Requirements.md), [Architecture](Architecture.md), - [Lifecycle](Lifecycle.md), [Networking](Networking.md), [Wait Strategies](Wait-Strategies.md), - [Modules](Modules.md), [Testing](Testing.md), [Packaging](Packaging.md), [Release Flow](Release-Flow.md)) + ([Consumer Requirements](../Consumer-Requirements.md), [Architecture](Architecture.md), + [Lifecycle](../guide/Lifecycle.md), [Networking](../guide/Networking.md), [Wait Strategies](../guide/Wait-Strategies.md), + [Modules](../Modules.md), [Testing](Testing.md), [Packaging](Packaging.md), [Release Flow](Release-Flow.md)) and `_Sidebar.md` when adding a page. - **`purview-build.json`** — the exhaustive `PackValidation.RequiredContent` manifest has to keep matching what the packages actually contain; see [Packaging](Packaging.md). @@ -76,6 +76,6 @@ A change is not complete until the affected documentation matches: ## Related -- [Contributing Modules](Contributing-Modules.md) — the module contract for new service packages. +- [Contributing Modules](../Contributing-Modules.md) — the module contract for new service packages. - [Packaging](Packaging.md) — package contents and validation rules. - [Release Flow](Release-Flow.md) — versioning and what CI does on a PR and on release. diff --git a/docs/wiki/Release-Flow.md b/docs/wiki/contributing/Release-Flow.md similarity index 90% rename from docs/wiki/Release-Flow.md rename to docs/wiki/contributing/Release-Flow.md index 05d95f8..5099d62 100644 --- a/docs/wiki/Release-Flow.md +++ b/docs/wiki/contributing/Release-Flow.md @@ -11,11 +11,11 @@ that end up in each nuspec. Versions use a `-prerelease.N` suffix until the stable 1.0.0 release, which will include the WSL Containers backend. Until then, consumers should pin an exact version rather than float, and each bump can change -the API or the [consumer requirements](Consumer-Requirements.md). +the API or the [consumer requirements](../Consumer-Requirements.md). ## Local commands -The `Justfile` wraps the common steps: +The `Justfile` wraps the common steps. The shared recipes live in `.build/just/` (copied verbatim from the `purview-buildsdk-justfile` skill); the root `Justfile` adds this repository's own: | Command | What it does | | --- | --- | @@ -23,8 +23,8 @@ The `Justfile` wraps the common steps: | `just test` | `dotnet test` across the solution, one test module at a time (see [Testing](Testing.md)). | | `just lint-check` / `just lint-fix` | CSharpier check / format over the repository root. | | `just pack` | Build (Debug) and `dotnet pack` into `./artifacts`. | -| `just verify-consumers` | Pack, then build throwaway consumer projects that assert the published consumer contract ([Consumer Requirements](Consumer-Requirements.md)). | -| `just scrub` | Delete `bin`/`obj`, clean, re-restore with `--force-evaluate`, and shut down the build server. | +| `just verify-consumers` | Pack, then build throwaway consumer projects that assert the published consumer contract ([Consumer Requirements](../Consumer-Requirements.md)). | +| `just scrub` | Shut down the build servers, delete `bin`/`obj` and `artifacts`, and re-restore with `--force-evaluate`. | | `just pipeline-pack-validate` | Shared pipeline: restore, build, lint, test, pack and **validate** the packages, without publishing. | ## The shared pipeline @@ -98,9 +98,9 @@ The shared workflow runs on **`ubuntu-latest`**, so the Linux agent builds the p `src/Directory.Build.props` sets `EnableWindowsTargeting=true`; removing it fails the pipeline with `NETSDK1100`. The agent has no WSL Containers, which is why the pipeline is filtered to `[Category=Unit]` — see -[Consumer Requirements](Consumer-Requirements.md) and [Testing](Testing.md). +[Consumer Requirements](../Consumer-Requirements.md) and [Testing](Testing.md). ## Related - [Packaging](Packaging.md) — the package contents and the validation manifest. -- [Contributing](Contributing.md) — the local workflow before raising a PR. +- [Contributing](README.md) — the local workflow before raising a PR. diff --git a/docs/wiki/Testing.md b/docs/wiki/contributing/Testing.md similarity index 86% rename from docs/wiki/Testing.md rename to docs/wiki/contributing/Testing.md index 4d781a8..920a36d 100644 --- a/docs/wiki/Testing.md +++ b/docs/wiki/contributing/Testing.md @@ -33,7 +33,7 @@ runtime fails the job instead of skipping every test. > The shared `purview-dev/build` workflow runs on **`ubuntu-latest`**, so the pipeline builds the portable > `net10.0`/`net11.0` projects and the `net11.0-windows…` test projects on Linux. That works because > `src/Directory.Build.props` sets `EnableWindowsTargeting=true`; without it the SDK reports `NETSDK1100`. -> See [Consumer Requirements](Consumer-Requirements.md) for what that workaround does and does not +> See [Consumer Requirements](../Consumer-Requirements.md) for what that workaround does and does not > cover. ```powershell @@ -48,7 +48,7 @@ to Docker, so a WSLC host runs the WSLC suites and a Docker-only host runs the D (`Docker.IntegrationTests` for the container contract, `Modules.Docker.IntegrationTests` for the nine service modules) skip themselves when no daemon is reachable, and the WSLC suites skip themselves when the host lacks the WSL Containers components. Set `PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl|docker` to turn that -skip into a failure — the CI integration jobs do. See [Backends: WSLC or Docker](Backends.md) for +skip into a failure — the CI integration jobs do. See [Backends: WSLC or Docker](../Backends.md) for consumer-facing setup and CI examples. ```powershell @@ -104,8 +104,9 @@ existed are never deleted, and the shared image store and host bind mounts are u The WSLC half used to be manual-only because no hosted runner was assumed to have WSL Containers. That is no longer true: GitHub's `windows-2025` runner is Windows Server 2025 with hardware nested virtualisation, -and `wsl --update --pre-release` installs a WSL build that includes `wslc`. The binary is not on `PATH`, so -the workflow adds `C:\Program Files\WSL` and calls it by absolute path. +and WSL Containers ships in the stable WSL channel, so `wsl --update` brings the runner to WSL 3.0.5 or +later, including `wslc`. The workflow checks `C:\Program Files\WSL\wslc.exe` and prints its version by +absolute path; the library itself finds `wslc` there without a `PATH` change. Coverage is split for cost: @@ -126,10 +127,10 @@ gh run watch ### Hosted runner notes Windows runners bill at 2× and the full module matrix pulls several GB of images on a cold runner, so the -full matrix is nightly rather than per-PR. `windows-2022` and Windows 10 do not support WSL Containers; -`windows-2025` is the only hosted option. The WSLC API surface is pinned by the -`Microsoft.WSL.Containers` package, so a hosted runner with a newer pre-release WSL may report the runtime -as incompatible. The workflow sets `PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl`, which turns that into a failed +full matrix is nightly rather than per-PR. The WSLC suites run on the hosted `windows-2025` runner; +GitHub's hosted `windows-2022` runner cannot run them. The WSLC API surface is pinned by the +`Microsoft.WSL.Containers` package (3.0.5), so a runner whose WSL is older than that floor, or newer than +the bundled SDK supports, reports the runtime as incompatible. The workflow sets `PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl`, which turns that into a failed job rather than a green run with every test skipped. ### Self-hosted runner prerequisites @@ -137,9 +138,10 @@ job rather than a green run with every test skipped. Register a **Windows x64** runner for this repository (or organisation) with the labels `self-hosted` and the custom **`wslc`** label, and install on that machine: -- Windows 11 (22H2 or later) or Windows Server 2025 with **WSL Containers**: - `wsl --install --no-distribution`, verified with `wsl --version` and `wslc version`. Windows 10 and - Windows Server 2022 do not support WSL Containers. +- A host that meets the + [host requirements](../Consumer-Requirements.md#host-requirements-wsl-containers-backend): x64, a Windows + where WSL 2 runs, virtualisation enabled, and **WSL 3.0.5 or later** from the stable channel + (`wsl --install --no-distribution` or `wsl --update`), verified with `wsl --version` and `wslc version`. - The **.NET 11 SDK** the repository pins in `global.json` (`11.0.100`). The job's first step prints `wsl --version` and `wslc version`, so a mis-provisioned runner fails @@ -164,12 +166,12 @@ startup; it cannot substitute for real runtime validation. `Wsl.UnitTests/ConsumerRequirementsTests.cs` guards the shape of the shipped library inside the normal unit run: the Windows build targets `.NETCoreApp,Version=v10.0`, targets `Windows10.0.19041.0` and declares only that OS platform. If the target framework ever drifts, that test fails — and -[Consumer Requirements](Consumer-Requirements.md), the package READMEs and the shipped +[Consumer Requirements](../Consumer-Requirements.md), the package READMEs and the shipped `buildTransitive` defaults all have to move with it. The behavioural side is covered by `just verify-consumers`, which packs the packages and builds throwaway consumer projects for every documented outcome (see -[Consumer Requirements](Consumer-Requirements.md#verifying-these-requirements)). It is deliberately +[Consumer Requirements](../Consumer-Requirements.md#verifying-these-requirements)). It is deliberately outside the `[Category=Unit]` filter because it packs and restores from nuget.org: ```powershell @@ -180,4 +182,4 @@ just verify-consumers -Keep # same, keeping the generated projects for inspec ## Related - [Architecture](Architecture.md) — session lifetime, the concurrency gate and the shared-store fallback. -- [Getting Started](Getting-Started.md) — running the tests locally. +- [Getting Started](../Getting-Started.md) — running the tests locally. diff --git a/docs/wiki/diagrams/package-architecture.c4 b/docs/wiki/diagrams/package-architecture.c4 new file mode 100644 index 0000000..cb73a4a --- /dev/null +++ b/docs/wiki/diagrams/package-architecture.c4 @@ -0,0 +1,77 @@ +// How the Purview.Containers packages fit together, and what each backend drives. +// Rendered on purview.dev in place of the Mermaid diagram in contributing/Architecture.md; +// change both in the same commit. +specification { + element package { + style { + shape rectangle + } + } + element consumer { + style { + shape person + color secondary + } + } + element external { + style { + shape rectangle + color muted + } + } +} + +model { + tests = consumer 'Your tests' { + description 'Reference the umbrella, or one module plus a backend' + } + umbrella = package 'Purview.Containers' { + description 'Umbrella: Core plus both backends, no code of its own' + } + modules = package 'Service modules' { + description 'PostgreSql, Redis, MsSql, MySql, RabbitMq, Azurite, Nats, Key Vault and Service Bus emulators' + } + core = package 'Purview.Containers.Core' { + description 'Backend-neutral contract, builders, wait strategies and ContainerBackends selection' + } + wsl = package 'Purview.Containers.Wsl' { + description 'WSLC backend: portable facades plus the x64 Windows implementation' + } + docker = package 'Purview.Containers.Docker' { + description 'Docker backend over Testcontainers' + } + wslcSdk = external 'Microsoft.WSL.Containers SDK' { + description 'Managed WSLC API' + } + wslcCli = external 'wslc CLI' { + description 'Bounded fallback for SDK-missing features' + } + wslcSession = external 'WSLC session' { + description 'One shared, process-wide session' + } + testcontainers = external 'Testcontainers' + dockerDaemon = external 'Docker daemon' + + tests -> umbrella 'references' + tests -> modules 'references' + umbrella -> core + umbrella -> wsl + umbrella -> docker + modules -> core 'references only' + wsl -> core 'implements IContainerBackend' + docker -> core 'implements IContainerBackend' + wsl -> wslcSdk 'lifecycle, images, networks' + wsl -> wslcCli 'entrypoint, copy, builds, reuse' + wslcSdk -> wslcSession + wslcCli -> wslcSession + docker -> testcontainers + testcontainers -> dockerDaemon +} + +views { + view packageArchitecture { + title 'Package architecture' + include * + autoLayout TopBottom + } +} diff --git a/docs/wiki/Backend-Capabilities.md b/docs/wiki/guide/Backend-Capabilities.md similarity index 98% rename from docs/wiki/Backend-Capabilities.md rename to docs/wiki/guide/Backend-Capabilities.md index 5e9b389..2c755f2 100644 --- a/docs/wiki/Backend-Capabilities.md +++ b/docs/wiki/guide/Backend-Capabilities.md @@ -1,5 +1,8 @@ # Backend capabilities and cancellation +Which container features `Purview.Containers` supports on WSL Containers and on Docker, where the +WSLC backend uses the managed SDK or the `wslc` CLI, and how timeouts and cancellation behave. + The Docker backend is implemented with Testcontainers for .NET. WSLC uses `Microsoft.WSL.Containers` 3.0.5 for lifecycle, images, named networks and aliases, Linux capabilities and session host-loopback support, with the `wslc` CLI only for capabilities missing from the managed diff --git a/docs/wiki/Connection-Strings.md b/docs/wiki/guide/Connection-Strings.md similarity index 96% rename from docs/wiki/Connection-Strings.md rename to docs/wiki/guide/Connection-Strings.md index daa3b26..c133fe5 100644 --- a/docs/wiki/Connection-Strings.md +++ b/docs/wiki/guide/Connection-Strings.md @@ -66,4 +66,4 @@ provider used before `Configure` throws `ConnectionStringProviderNotConfiguredEx ## Module reference -See [Modules](Modules.md) for each module's default connection string and any extra endpoint accessors. +See [Modules](../Modules.md) for each module's default connection string and any extra endpoint accessors. diff --git a/docs/wiki/Lifecycle.md b/docs/wiki/guide/Lifecycle.md similarity index 96% rename from docs/wiki/Lifecycle.md rename to docs/wiki/guide/Lifecycle.md index 04f646b..d5a812e 100644 --- a/docs/wiki/Lifecycle.md +++ b/docs/wiki/guide/Lifecycle.md @@ -1,6 +1,7 @@ # Lifecycle -Container lifecycle semantics for `Purview.Containers`. +How a `Purview.Containers` test container starts, stops and is disposed on WSL Containers or Docker: +the state model, cleanup guarantees, startup deadlines and container reuse. ## Public API diff --git a/docs/wiki/Networking.md b/docs/wiki/guide/Networking.md similarity index 95% rename from docs/wiki/Networking.md rename to docs/wiki/guide/Networking.md index 8c4e882..1adff28 100644 --- a/docs/wiki/Networking.md +++ b/docs/wiki/guide/Networking.md @@ -1,5 +1,8 @@ # Networking +Container networking in `Purview.Containers` on WSL Containers and Docker: bridged networking, +mapped host ports, managed networks with alias DNS, and WSLC host loopback. + Containers default to `ContainerNetworkingMode.Bridged`. The default WSLC bridge supports container-to-container IP traffic but not container-name DNS. `None` disables networking. diff --git a/docs/wiki/Wait-Strategies.md b/docs/wiki/guide/Wait-Strategies.md similarity index 60% rename from docs/wiki/Wait-Strategies.md rename to docs/wiki/guide/Wait-Strategies.md index 319a87a..4ff7b95 100644 --- a/docs/wiki/Wait-Strategies.md +++ b/docs/wiki/guide/Wait-Strategies.md @@ -2,31 +2,36 @@ Composable readiness waits. **A started WSLC container is not necessarily a ready service** — `Container.Start()` returns once the init process is running; readiness is checked separately. -> **Status: implemented.** Verified by integration tests (`tests/Wsl.IntegrationTests/WaitStrategyTests.cs`). - ## Model +Every strategy implements `IWaitStrategy`, and the built-in ones derive from `WaitStrategy`, which adds +the fluent `WithTimeout`, `WithInterval` and `WithRetries`: + +```csharp +public interface IWaitStrategy +{ + TimeSpan? Timeout { get; } // null: the container's StartupTimeout + TimeSpan Interval { get; } // default 250 ms + int? Retries { get; } // optional maximum number of failed checks + + Task UntilAsync(WaitContext context, CancellationToken cancellationToken); +} + +// WaitContext: Container, NetworkIp, GetHostPort(ushort containerPort), FirstHostPort ``` -IWaitStrategy - TimeSpan? Timeout // null → container StartupTimeout - TimeSpan Interval // default 250 ms - int? Retries // optional max failed checks - Task UntilAsync(WaitContext context, CancellationToken ct) - -WaitContext { IContainer Container; string? NetworkIp; int? GetHostPort(ushort); int? FirstHostPort; } - -Wait (factory) - ForContainerRunning() - ForExitCode(long expectedExitCode = 0) - ForTcpPort(ushort containerPort, TimeSpan? connectTimeout = null) - ForHttp(string path = "/") → HttpWaitStrategy { ForPort, ForScheme, ForStatusCode, ForStatusPredicate, ForHeader, AllowInsecureTls } - ForLogMessage(string) | ForLogMessage(Regex) - ForCommand(params string[]) → CommandWaitStrategy { ForExitCode } - ForCustom(Func>) - ForAll(params IWaitStrategy[]) | ForAny(params IWaitStrategy[]) - -WaitStrategy.WithTimeout / .WithInterval / .WithRetries (fluent) -``` + +The `Wait` factory creates them: + +| Factory | Ready when | +| --- | --- | +| `Wait.ForContainerRunning()` | The init process is running (not a service-readiness check) | +| `Wait.ForExitCode(long exitCode = 0)` | A one-shot container exits with the expected code | +| `Wait.ForTcpPort(ushort containerPort, TimeSpan? connectTimeout = null)` | A TCP connection to the mapped host port succeeds | +| `Wait.ForHttp(string path = "/")` | An HTTP(S) request succeeds; returns `HttpWaitStrategy` with `ForPort`, `ForScheme`, `ForStatusCode`, `ForStatusPredicate`, `ForHeader` and `AllowInsecureTls` | +| `Wait.ForLogMessage(string)`, `Wait.ForLogMessage(Regex)` | The container output contains the message | +| `Wait.ForCommand(params string[] command)` | A command run in the container succeeds. It returns `WaitStrategy`; the instance is a `CommandWaitStrategy`, whose `ForExitCode(int)` sets a different expected code | +| `Wait.ForCustom(Func>)` | Your predicate returns `true` | +| `Wait.ForAll(params IWaitStrategy[])`, `Wait.ForAny(params IWaitStrategy[])` | Every one, or any one, of the strategies is ready | - Waits run inside `StartAsync()` after the container starts. `StartAsync` only returns once every configured strategy is ready (or throws `ContainerTimeoutException`). - Default timeout = the container's `StartupTimeout` (5 min). This is also the total managed startup diff --git a/docs/wiki/index.md b/docs/wiki/index.md deleted file mode 100644 index 434f717..0000000 --- a/docs/wiki/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Purview Containers - -Throwaway Linux containers for .NET integration testing — Testcontainers-style APIs for **Microsoft WSL -Containers (WSLC)** with no Docker installation, and for **Docker** through Testcontainers. The same test -code runs on either runtime; see [Backends: WSLC or Docker](Backends.md). - -[Get started](Getting-Started.md){ .md-button .md-button--primary } -[Choose a backend](Backends.md){ .md-button } - -## Guides - -- [Getting Started](Getting-Started.md) -- [Using in your tests (auto)](Using-in-Your-Tests.md) -- [Backends: WSLC or Docker](Backends.md) -- [Consumer requirements](Consumer-Requirements.md) -- [Architecture](Architecture.md) -- [Lifecycle](Lifecycle.md) -- [Networking](Networking.md) -- [Wait strategies](Wait-Strategies.md) -- [Modules](Modules.md) -- [Testing](Testing.md) -- [Packaging](Packaging.md) -- [Release flow](Release-Flow.md) -- [Contributing modules](Contributing-Modules.md) -- [Contributing](Contributing.md) diff --git a/samples/getting-started/WslSample/WslSample.csproj b/samples/getting-started/WslSample/WslSample.csproj index 0ef4530..7823ddd 100644 --- a/samples/getting-started/WslSample/WslSample.csproj +++ b/samples/getting-started/WslSample/WslSample.csproj @@ -9,7 +9,7 @@ Exe net11.0-windows10.0.19041.0 x64 - + 10.0.26100.80 enable enable diff --git a/skills/purview-containers-capabilities/SKILL.md b/skills/purview-containers-capabilities/SKILL.md index 5e3c197..4163b03 100644 --- a/skills/purview-containers-capabilities/SKILL.md +++ b/skills/purview-containers-capabilities/SKILL.md @@ -14,7 +14,8 @@ metadata: Docker uses Testcontainers for .NET. WSLC ordinarily uses its managed SDK (3.0.5): lifecycle, images, named networks and aliases, Linux capabilities and host loopback are SDK-backed; entrypoint/user/labels, -reuse, image builds and copy need the `wslc` CLI on PATH. The CLI targets the same +reuse, image builds and copy need the `wslc` CLI that ships with WSL (found on PATH or at +`%ProgramFiles%\WSL\wslc.exe`). The CLI targets the same SDK-owned session and image store, not the user's default CLI session. There is no Docker dependency on the WSLC path and no silent runtime fallback when an operation is unsupported. diff --git a/skills/purview-containers-consumer-requirements/SKILL.md b/skills/purview-containers-consumer-requirements/SKILL.md index 977b67f..30b2a37 100644 --- a/skills/purview-containers-consumer-requirements/SKILL.md +++ b/skills/purview-containers-consumer-requirements/SKILL.md @@ -25,7 +25,8 @@ A consumer of any backend other than WSL needs only a portable `net10.0` or `net .NET 9 are unsupported. WSLC features missing from the managed SDK (entrypoint/user/labels, reuse, copy -and Dockerfile builds) additionally require `wslc` on PATH; networks/aliases, Linux capabilities and +and Dockerfile builds) additionally require the `wslc` CLI that ships with WSL (found on PATH or at +`%ProgramFiles%\WSL\wslc.exe`); networks/aliases, Linux capabilities and host loopback use the managed SDK 3.0.5. The ordinary SDK-only path is unchanged. Use `purview-containers-capabilities` for the feature/cancellation boundary. @@ -44,7 +45,7 @@ A Windows-targeting project binds the implementation directly, with no run-time ```xml net10.0-windows10.0.19041.0 - x64 + x64 10.0.26100.80 ``` @@ -59,9 +60,29 @@ value you have not chosen. | --- | --- | --- | | 1 | **.NET 10 or .NET 11** (.NET 8 and .NET 9 are unsupported) | the package ships `lib/net10.0/` and `lib/net11.0/` (facades) plus `lib/net10.0-windows10.0.19041/` and `lib/net11.0-windows10.0.19041/` (implementations) | | 2 | **A Windows target framework that names the OS version** — *only* if you want the implementation bound directly | the `Microsoft.WSL.Containers` projection ships Windows assets only | -| 3 | **64-bit** — `PlatformTarget` `x64`/`arm64`, or a matching `RuntimeIdentifier` | the native `wslcsdk.dll` ships for `win-x64` and `win-arm64` only | +| 3 | **x64** — `PlatformTarget` `x64` (the default), or the `win-x64` `RuntimeIdentifier` | the implementation is compiled for x64 and only the `win-x64` native `wslcsdk.dll` is deployed; ARM64 and x86 are not supported | | 4 | **`WindowsSdkPackageVersion` ≥ `10.0.26100.80`** | the projection is compiled against `Microsoft.Windows.SDK.NET` `10.0.26100.79`, and the pack the SDK resolves for a `10.0.19041.0` target framework is older | -| 5 | **Windows 11 or Windows Server 2025 with WSL Containers**, to actually run anything | the library drives WSLC; it never installs or updates it for you; a Windows target framework does not imply Windows 10 runtime support | +| 5 | **A host that can run WSL Containers**, to actually run anything (see below) | the library drives WSLC; it never installs or updates it for you | + +### Host requirements + +- **x64 only.** A non-x64 Windows-target consumer fails the build with `PCC0002`; a platform-neutral + consumer in a non-x64 process sees `wsl` reported unavailable ("supports x64 processes only"), so + automatic selection falls through to Docker. +- **WSL 3.0.5 or later** from the normal stable channel — `wsl --install --no-distribution` for a new + install, or `wsl --update`. The `--pre-release` channel is not needed. The floor follows the bundled + `Microsoft.WSL.Containers` SDK (3.0.5) and is checked at run time. +- **Windows wherever WSL 2 runs**: Windows 11, Windows 10 version 2004 (build 19041) or later with + current updates, or Windows Server 2025. The library adds no Windows-version check; WSL reports an + unsupported Windows as `WSL_E_OS_NOT_SUPPORTED`. +- **Virtualisation** enabled in firmware plus the Virtual Machine Platform feature + (`wsl --install --no-distribution` enables it; restart required). +- **`wslc`** ships with WSL and is needed only for the CLI-backed features; it is found on PATH or at + `%ProgramFiles%\WSL\wslc.exe`. + +Tested on Windows 11 23H2 and Windows Server 2025; Windows 10 and Windows Server 2022 are untested. +`GetInfoAsync()` and `ContainerBackendUnavailableException` name the fix for each shortfall (for +example "Run 'wsl --update'"). ### Always spell out the Windows version @@ -101,7 +122,7 @@ package, and use `PURVIEW_CONTAINERS_BACKEND` to pin which one runs. | Error | Raised by | Means | Fix | | --- | --- | --- | --- | | `PCC0001` | the shipped guard target | the target framework is neither .NET 10 nor .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 `PlatformTarget`, set it to `x64`/`arm64`, or choose a matching `RuntimeIdentifier` | +| `PCC0002` | the shipped guard target | the consumer is not x64 (ARM64 and x86 are not supported) | remove `PlatformTarget` (x64 is the default), set it to `x64`, or choose the `win-x64` `RuntimeIdentifier` | | `CS1705` naming `Microsoft.Windows.SDK.NET` | the compiler | the resolved Windows SDK targeting pack is older than the projection's | pin `WindowsSdkPackageVersion` to `10.0.26100.80` | | `CS0234`/`CS0246` for `Microsoft.WSL`/`Purview` types | the compiler | the package contributed no compile assets — an unsupported target framework, or an unverified escape hatch | fix the target framework; `PCC0001` says the same thing more clearly | | `NETSDK1100` | the SDK | building a Windows-targeted project on a non-Windows agent | set `EnableWindowsTargeting=true` | @@ -122,7 +143,8 @@ The repository proves every row above rather than asserting it: compiler-generated async state machines (runtime-async is on). If either drifts, the test fails, and this page, the package READMEs and the `buildTransitive` defaults all have to move with it. - `just verify-consumers` proves the **behaviour**: it packs, then builds throwaway consumer projects - for every documented outcome, including the guard errors (`PlatformTarget=x86` → `PCC0002`; + for every documented outcome, including the guard errors (`PlatformTarget=x86`, `PlatformTarget=arm64` + and `RuntimeIdentifier=win-arm64` → `PCC0002`; `net8.0-windows` → `PCC0001`; `net11.0-windows` without an OS version → `PCC0001`). It sits outside the `[Category=Unit]` filter because it restores from nuget.org. diff --git a/skills/purview-containers-quickstart/SKILL.md b/skills/purview-containers-quickstart/SKILL.md index 2de75b8..0105ffc 100644 --- a/skills/purview-containers-quickstart/SKILL.md +++ b/skills/purview-containers-quickstart/SKILL.md @@ -81,8 +81,13 @@ A **named** backend never silently falls back: if it cannot run, the test fails diagnostics. That is usually what you want in CI. The library never installs a runtime. `WslContainerRuntime.GetInfoAsync()` and -`DockerContainerBackend.GetInfoAsync()` report what is missing. Verify a host with `wsl --version` and -`wslc version`, or `docker info`. +`DockerContainerBackend.GetInfoAsync()` report what is missing and how to fix it. Verify a host with +`wsl --version` and `wslc version`, or `docker info`. + +WSLC needs an **x64** Windows host where WSL 2 runs (Windows 11, Windows 10 version 2004 or later, or +Windows Server 2025) with virtualisation enabled and **WSL 3.0.5 or later** from the stable channel: +`wsl --install --no-distribution`, or `wsl --update`. ARM64 is not supported; on a non-x64 process +`wsl` reports unavailable and automatic selection falls through to Docker. ## A generic container diff --git a/skills/purview-containers-testing/SKILL.md b/skills/purview-containers-testing/SKILL.md index 87d122e..25ef9ec 100644 --- a/skills/purview-containers-testing/SKILL.md +++ b/skills/purview-containers-testing/SKILL.md @@ -73,8 +73,9 @@ Print `wsl --version` and `wslc version` in WSLC jobs so provisioning failures a ## CI shape - **Docker half** — runs on every pull request, on `ubuntu-latest`. -- **WSLC contract** — runs on every pull request on `windows-2025`, with nested virtualisation and - WSL Containers installed by the workflow. +- **WSLC contract** — runs on every pull request on the hosted `windows-2025` runner (GitHub's hosted + `windows-2022` runner cannot run the WSLC suites), with nested virtualisation and the stable WSL + brought to 3.0.5 or later by `wsl --update` in the workflow. - **Full WSLC matrix** — runs nightly on `windows-2025`, or on demand on a hosted or self-hosted runner: ```bash @@ -86,7 +87,8 @@ Print `wsl --version` and `wslc version` in WSLC jobs so provisioning failures a shared WSLC image store is never contended. Use `scope: contract` for the backend contract alone. Self-hosted runner prerequisites: a **Windows x64** runner labelled `self-hosted` and `wslc`, with -WSL Containers installed (`wsl --install --no-distribution`) and the pinned .NET SDK. Tell +virtualisation enabled, WSL 3.0.5 or later from the stable channel (`wsl --install --no-distribution` +or `wsl --update`) and the pinned .NET SDK. ARM64 runners are not supported. Tell `actionlint` about the custom label in `.github/actionlint.yaml`. > The shared pipeline runs on `ubuntu-latest`, so it builds the portable `net10.0`/`net11.0` projects **and** diff --git a/src/src/AzureKeyVaultEmulator/Sdk/README.md b/src/src/AzureKeyVaultEmulator/Sdk/README.md index dda336a..cf3975e 100644 --- a/src/src/AzureKeyVaultEmulator/Sdk/README.md +++ b/src/src/AzureKeyVaultEmulator/Sdk/README.md @@ -14,10 +14,10 @@ container can hand out clients that are already wired for the emulator. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -109,5 +109,5 @@ certificate is installed into the trust store, the default client options work. - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. - [Azure Key Vault Emulator](https://github.com/james-gould/azure-keyvault-emulator) — the emulator itself. diff --git a/src/src/AzureServiceBusEmulator/Sdk/README.md b/src/src/AzureServiceBusEmulator/Sdk/README.md index 9954da7..27c286e 100644 --- a/src/src/AzureServiceBusEmulator/Sdk/README.md +++ b/src/src/AzureServiceBusEmulator/Sdk/README.md @@ -14,10 +14,10 @@ its state in SQL Server), and needs a backend package (`Purview.Containers.Wsl` ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -25,7 +25,7 @@ its state in SQL Server), and needs a backend package (`Purview.Containers.Wsl` - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. - **SQL Server sidecar:** the default is SQL Server 2025 (`mcr.microsoft.com/mssql/server:2025-latest`), - which is x64 only and needs at least 2000 MB of memory in the WSLC session VM or Docker host. On ARM64, + which is x64 only and needs at least 2000 MB of memory in the WSLC session VM or Docker host. On an ARM64 Docker host (the WSLC backend is x64 only), `WithSqlServerImage("mcr.microsoft.com/azure-sql-edge:latest")` is an alternative the emulator supports. SQL Server 2022 does not start on WSLC (it fails to create `/.system` as the non-root `mssql` user). - The emulator is for local development and testing only; it is not a replacement for Azure Service Bus. @@ -168,7 +168,8 @@ What this module and its tests have established: time and any unconsumed messages are lost with the container. - **Slow, memory-hungry start.** About a minute per instance, and the SQL Server sidecar needs at least 2000 MB. Running several emulators at once multiplies both, which is why sharing one is recommended. -- **x64 only by default.** SQL Server 2025 has no ARM64 image. +- **x64 only by default.** SQL Server 2025 has no ARM64 image (this matters only on an ARM64 Docker + host; the WSLC backend is x64 only). - **Host connections only.** The connection strings point at `127.0.0.1` and the mapped host ports. An application under test that runs in another container cannot use them (`ConnectionMode.Container` is not supported). @@ -205,5 +206,5 @@ known. - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/Networking.md) — how containers reach each other by IP. +- [Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Networking.md) — how containers reach each other by IP. - [Azure Service Bus Emulator](https://learn.microsoft.com/azure/service-bus-messaging/overview-emulator) — the emulator itself. diff --git a/src/src/Azurite/Sdk/README.md b/src/src/Azurite/Sdk/README.md index 0519b27..ff6577d 100644 --- a/src/src/Azurite/Sdk/README.md +++ b/src/src/Azurite/Sdk/README.md @@ -12,10 +12,10 @@ See the [Getting Started guide](https://github.com/purview-dev/containers/blob/m ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the diff --git a/src/src/Containers/Sdk/README.md b/src/src/Containers/Sdk/README.md index 8e27633..4e5c43e 100644 --- a/src/src/Containers/Sdk/README.md +++ b/src/src/Containers/Sdk/README.md @@ -59,8 +59,8 @@ not change. - **.NET 10 or .NET 11** (.NET 8 and .NET 9 are not supported). The abstractions and service modules are portable; the WSL Containers backend is multi-target and stays dormant on non-Windows hosts. See the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). -- Either a Windows 10/11 host with **WSL Containers** (`wsl --install --no-distribution`) or a reachable - **Docker** daemon. +- Either an x64 Windows host with **WSL 3.0.5 or later** (`wsl --install --no-distribution` or + `wsl --update`; ARM64 is not supported) or a reachable **Docker** daemon. ## Documentation diff --git a/src/src/Core/Sdk/README.md b/src/src/Core/Sdk/README.md index 1c9a564..ef1c8d8 100644 --- a/src/src/Core/Sdk/README.md +++ b/src/src/Core/Sdk/README.md @@ -43,7 +43,7 @@ Defaults: total startup 5 minutes; exec/exit wait 1 minute; stop 15 seconds; cle copy/read/log snapshots 1 minute. Fluent timeout overrides and cancellation tokens are supported. Native synchronous WSLC calls cannot be safely interrupted; these are managed deadlines, not a hard runtime isolation guarantee. See the -[capability contract](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backend-Capabilities.md). +[capability contract](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Backend-Capabilities.md). ## Backend registration diff --git a/src/src/Docker/Sdk/README.md b/src/src/Docker/Sdk/README.md index a6d3024..f824013 100644 --- a/src/src/Docker/Sdk/README.md +++ b/src/src/Docker/Sdk/README.md @@ -61,7 +61,7 @@ PURVIEW_CONTAINERS_BACKEND=docker # or "auto" (the default) to probe WSLC fi one minute for exec/copy/read/log snapshots, 15 seconds for stop and 30 seconds for cleanup. Reuse follows Testcontainers semantics and disables normal reaper cleanup; `DeleteAsync` removes retained containers explicitly. See - [capabilities and ownership](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backend-Capabilities.md). + [capabilities and ownership](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Backend-Capabilities.md). - Named volumes created through `WithVolumeMount` are tracked by the backend. Set `ContainerCleanup.CleanUpVolumesOnExit` (or `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true`) before creating containers to force-remove those containers and the volumes the backend created when the process exits; diff --git a/src/src/MsSql/Sdk/README.md b/src/src/MsSql/Sdk/README.md index ab2572d..9346b49 100644 --- a/src/src/MsSql/Sdk/README.md +++ b/src/src/MsSql/Sdk/README.md @@ -11,10 +11,10 @@ connection-string generation and readiness probing. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the diff --git a/src/src/MySql/Sdk/README.md b/src/src/MySql/Sdk/README.md index fd72a58..65075fb 100644 --- a/src/src/MySql/Sdk/README.md +++ b/src/src/MySql/Sdk/README.md @@ -11,10 +11,10 @@ connection-string generation. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -65,4 +65,4 @@ strategy with `WithWaitStrategy(...)` if you need different behaviour. - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/Nats/Sdk/README.md b/src/src/Nats/Sdk/README.md index e22ea31..27d2c61 100644 --- a/src/src/Nats/Sdk/README.md +++ b/src/src/Nats/Sdk/README.md @@ -11,10 +11,10 @@ package — bring your own client. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -54,4 +54,4 @@ with `WithWaitStrategy(...)`. Endpoint accessors resolve the mapped host ports, - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/PostgreSql/Sdk/README.md b/src/src/PostgreSql/Sdk/README.md index fef7ef2..50e6990 100644 --- a/src/src/PostgreSql/Sdk/README.md +++ b/src/src/PostgreSql/Sdk/README.md @@ -11,10 +11,10 @@ See the [Getting Started guide](https://github.com/purview-dev/containers/blob/m ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -59,4 +59,4 @@ your own with `WithWaitStrategy(...)`. Call `GetConnectionString()` after `Start - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/RabbitMq/Sdk/README.md b/src/src/RabbitMq/Sdk/README.md index 0473edb..be389a5 100644 --- a/src/src/RabbitMq/Sdk/README.md +++ b/src/src/RabbitMq/Sdk/README.md @@ -11,10 +11,10 @@ bring your own client. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -66,4 +66,4 @@ startup failure (`eacces` reading `.erlang.cookie`). See - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/Redis/Sdk/README.md b/src/src/Redis/Sdk/README.md index 9e8050b..92612ed 100644 --- a/src/src/Redis/Sdk/README.md +++ b/src/src/Redis/Sdk/README.md @@ -11,10 +11,10 @@ package — bring your own client. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -61,4 +61,4 @@ await using var garnet = new RedisBuilder("ghcr.io/microsoft/garnet:latest").Bui - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. From 011a004e7dec60ffdfcbeb493f544f34d57c2377 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Wed, 18 Nov 2026 16:51:11 +0000 Subject: [PATCH 13/14] fix(wsl): keep the requirement messages SDK-free so unit tests run on Linux The WslRequirements Describe(Component ...) tests failed on the Linux CI agent with TypeInitializationException: touching any Microsoft.WSL.Containers type runs that assembly's module initializer, which loads the Windows-only native wslcsdk.dll. Mirror the SDK's Component flags as WslComponent, with values taken from the SDK's own enum constants (folded at compile time, so they cannot drift and nothing loads the SDK), and convert at the one call site in WslContainerRuntime. AGENTS.md now states the rule and how to reproduce the Linux condition locally. --- AGENTS.md | 17 ++++++++++ src/src/Wsl/WslContainerRuntime.cs | 5 ++- src/src/Wsl/WslRequirements.cs | 32 ++++++++++++++----- .../Wsl.UnitTests/WslRequirementsTests.cs | 9 +++--- 4 files changed, 49 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5514971..f6c5257 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -239,6 +239,23 @@ whenever a target framework, a backend package or the `buildTransitive` assets c - Use the shared `WslcTest` helper in `src/tests/SharedTestingFramework` for WSLC integration skip/availability checks; the Docker suites use their own `DockerTest` helper. Unit tests may use the modules' `BuildConfigurationForTesting()` internal hook. +- **Unit tests must never load the WSL Containers SDK at run time.** The `*.UnitTests` projects run on + the shared **Linux** CI agent (`ubuntu-latest`). The `Microsoft.WSL.Containers` assembly's module + initializer loads the Windows-only native `wslcsdk.dll`, so the first run-time use of *any* SDK + type fails there with `TypeInitializationException` / `DllNotFoundException` (`Unable to load shared + library 'wslcsdk.dll'`), even though the same test passes on a Windows machine. In a unit test (and + in any code path a unit test reaches), never pass, box, construct, call or enumerate an SDK type + such as `Component`, `ServiceVersion` or `WslcService`. + - Keep testable logic SDK-free and map SDK values at the single call site that already runs + against the SDK. For example, `WslComponent` (in `WslRequirements.cs`) mirrors the SDK's + `Component` flags, and `WslContainerRuntime.GetInfoAsync` converts with + `(WslComponent)(int)component`. + - When mirroring an SDK enum, define its values *from* the SDK constants + (`VirtualMachinePlatform = Sdk.Component.VirtualMachinePlatform`). The compiler folds them into + this assembly, so the values cannot drift and nothing loads the SDK. + - Reproduce the Linux condition locally before pushing: delete every `wslcsdk.dll` under + `src/tests/Wsl.UnitTests/bin//net11.0-windows10.0.19041.0/` and run + `Wsl.UnitTests`; rebuild to restore it. - `Wsl.UnitTests/ConsumerRequirementsTests.cs` guards the published target framework of the Windows build this project binds (`.NETCoreApp,Version=v11.0` plus `Windows10.0.19041.0`), and `Wsl.UnitTests/BuildFeatureTests.cs` guards that the net11.0 build has no compiler-generated async diff --git a/src/src/Wsl/WslContainerRuntime.cs b/src/src/Wsl/WslContainerRuntime.cs index f5a7d2c..98e9f4e 100644 --- a/src/src/Wsl/WslContainerRuntime.cs +++ b/src/src/Wsl/WslContainerRuntime.cs @@ -81,7 +81,10 @@ public async Task GetInfoAsync(CancellationToken cancel var serviceVersion = WslcService.GetVersion(); Version installed = new((int)serviceVersion.Major, (int)serviceVersion.Minor, (int)serviceVersion.Revision); var missing = WslcService.GetMissingComponents(); - List reasons = [.. missing.Select(component => WslRequirements.Describe(component, installed))]; + List reasons = + [ + .. missing.Select(component => WslRequirements.Describe((WslComponent)(int)component, installed)), + ]; // The SDK reports a WSL that is too old for it only indirectly, so the floor is checked here. var tooOld = WslRequirements.DescribeVersion(installed); diff --git a/src/src/Wsl/WslRequirements.cs b/src/src/Wsl/WslRequirements.cs index 9396660..5bee5ef 100644 --- a/src/src/Wsl/WslRequirements.cs +++ b/src/src/Wsl/WslRequirements.cs @@ -1,6 +1,6 @@ using System.Reflection; using System.Runtime.InteropServices; -using Microsoft.WSL.Containers; +using Sdk = Microsoft.WSL.Containers; namespace Purview.Containers.Wsl; @@ -15,6 +15,20 @@ namespace Purview.Containers.Wsl; /// WSL_E_OS_NOT_SUPPORTED HRESULT it raises on an unsupported Windows). The one floor enforced /// here is the WSL version, because the bundled SDK needs a WSL at least as new as itself. /// +/// +/// The WSL Containers SDK's missing-component flags (Microsoft.WSL.Containers.Component), mirrored +/// here so describing a component never touches the SDK assembly: its module initializer loads the +/// Windows-only native wslcsdk.dll, which would fail anywhere else (for example the Linux CI +/// agent that runs the unit tests). Each value is the SDK's own enum constant, which the compiler folds +/// into this assembly: the values cannot drift, and nothing here loads the SDK at run time. +/// +enum WslComponent +{ + VirtualMachinePlatform = Sdk.Component.VirtualMachinePlatform, + WslPackage = Sdk.Component.WslPackage, + SdkNeedsUpdate = Sdk.Component.SdkNeedsUpdate, +} + static class WslRequirements { /// WSL_E_OS_NOT_SUPPORTED: the Windows version cannot run WSL Containers. @@ -47,18 +61,20 @@ static class WslRequirements + "Run the tests as an x64 process, or use the Docker backend."; /// The fix for one component the SDK reports as missing. - internal static string Describe(Component component, Version? installed) => + internal static string Describe(WslComponent component, Version? installed) => component switch { - Component.VirtualMachinePlatform => + WslComponent.VirtualMachinePlatform => "The Virtual Machine Platform Windows feature is not enabled. Enable virtualisation in the " + $"firmware, run '{InstallCommand}' from an elevated terminal (or enable 'Virtual Machine " + "Platform' in Windows Features), and restart Windows.", - Component.WslPackage => $"WSL is not installed, or is too old for WSL Containers. Run '{InstallCommand}' " - + $"(or '{UpdateCommand}' if WSL is already installed); WSL {MinimumWslVersion} or later is required.", - Component.SdkNeedsUpdate => $"The installed WSL{(installed is null ? string.Empty : $" ({installed})")} is " - + $"newer than the WSL Containers SDK bundled with Purview.Containers.Wsl ({SdkVersion}). Update the " - + "Purview.Containers.Wsl package to a release built against this WSL.", + WslComponent.WslPackage => + $"WSL is not installed, or is too old for WSL Containers. Run '{InstallCommand}' " + + $"(or '{UpdateCommand}' if WSL is already installed); WSL {MinimumWslVersion} or later is required.", + WslComponent.SdkNeedsUpdate => + $"The installed WSL{(installed is null ? string.Empty : $" ({installed})")} is " + + $"newer than the WSL Containers SDK bundled with Purview.Containers.Wsl ({SdkVersion}). Update the " + + "Purview.Containers.Wsl package to a release built against this WSL.", _ => $"WSL Containers reports a missing component: {component}. Run '{UpdateCommand}'.", }; diff --git a/src/tests/Wsl.UnitTests/WslRequirementsTests.cs b/src/tests/Wsl.UnitTests/WslRequirementsTests.cs index 5cde4ed..4c2c518 100644 --- a/src/tests/Wsl.UnitTests/WslRequirementsTests.cs +++ b/src/tests/Wsl.UnitTests/WslRequirementsTests.cs @@ -1,5 +1,4 @@ using System.Runtime.InteropServices; -using Microsoft.WSL.Containers; namespace Purview.Containers.Wsl; @@ -45,17 +44,17 @@ public async Task DescribeVersion_BelowTheFloor_NamesTheMinimumAndTheFix(int maj [Test] public async Task Describe_VirtualMachinePlatform_ExplainsTheWindowsFeature() { - var reason = WslRequirements.Describe(Component.VirtualMachinePlatform, installed: null); + var reason = WslRequirements.Describe(WslComponent.VirtualMachinePlatform, installed: null); await Assert.That(reason).Contains("Virtual Machine Platform"); await Assert.That(reason).Contains("wsl --install --no-distribution"); - await Assert.That(reason).DoesNotContain(nameof(Component.VirtualMachinePlatform)); + await Assert.That(reason).DoesNotContain(nameof(WslComponent.VirtualMachinePlatform)); } [Test] public async Task Describe_WslPackage_GivesTheInstallCommandAndTheMinimum() { - var reason = WslRequirements.Describe(Component.WslPackage, installed: null); + var reason = WslRequirements.Describe(WslComponent.WslPackage, installed: null); await Assert.That(reason).Contains("wsl --install --no-distribution"); await Assert.That(reason).Contains("wsl --update"); @@ -65,7 +64,7 @@ public async Task Describe_WslPackage_GivesTheInstallCommandAndTheMinimum() [Test] public async Task Describe_SdkNeedsUpdate_PointsAtThePackageNotWsl() { - var reason = WslRequirements.Describe(Component.SdkNeedsUpdate, new Version(3, 1, 0)); + var reason = WslRequirements.Describe(WslComponent.SdkNeedsUpdate, new Version(3, 1, 0)); await Assert.That(reason).Contains("3.1.0"); await Assert.That(reason).Contains("Update the Purview.Containers.Wsl package"); From 2a2f75cd83eef5421d0a5df47cec4f660049faf9 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Wed, 18 Nov 2026 17:00:25 +0000 Subject: [PATCH 14/14] ci: move actions/checkout and actions/setup-dotnet to their Node.js 24 majors GitHub deprecated Node.js 20 for actions and was forcing checkout@v4 and setup-dotnet@v4 onto Node.js 24 with a warning. Use checkout@v7 and setup-dotnet@v6, which target Node.js 24 natively, in the workflows and in the CI examples in Backends.md. A self-hosted runner needs 2.327.1 or later, now listed in the Testing prerequisites. --- .github/workflows/integration-wsl.yml | 8 ++++---- .github/workflows/pr.yml | 8 ++++---- docs/wiki/Backends.md | 8 ++++---- docs/wiki/contributing/Testing.md | 2 ++ 4 files changed, 14 insertions(+), 12 deletions(-) diff --git a/.github/workflows/integration-wsl.yml b/.github/workflows/integration-wsl.yml index 60087ec..98c8655 100644 --- a/.github/workflows/integration-wsl.yml +++ b/.github/workflows/integration-wsl.yml @@ -54,12 +54,12 @@ jobs: PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 with: ref: ${{ inputs.ref || github.ref }} - name: Set up .NET - uses: actions/setup-dotnet@v4 + uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json (and the other workflows). dotnet-version: "11.0.100" @@ -140,12 +140,12 @@ jobs: PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 with: ref: ${{ inputs.ref || github.ref }} - name: Set up .NET - uses: actions/setup-dotnet@v4 + uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json (and the other workflows). dotnet-version: "11.0.100" diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index e05fb94..758dd3b 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -48,8 +48,8 @@ jobs: PURVIEW_CONTAINERS_BACKEND: docker PURVIEW_CONTAINERS_REQUIRE_BACKEND: docker steps: - - uses: actions/checkout@v4 - - uses: actions/setup-dotnet@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json. dotnet-version: "11.0.100" @@ -73,8 +73,8 @@ jobs: PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 - - uses: actions/setup-dotnet@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json. dotnet-version: "11.0.100" diff --git a/docs/wiki/Backends.md b/docs/wiki/Backends.md index 02d8821..0a24857 100644 --- a/docs/wiki/Backends.md +++ b/docs/wiki/Backends.md @@ -391,8 +391,8 @@ jobs: # 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 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: dotnet-version: 10.0.x - run: dotnet restore @@ -424,8 +424,8 @@ change: PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 - - uses: actions/setup-dotnet@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: dotnet-version: 11.0.x - name: Install WSL Containers diff --git a/docs/wiki/contributing/Testing.md b/docs/wiki/contributing/Testing.md index 920a36d..2275b5a 100644 --- a/docs/wiki/contributing/Testing.md +++ b/docs/wiki/contributing/Testing.md @@ -143,6 +143,8 @@ Register a **Windows x64** runner for this repository (or organisation) with the where WSL 2 runs, virtualisation enabled, and **WSL 3.0.5 or later** from the stable channel (`wsl --install --no-distribution` or `wsl --update`), verified with `wsl --version` and `wslc version`. - The **.NET 11 SDK** the repository pins in `global.json` (`11.0.100`). +- GitHub Actions runner **2.327.1 or later**: the workflows use `actions/checkout@v7` and + `actions/setup-dotnet@v6`, which run on Node.js 24. The job's first step prints `wsl --version` and `wslc version`, so a mis-provisioned runner fails immediately instead of surfacing as container timeouts. `actionlint` is told about the custom label in