Skip to content

[release/17.0] Add initial WSLc publish/deploy support with explicit capability limits - #21991

Merged
Jose Perez Rodriguez (joperezr) merged 1 commit into
release/17.0from
danegsta-backport-21009-release-17-0
Nov 11, 2026
Merged

Jose Perez Rodriguez (joperezr) merged 1 commit into
release/17.0from
danegsta-backport-21009-release-17-0

Conversation

@danegsta

@danegsta David Negstad (danegsta) commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

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 doctor reports explicit capability limits for features that WSLc doesn't support.

Testing

  • The original PR passed CI on main.
  • Ran locally on macOS against this branch:
    • 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)
    • WslcDotnetPublishingTests is 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, and ContainerRuntimeDetector), which affects all runtimes. The existing Docker and Podman unit tests pass. Publishing with LocalRegistry=Wslc also requires an SDK that includes dotnet/sdk#55249.

Regression?

No. This is new functionality for WSLc users.

…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)
@github-actions github-actions Bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Nov 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21991

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21991"

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Tests selector

53 / 101 PR test projects · 4 PR jobs, from 17 changed files.

Selected PR test projects (53 / 101)

Aspire.Cli.EndToEnd.Tests, Aspire.Cli.Tests, Aspire.Hosting.Analyzers.Tests, Aspire.Hosting.Azure.EntraId.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Kusto.Tests, Aspire.Hosting.Azure.Provisioning.Tests, Aspire.Hosting.Azure.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Browsers.Tests, Aspire.Hosting.CodeGeneration.Go.Tests, Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Containers.Tests, Aspire.Hosting.DevTunnels.Tests, Aspire.Hosting.Docker.Tests, Aspire.Hosting.Dotnet.Tests, Aspire.Hosting.DotnetTool.Tests, Aspire.Hosting.EntityFrameworkCore.Tests, Aspire.Hosting.Foundry.Tests, Aspire.Hosting.Garnet.Tests, Aspire.Hosting.Go.Tests, Aspire.Hosting.Java.Tests, Aspire.Hosting.JavaScript.Tests, Aspire.Hosting.Kafka.Tests, Aspire.Hosting.Keycloak.Tests, Aspire.Hosting.Kubernetes.Tests, Aspire.Hosting.Maui.Tests, Aspire.Hosting.Milvus.Tests, Aspire.Hosting.MongoDB.Tests, Aspire.Hosting.MySql.Tests, Aspire.Hosting.Nats.Tests, Aspire.Hosting.OpenAI.Tests, Aspire.Hosting.Oracle.Tests, Aspire.Hosting.Orleans.Tests, Aspire.Hosting.PostgreSQL.Tests, Aspire.Hosting.Python.Tests, Aspire.Hosting.Qdrant.Tests, Aspire.Hosting.RabbitMQ.Tests, Aspire.Hosting.Radius.Tests, Aspire.Hosting.Redis.Tests, Aspire.Hosting.RemoteHost.Tests, Aspire.Hosting.Rust.Tests, Aspire.Hosting.Seq.Tests, Aspire.Hosting.SqlServer.Tests, Aspire.Hosting.Testing.Tests, Aspire.Hosting.Tests, Aspire.Hosting.Valkey.Tests, Aspire.Hosting.Yarp.Tests, Aspire.Playground.Tests, Aspire.Templates.Tests

Selected PR jobs (4)

cli-starter-validation, extension-e2e, polyglot, typescript-api-compat


How these were chosen — grouped by what changed

⚠️ 46 of the 53 selected test projects come from a single change — src/Aspire.Hosting/DistributedApplicationBuilder.cs.

🔧 src/Aspire.Hosting/DistributedApplicationBuilder.cs (changed source)
→ 46 via the project graph

show 46

Aspire.Hosting.Analyzers.Tests (2 hops), Aspire.Hosting.Azure.EntraId.Tests (2 hops), Aspire.Hosting.Azure.Kubernetes.Tests (2 hops), Aspire.Hosting.Azure.Kusto.Tests (2 hops), Aspire.Hosting.Azure.Provisioning.Tests (3 hops), Aspire.Hosting.Azure.Tests, Aspire.Hosting.Browsers.Tests (2 hops), Aspire.Hosting.CodeGeneration.Go.Tests, Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Containers.Tests (2 hops), Aspire.Hosting.DevTunnels.Tests (2 hops), Aspire.Hosting.Docker.Tests (2 hops), Aspire.Hosting.DotnetTool.Tests (2 hops), Aspire.Hosting.EntityFrameworkCore.Tests (2 hops), Aspire.Hosting.Foundry.Tests (2 hops), Aspire.Hosting.Garnet.Tests (2 hops), Aspire.Hosting.Go.Tests (2 hops), Aspire.Hosting.Java.Tests (2 hops), Aspire.Hosting.JavaScript.Tests (2 hops), Aspire.Hosting.Kafka.Tests (2 hops), Aspire.Hosting.Keycloak.Tests (2 hops), Aspire.Hosting.Kubernetes.Tests (2 hops), Aspire.Hosting.Maui.Tests, Aspire.Hosting.Milvus.Tests (2 hops), Aspire.Hosting.MongoDB.Tests (2 hops), Aspire.Hosting.MySql.Tests (2 hops), Aspire.Hosting.Nats.Tests (2 hops), Aspire.Hosting.OpenAI.Tests (2 hops), Aspire.Hosting.Oracle.Tests (2 hops), Aspire.Hosting.Orleans.Tests (2 hops), Aspire.Hosting.PostgreSQL.Tests (2 hops), Aspire.Hosting.Python.Tests (2 hops), Aspire.Hosting.Qdrant.Tests (2 hops), Aspire.Hosting.RabbitMQ.Tests (2 hops), Aspire.Hosting.Redis.Tests (2 hops), Aspire.Hosting.RemoteHost.Tests, Aspire.Hosting.Rust.Tests (2 hops), Aspire.Hosting.Seq.Tests (2 hops), Aspire.Hosting.SqlServer.Tests (2 hops), Aspire.Hosting.Testing.Tests (2 hops), Aspire.Hosting.Valkey.Tests (2 hops), Aspire.Hosting.Yarp.Tests (2 hops), Aspire.Playground.Tests

🧪 tests/Aspire.Hosting.Tests/Publishing/ContainerRuntimeBaseTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests
→ 2 via the project graph: Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Radius.Tests

📦 affected project Aspire.Hosting.Dotnet
→ 2 tests: Aspire.Cli.EndToEnd.Tests, Aspire.Templates.Tests

📦 affected project Aspire.Cli
→ 1 test: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.Tests/Utils/ContainerRuntimeCheckTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Hosting.Dotnet.Tests/WslcDotnetPublishingTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Dotnet.Tests

🧪 tests/Aspire.Hosting.Tests/Publishing/ContainerRuntimeResolverTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests

🧪 tests/Aspire.Hosting.Tests/Publishing/DockerContainerRuntimeTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests

🧪 tests/Aspire.Hosting.Tests/Publishing/PodmanSaveArgumentsTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests

🧪 tests/Aspire.Hosting.Tests/Publishing/ResourceContainerImageManagerTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests

🧪 tests/Aspire.Hosting.Tests/Publishing/WslcContainerRuntimeTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Cli
extension-e2e • src/Aspire.Cli/Utils/EnvironmentChecker/ContainerRuntimeCheck.cs, src/Aspire.Hosting/DistributedApplicationBuilder.cs, src/Aspire.Hosting/Publishing/ContainerRuntimeBase.cs, src/Aspire.Hosting/Publishing/ContainerRuntimeResolver.cs, src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs, src/Aspire.Hosting/Publishing/PodmanContainerRuntime.cs, src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs, src/Aspire.Hosting/Publishing/WslcContainerRuntime.cs
• affected project Aspire.Cli
polyglot • affected project Aspire.Cli
• affected project Aspire.Hosting.Azure.Provisioning.KeyVault
typescript-api-compat affected project Aspire.Cli

Selection computed for commit 8d8b473.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread docs/machine-requirements.md Resolved
@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@joperezr
Jose Perez Rodriguez (joperezr) merged commit 113fa13 into release/17.0 Nov 11, 2026
1080 of 1083 checks passed
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

✅ 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 release/17.0 (title prefixed [release/17.0], body says "Backport of #21009"). Docs belong with the original forward PR. Triggered signals: pr_body_has_cli_flag_mention (only a dotnet test command in the testing section).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants