From 7d451ee7ea246602874f3cb45d7887e1cdc6d9fb Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Fri, 2 Oct 2026 08:34:18 +0100 Subject: [PATCH] docs: updated docs --- README.md | 5 ++- docs/wiki/Backends.md | 67 ++++++++++++++++++++---------- docs/wiki/Consumer-Requirements.md | 7 ++-- docs/wiki/Getting-Started.md | 28 +++++++++---- docs/wiki/Home.md | 6 ++- package.json | 4 +- samples/getting-started/README.md | 4 +- src/src/Core/Sdk/README.md | 5 ++- src/src/Wsl/Sdk/README.md | 14 ++++--- 9 files changed, 93 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 6645adb..0492073 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,10 @@ The WSLC backend is built directly against the `Microsoft.WSL.Containers` NuGet ## Prerequisites -Pick a backend — see [Backends: WSLC or Docker](docs/wiki/Backends.md) for the comparison. +Pick a backend — see [Backends: WSLC or Docker](docs/wiki/Backends.md) for the comparison — or skip the +choice: reference the umbrella `Purview.Containers` and it brings the abstractions plus both backends, +selecting WSLC on Windows and Docker elsewhere automatically. Pick a single backend below only when you +want to fix the runtime. **WSL Containers backend** diff --git a/docs/wiki/Backends.md b/docs/wiki/Backends.md index 137e930..328029b 100644 --- a/docs/wiki/Backends.md +++ b/docs/wiki/Backends.md @@ -2,14 +2,30 @@ `Purview.Containers` has **one API and two interchangeable backends**. The same test code, the same service modules (`Purview.Containers.PostgreSql`, `Redis`, `MsSql`, `RabbitMq`, `Azurite`, `Nats`, `MySql`), and -the same connection-string accessors run on either runtime — you choose which one, in code or from the -environment. +the same connection-string accessors run on either runtime — you choose which one by the package you +reference, and can override it in code or from the environment. +- `**Purview.Containers**` — the umbrella: `Core` plus both backends, for one reference with automatic + selection. +- `**Purview.Containers.Core**` — the backend-neutral abstractions (the API you code against); usually + arrives transitively. - `**Purview.Containers.Wsl**` — throwaway containers on **Microsoft WSL Containers (WSLC)**, the Windows runtime with no Docker installation. - `**Purview.Containers.Docker**` — throwaway containers on **any reachable Docker daemon**, driven by Testcontainers. +## Which package do I reference? + +| Package | Use it when | +| --- | --- | +| `Purview.Containers` | The umbrella: `Core` + both backends. One reference, zero config — WSLC on Windows, Docker elsewhere (auto). **Recommended default.** | +| `Purview.Containers.Core` | The backend-neutral abstractions (the API). Reference it explicitly with one or both backends when you want a minimal dependency surface; otherwise it arrives transitively. | +| `Purview.Containers.Wsl` | WSL Containers only — a Windows dev machine with no Docker. | +| `Purview.Containers.Docker` | Docker only — any platform, CI, Linux/macOS. | + +Service modules (`Purview.Containers.PostgreSql`, `Redis`, …) are backend-neutral: add any backend package +(or the umbrella) alongside one to run it. + ## At a glance | | WSL Containers | Docker | @@ -117,7 +133,7 @@ public class CacheTests The **package reference** decides which runtime executes it. Three project shapes cover every case. -### Option 1 — WSLC on a Windows machine, Docker elsewhere (one project) +### Option 1 — WSLC only (Windows) ```bash dotnet add package Purview.Containers.Wsl @@ -126,7 +142,7 @@ dotnet add package Purview.Containers.Wsl ```xml - net10.0 + net10.0 enable enable @@ -136,13 +152,16 @@ dotnet add package Purview.Containers.Wsl ``` -A platform-neutral `net10.0` project binds the portable facade, so it selects WSLC on a Windows host -and Docker everywhere else. A Windows target framework (`net10.0-windows10.0.19041.0`, x64 or arm64) -binds the implementation directly. `WindowsSdkPackageVersion` is supplied by the package. A project -older than .NET 10 fails the build with `PCC0001`, and a 32-bit Windows consumer with `PCC0002`; see +This project runs WSLC on a Windows host. A platform-neutral `net10.0` project binds the portable +facade; a Windows target framework (`net10.0-windows10.0.19041.0`, x64 or arm64) binds the +implementation directly. `WindowsSdkPackageVersion` is supplied by the package. A project older than +.NET 10 fails the build with `PCC0001`, and a 32-bit Windows consumer with `PCC0002`; see [Consumer Requirements](Consumer-Requirements.md). -### Option 2 — Docker anywhere +> On a non-Windows host this project has **no usable backend** (the facade reports `wsl` unavailable). +> To also run on Docker there, add `Purview.Containers.Docker` or use the umbrella — see Option 3. + +### Option 2 — Docker only (any platform) ```bash dotnet add package Purview.Containers.Docker @@ -164,14 +183,13 @@ dotnet add package Purview.Containers.Docker That project restores and builds on Linux, macOS and Windows — no Windows target framework, no `WindowsSdkPackageVersion`, no Docker Desktop licence requirement beyond the daemon you already run. -### Option 3 — one project, both backends (auto) +### Option 3 — both backends, automatic selection (recommended) -Reference both backends from a single **platform-neutral** project. `auto` selects WSLC on a machine that -can run it and Docker otherwise — no multi-targeting and no conditional references: +Add the umbrella `Purview.Containers`: it brings `Core` plus both backends, so `auto` selects WSLC on a +machine that can run it and Docker otherwise — no multi-targeting and no conditional references: ```bash -dotnet add package Purview.Containers.Wsl -dotnet add package Purview.Containers.Docker +dotnet add package Purview.Containers ``` ```xml @@ -182,16 +200,23 @@ dotnet add package Purview.Containers.Docker enable - - + ``` -`auto` probes both in priority order (`wsl` before `docker`) and uses the first that is usable, so this -one project runs on WSLC on a developer's Windows machine and on Docker in a Linux CI job. A Windows -target framework is still supported when you want the implementation bound at compile time, but it is not -required. +`auto` probes the registered backends in priority order (`wsl` before `docker`) and uses the first that is +usable, so this one project runs on WSLC on a developer's Windows machine and on Docker in a Linux CI job. +A Windows target framework is still supported when you want the implementation bound at compile time, but +it is not required. + +Prefer the explicit form? Reference `Purview.Containers.Core` plus both backends instead of the umbrella: + +```bash +dotnet add package Purview.Containers.Core +dotnet add package Purview.Containers.Wsl +dotnet add package Purview.Containers.Docker +``` If your code needs a Windows-only API the portable facade does not expose (for example `WslContainer`, or `WslContainerBackend(runtime)` to pin a specific WSLC session), guard it with `#if WINDOWS` — defined by @@ -216,7 +241,7 @@ A module is backend-neutral, so only the backend package line changes: ```bash dotnet add package Purview.Containers.PostgreSql # the module -dotnet add package Purview.Containers.Wsl # ...or Purview.Containers.Docker +dotnet add package Purview.Containers # ...or Purview.Containers.Wsl / Purview.Containers.Docker ``` ```csharp diff --git a/docs/wiki/Consumer-Requirements.md b/docs/wiki/Consumer-Requirements.md index f6010eb..cf1bb1f 100644 --- a/docs/wiki/Consumer-Requirements.md +++ b/docs/wiki/Consumer-Requirements.md @@ -9,9 +9,10 @@ The WSL Containers backend package is **multi-target**. It ships a Windows build (`net10.0-windows10.0.19041.0`, the implementation, built on the `Microsoft.WSL.Containers` projection) and a platform-neutral build (`net10.0`, a facade). A Windows-targeting project binds the implementation directly; any other project binds the facade, which builds on **every** platform and, on -a Windows host, loads the implementation at run time. That is what lets the *same* `net10.0` test -project run on WSLC on a developer's Windows machine and on Docker in a Linux CI job with no -configuration change. This page is the authoritative statement of that contract, of the workarounds +a Windows host, loads the implementation at run time. That is what lets a `net10.0` test project that +references the WSL backend (or the umbrella `Purview.Containers`, which also brings Docker) run on WSLC on +a developer's Windows machine and on Docker in a Linux CI job with no configuration change. This page is +the authoritative statement of that contract, of the workarounds that exist for it, and of how each of them is verified. ## Which package requires what diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md index 658c8d0..7073c35 100644 --- a/docs/wiki/Getting-Started.md +++ b/docs/wiki/Getting-Started.md @@ -28,24 +28,34 @@ Everything runs on one of two backends; pick the one that matches your machine ## 1. Reference a package -Reference a backend package for generic containers: +| Package | Use it when | +| --- | --- | +| `Purview.Containers` | The umbrella: `Core` + both backends. One reference, zero config — WSLC on Windows, Docker elsewhere (auto). **Recommended default.** | +| `Purview.Containers.Wsl` | WSL Containers only — a Windows dev machine with no Docker. | +| `Purview.Containers.Docker` | Docker only — any platform, CI, Linux/macOS. | + +Start with the umbrella: + +```bash +dotnet add package Purview.Containers +``` + +or pick a single backend: ```bash -dotnet add package Purview.Containers.Wsl # WSL Containers (WSLC on Windows, Docker elsewhere) -dotnet add package Purview.Containers.Docker # Docker / Testcontainers (any platform) +dotnet add package Purview.Containers.Wsl # WSLC only (Windows) +dotnet add package Purview.Containers.Docker # Docker only (any platform) ``` -or a service module, which is backend-neutral and needs a backend package alongside it: +A service module is backend-neutral, so it needs any backend (or the umbrella) alongside it: ```bash dotnet add package Purview.Containers.PostgreSql -dotnet add package Purview.Containers.Wsl # ...or Purview.Containers.Docker +dotnet add package Purview.Containers # ...or Purview.Containers.Wsl / Purview.Containers.Docker ``` -> **Want it to just work without choosing a backend?** Add `Purview.Containers` (the umbrella — it brings -> the abstractions and both backends) to a platform-neutral `net10.0` project and let automatic selection -> decide — WSLC on a Windows machine, Docker everywhere else, with no code or configuration change. See -> [Using it in your tests](Using-in-Your-Tests.md). +The umbrella is the zero-config shape — see [Using it in your tests](Using-in-Your-Tests.md) for the full +story. ## 2. Run a generic container diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index b9c1cb5..fe18f62 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -84,8 +84,10 @@ updates WSL on its own. ## Choosing a backend -Two backends implement the same API. Automatic detection is the default; pin one in code or from the -environment: +Two backends implement the same API. The zero-choice default is the umbrella `Purview.Containers` (see the +Packages table above): one reference brings both backends and automatic selection — WSLC on Windows, +Docker elsewhere. Reference a single backend only when you want to fix the runtime. Automatic detection is +the default; pin one in code or from the environment: ```powershell # auto (the default) | wsl | docker | diff --git a/package.json b/package.json index 603cc1c..aef2255 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "purview-containers", - "version": "1.0.0-prerelease.2", + "version": "1.0.0-prerelease.3", "license": "MIT", "author": { "name": "Kieron Lanning", @@ -14,4 +14,4 @@ "type": "git", "url": "git+https://github.com/purview-dev/containers.git" } -} +} \ No newline at end of file diff --git a/samples/getting-started/README.md b/samples/getting-started/README.md index 2290964..8617cbb 100644 --- a/samples/getting-started/README.md +++ b/samples/getting-started/README.md @@ -30,7 +30,9 @@ They reference the backends as **projects** so they build from a clone with no p consumer uses packages instead: ```bash -dotnet add package Purview.Containers.Docker # or Purview.Containers.Wsl +dotnet add package Purview.Containers # umbrella: both backends, auto (recommended) +dotnet add package Purview.Containers.Wsl # or WSLC only +dotnet add package Purview.Containers.Docker # or Docker only ``` Because they are project references, no `buildTransitive` assets apply, so each sample registers its diff --git a/src/src/Core/Sdk/README.md b/src/src/Core/Sdk/README.md index 8540ea7..883dcc5 100644 --- a/src/src/Core/Sdk/README.md +++ b/src/src/Core/Sdk/README.md @@ -59,8 +59,9 @@ callers that want to apply their own policy. ## Requirements - **.NET 10 or later**, any platform (this package is portable). -- A **backend package**: `Purview.Containers.Wsl` (WSLC on a Windows host, Docker elsewhere) or - `Purview.Containers.Docker` (Docker Engine reachable from the test host). +- A **backend package**: `Purview.Containers.Wsl` (WSLC on a Windows host), + `Purview.Containers.Docker` (Docker Engine reachable from the test host), or both — or the umbrella + `Purview.Containers`, which brings this package plus both backends for automatic selection. ## Related diff --git a/src/src/Wsl/Sdk/README.md b/src/src/Wsl/Sdk/README.md index e250015..4685b2e 100644 --- a/src/src/Wsl/Sdk/README.md +++ b/src/src/Wsl/Sdk/README.md @@ -13,12 +13,14 @@ Reference this package (or a service module) and containers run on WSLC. The pac **multi-target**: a `net10.0` build (a portable facade) and a `net10.0-windows10.0.19041.0` build (the implementation). A Windows-targeting project binds the implementation; a `net10.0` project binds the facade, which loads the implementation at run time on a Windows host and reports `wsl` as unavailable -elsewhere — so the **same** test project runs on WSLC on your Windows machine and on -[`Purview.Containers.Docker`](https://www.nuget.org/packages/Purview.Containers.Docker) in Linux CI -with no configuration change. It registers itself as the `wsl` backend in the consuming assembly. - -> **Running in CI, or on a machine without WSL Containers?** With `auto` (the default) the backend is -> reported unavailable and selection falls through to Docker. Pin instead with +elsewhere. It registers itself as the `wsl` backend in the consuming assembly. To also run the same test +code on Docker in Linux CI, reference +[`Purview.Containers.Docker`](https://www.nuget.org/packages/Purview.Containers.Docker) (or the umbrella +[`Purview.Containers`](https://www.nuget.org/packages/Purview.Containers), which brings both backends). + +> **Running in CI, or on a machine without WSL Containers?** With only this package referenced, `wsl` is +> reported unavailable and there is **no** backend to fall back to. Add `Purview.Containers.Docker` or use +> the umbrella `Purview.Containers`, and `auto` (the default) falls through to Docker. Pin instead with > `PURVIEW_CONTAINERS_BACKEND=wsl|docker` or `ContainerBackends.Use(...)` — see > [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md).