Repository navigation
[release/17.0] Add initial WSLc publish/deploy support with explicit capability limits - #21991
Conversation
…ts (#21009) ## Description WSLc can run Aspire apps on Windows, but publishing currently has no WSLc runtime implementation. This adds an initial, deliberately limited publishing implementation so supported image operations use the selected runtime and unsupported operations fail clearly instead of falling back or working around WSLc limitations. This PR targets `main` and builds on the runtime detection and doctor support from #21004, now incorporated into `main`. Supported on Windows: local Dockerfile builds without platform selection, image tagging/removal/push, registry login, native JSON image configuration inspection, and single-platform .NET SDK publishing to WSLc's local image store. Auto-discovery retains Docker → Podman → WSLc priority; explicit case-insensitive selection and custom keyed runtimes remain supported. Native SDK local publishing uses `LocalRegistry=Wslc` and requires an SDK containing the WSLc support introduced in [dotnet/sdk#55249](dotnet/sdk#55249). It was verified with the repository-pinned SDK `11.0.100-rc.1.26425.128`; older SDKs without this support report an unsupported registry rather than falling back to another runtime. Aspire does not implement an archive/load bridge. Unsupported: Compose deployment/management, platform-selected Dockerfile builds, Dockerfile archives/OCI format selection, manifest inspection, multi-platform SDK publishing to WSLc's local image store, and container-file layering (which requires a platform-selected Dockerfile build). Multi-platform image loading is tracked by [microsoft/WSL#41123](microsoft/WSL#41123). These paths reject explicitly using existing exception/inspection-result contracts. Daemon-free single- and multi-platform SDK archives remain supported without WSLc health checks or commands; archive publishing omits `LocalRegistry=Wslc`, preserving compatibility with SDKs that do not recognize it. No alternative builder or runtime fallback is introduced. Dockerfile builds in Docker, Podman, and WSLc now use `ProcessSpec.ArgumentList` instead of a manually quoted command line. Shared eager argument helpers preserve quotes, spaces, backslashes, empty values, and inherited environment values, retaining Podman's existing secret behavior. Platform-specific process argument handling remains owned by .NET, without invoking a shell. ### User-facing usage On Windows, select WSLc with `ASPIRE_CONTAINER_RUNTIME=wslc`. Single-platform .NET SDK publishing then uses WSLc's local store through the SDK's native support. Dockerfile publishing defaults to `linux/amd64`; explicitly opt into the WSLc host platform only when appropriate: ```csharp builder.AddDockerfile("program", "./program") .WithContainerBuildOptions(options => options.TargetPlatform = null); ``` For a .NET SDK archive without container-file layering: ```csharp project.WithContainerBuildOptions(options => { options.Destination = ContainerImageDestination.Archive; options.OutputPath = "./images"; }); ``` ### Validation - `.\restore.cmd /p:SkipNativeBuild=true` — passed during initial setup. - `.\.dotnet\dotnet.exe test --project tests\Aspire.Hosting.Tests\Aspire.Hosting.Tests.csproj --no-launch-profile /p:SkipNativeBuild=true -- --filter-class '*.WslcContainerRuntimeTests' --filter-class '*.ContainerRuntimeResolverTests' --filter-class '*.ContainerRuntimeDetectorTests' --filter-class '*.DockerContainerRuntimeTests' --filter-class '*.ContainerRuntimeBaseTests' --filter-class '*.DotnetProgramArchiveTests' --filter-class '*.DotnetProgramPublishingTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'` — passed, 151 tests after merging `main`, before the argument-list correction. - `.\.dotnet\dotnet.exe test --project tests\Aspire.Hosting.Tests\Aspire.Hosting.Tests.csproj --no-launch-profile /p:SkipNativeBuild=true -- --filter-class '*.ContainerRuntimeBaseTests' --filter-class '*.DockerContainerRuntimeTests' --filter-class '*.PodmanSaveArgumentsTests' --filter-class '*.WslcContainerRuntimeTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'` — passed, 95 tests after the argument-list correction and eager helper changes. The runtime-constant follow-up was rebuilt with `--filter-method '*.BuildImageAsync_PreservesArgumentBoundaries'` (same project and exclusions) — passed, 3 cases. The complete 95-test selection was rerun with `--no-build` immediately before pushing — passed. - `.\.dotnet\dotnet.exe test --project tests\Aspire.Hosting.Tests\Aspire.Hosting.Tests.csproj --no-build --no-launch-profile -- --filter-method '*.BuildSecretsFormats*' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'` — passed, 4 tests after the argument-list correction. - `.\.dotnet\dotnet.exe test --project tests\Aspire.Hosting.Tests\Aspire.Hosting.Tests.csproj --no-build --no-launch-profile -- --filter-class '*.DotnetProgramArchiveTests' --filter-class '*.DotnetProgramPublishingTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'` — passed, 48 tests after the argument-list correction. - `.\.dotnet\dotnet.exe test --project tests\Aspire.Hosting.Tests\Aspire.Hosting.Tests.csproj --no-build --no-launch-profile -- --filter-method '*.BuildImageAsync_Dotnet*' --filter-method '*.BuildImageAsync_ProjectBuildPassesResolvedContainerRuntimeAsLocalRegistry' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'` — passed, 20 tests after the SDK correction and before the `main` merge. - `.\.dotnet\dotnet.exe publish '<probe-directory>\probe.csproj' --configuration Release /t:PublishContainer --property:LocalRegistry=Wslc --property:ContainerRepository=aspire-wslc-sdk-probe-b35fa7a4 --property:ContainerImageTag=single --property:RuntimeIdentifier=linux-x64 --property:ContainerRuntimeIdentifier=linux-x64 --property:ContainerBaseImage=mcr.microsoft.com/dotnet/runtime:10.0 --source https://packagefeedproxy.microsoft.io/nuget/v3/index.json` — passed using a temporary minimal net10.0 console project and SDK `11.0.100-rc.1.26425.128`. SDK reported successful publication via Wslc; `wslc image inspect aspire-wslc-sdk-probe-b35fa7a4:single --format json` confirmed linux/amd64. Probe image and project cleaned up; the path above is a placeholder for that temporary directory. - Installed WSLc 3.0.3.0: verified local Dockerfile build and native `image inspect --format json`; inspected tag/remove/push/login/build help and DCP's WSLc adapter. Direct `--output type=docker` and `--output type=oci` probes both failed with the Docker-driver exporter limitation, confirming the explicit archive boundary. Probe image/files cleaned up. - Local E2E tests were not run; no E2E tests were added. Linux/macOS execution and live registry push/login were not validated locally. - Existing NU1902/NU1903 warnings for `System.Security.Cryptography.Pkcs` 10.0.12 remain; no dependency changes are included. ### Security considerations The selected WSLc executable is trusted in the same way as Docker/Podman. Image commands use the existing process runner; registry passwords remain on stdin and environment build secrets follow the existing runtime pattern. Native image inspection uses source-generated JSON deserialization and preserves the image reference as a single process argument. Dockerfile build invocations for all three runtimes now preserve argument boundaries through `ProcessSpec.ArgumentList`. No listener, elevated execution, archive extraction, or Aspire-managed archive/load bridge is added. A separate security review has not been performed. Fixes # (issue) ## Checklist - Is this feature complete? - [x] Yes. Ready to ship. - [ ] No. Follow-up changes expected. - Are you including unit tests for the changes and scenario tests if relevant? - [x] Yes - [ ] No - Did you add public API? - [ ] Yes - If yes, did you have an API Review for it? - [ ] Yes - [ ] No - Did you add `<remarks />` and `<code />` elements on your triple slash comments? - [ ] Yes - [ ] No - [x] No - Does the change make any security assumptions or guarantees? - [ ] Yes - If yes, have you done a threat model and had a security review? - [ ] Yes - [x] No - [x] No --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f85e4b06-371e-465a-8fd8-e635d14ec41f Copilot-Session: b35fa7a4-1433-4b70-9840-5f5866230ff4 (cherry picked from commit 64ba1eb)
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21991Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21991" |
Tests selector53 / 101 PR test projects · 4 PR jobs, from 17 changed files. Selected PR test projects (53 / 101)
Selected PR jobs (4)
How these were chosen — grouped by what changed
🔧 show 46
🧪 📦 affected project 📦 affected project 🧪 🧪 🧪 🧪 🧪 🧪 🧪 Job reasons
Selection computed for commit |
There was a problem hiding this comment.
🟡 Changes recommended
The machine requirements documentation contradicts the newly added WSLc publishing support and needs to clarify supported operations, remaining limitations, and the SDK requirement for LocalRegistry=Wslc.
1 open issue
What changed in this PR
Backports initial Windows WSLc publishing support to release/17.0, integrating it with Aspire’s container runtime selection while explicitly rejecting unsupported operations.
Changes:
- Adds WSLc image operations and single-platform .NET SDK local publishing, with capability checks.
- Moves Dockerfile build commands to argument lists to preserve argument boundaries.
- Adds runtime regression tests and raises the WSLc minimum version to 3.0.4.0.
| File | Description |
|---|---|
| tests/Aspire.Hosting.Tests/Publishing/WslcContainerRuntimeTests.cs | Tests WSLc commands, inspection, cancellation, and capability limits. |
| tests/Aspire.Hosting.Tests/Publishing/ResourceContainerImageManagerTests.cs | Updates secret-format assertions for argument lists. |
| tests/Aspire.Hosting.Tests/Publishing/PodmanSaveArgumentsTests.cs | Updates build assertions while retaining save coverage. |
| tests/Aspire.Hosting.Tests/Publishing/DockerContainerRuntimeTests.cs | Updates Docker build argument assertions. |
| tests/Aspire.Hosting.Tests/Publishing/ContainerRuntimeResolverTests.cs | Tests WSLc selection and Windows-only enforcement. |
| tests/Aspire.Hosting.Tests/Publishing/ContainerRuntimeBaseTests.cs | Tests argument boundaries, root paths, and secret encoding. |
| tests/Aspire.Hosting.Dotnet.Tests/WslcDotnetPublishingTests.cs | Tests SDK publishing, archives, and unsupported scenarios. |
| tests/Aspire.Cli.Tests/Utils/ContainerRuntimeCheckTests.cs | Updates minimum-version cases and removes obsolete filtering coverage. |
| src/Shared/ContainerRuntimeDetector.cs | Removes the runtime discovery filter. |
| src/Aspire.Hosting/Publishing/WslcContainerRuntime.cs | Implements WSLc publishing operations and explicit limits. |
| src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs | Routes SDK publishing to WSLc and enforces capability limits. |
| src/Aspire.Hosting/Publishing/PodmanContainerRuntime.cs | Uses argument lists for Dockerfile builds. |
| src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs | Uses argument lists and preserves root context paths. |
| src/Aspire.Hosting/Publishing/ContainerRuntimeResolver.cs | Includes WSLc in publishing discovery and diagnostics. |
| src/Aspire.Hosting/Publishing/ContainerRuntimeBase.cs | Adds shared argument-list and secret-encoding helpers. |
| src/Aspire.Hosting/DistributedApplicationBuilder.cs | Registers the WSLc runtime. |
| src/Aspire.Cli/Utils/EnvironmentChecker/ContainerRuntimeCheck.cs | Raises the WSLc minimum version to 3.0.4.0. |
| docs/machine-requirements.md | Updates the documented WSLc minimum version. |
Review effort: Balanced
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
113fa13
into
release/17.0
|
✅ No documentation update needed. excluded → backport (exclusion_reasons: base_branch_is_release, title_release_prefix, body_backport_marker). The PR is a backport of #21009 to |

Backport of #21009 to release/17.0.
Customer Impact
Users running containers through WSLc on Windows can't use Aspire 17.0 to build, publish, or deploy container images. WSLc is not recognized as a container runtime for publish and deploy, so these operations fail or select the wrong runtime. This change adds a WSLc container runtime, and
aspire doctorreports explicit capability limits for features that WSLc doesn't support.Testing
dotnet test --project tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj --no-launch-profile -- --filter-class "*.ContainerRuntimeBaseTests" --filter-class "*.ContainerRuntimeResolverTests" --filter-class "*.DockerContainerRuntimeTests" --filter-class "*.PodmanSaveArgumentsTests" --filter-class "*.ResourceContainerImageManagerTests" --filter-class "*.WslcContainerRuntimeTests" --filter-class "*.ContainerRuntimeDetectorTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true": passed (84/84)dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ContainerRuntimeCheckTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true": passed (78/78)WslcDotnetPublishingTestsis Windows-only and was skipped locally. Windows CI on this PR covers it.Risk
Low to medium. The new behavior applies only when WSLc is the selected container runtime. However, the change also touches shared container runtime code (
ContainerRuntimeBase,ContainerRuntimeResolver, the Docker and Podman runtimes,ResourceContainerImageManager, andContainerRuntimeDetector), which affects all runtimes. The existing Docker and Podman unit tests pass. Publishing withLocalRegistry=Wslcalso requires an SDK that includes dotnet/sdk#55249.Regression?
No. This is new functionality for WSLc users.