Skip to content

Add initial WSLc publish/deploy support with explicit capability limits - #21009

Merged
David Negstad (danegsta) merged 17 commits into
mainfrom
danegsta-wslc-publishing-support
Nov 6, 2026
Merged

David Negstad (danegsta) merged 17 commits into
mainfrom
danegsta-wslc-publishing-support

Conversation

@danegsta

@danegsta David Negstad (danegsta) commented Oct 14, 2026 •

Copy link
Copy Markdown
Member

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. 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. 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:

builder.AddDockerfile("program", "./program")
    .WithContainerBuildOptions(options => options.TargetPlatform = null);

For a .NET SDK archive without container-file layering:

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?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • 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
    • 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
        • No
    • No

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f85e4b06-371e-465a-8fd8-e635d14ec41f
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f85e4b06-371e-465a-8fd8-e635d14ec41f
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f85e4b06-371e-465a-8fd8-e635d14ec41f
Stream runtime metadata and drain process output concurrently while retaining failure diagnostics.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f85e4b06-371e-465a-8fd8-e635d14ec41f
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f85e4b06-371e-465a-8fd8-e635d14ec41f
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f85e4b06-371e-465a-8fd8-e635d14ec41f
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b35fa7a4-1433-4b70-9840-5f5866230ff4
@danegsta
David Negstad (danegsta) changed the base branch from danegsta-wslc-runtime-support to main October 15, 2026 19:30
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b35fa7a4-1433-4b70-9840-5f5866230ff4
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b35fa7a4-1433-4b70-9840-5f5866230ff4
@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 -- 21009

Or

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

@github-actions

This comment has been minimized.

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

Build-argument quoting can corrupt inputs, and the declared SDK publishing scope contradicts the implementation.

2 open findings
What changed in this PR

Extends Aspire’s WSLc runtime detection with limited Windows publishing support and explicit capability limits.

Changes:

  • Adds WSLc image operations, inspection, and unsupported-operation checks.
  • Integrates runtime selection and SDK publishing behavior.
  • Adds focused tests and documents supported scenarios.
File Description
tests/​Aspire.Hosting.Tests/​Publishing/​WslcContainerRuntimeTests.cs Tests image operations and capability limits.
tests/​Aspire.Hosting.Tests/​Publishing/​ContainerRuntimeResolverTests.cs Tests WSLc selection and Windows restriction.
src/​Aspire.Hosting/​Publishing/​WslcContainerRuntime.cs Implements limited WSLc publishing operations.
src/​Aspire.Hosting/​Publishing/​ResourceContainerImageManager.cs Integrates WSLc SDK publishing and capability checks.
src/​Aspire.Hosting/​Publishing/​ContainerRuntimeResolver.cs Includes WSLc in publishing auto-detection.
src/​Aspire.Hosting/​DistributedApplicationBuilder.cs Registers the WSLc runtime.
docs/​machine-requirements.md Documents WSLc publishing capabilities and restrictions.

🧠 Review effort: Balanced

@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.

@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.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b35fa7a4-1433-4b70-9840-5f5866230ff4
@github-actions

This comment has been minimized.

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.

🔵 Needs a closer look

Unresolved publishing defects and shared cross-platform process changes require fixes and final human validation.

0 open findings

2 resolved since last review
Previously missed (2)

In code that hasn't changed since last review

Medium severity Avoid WSLc runtime probes for SDK archive builds

src/​Aspire.Hosting/​Publishing/​ContainerRuntimeResolver.cs:84

On Windows with no runtime configured, SDK archive publishing still runs WSLc probes. BuildImagesAsync resolves the runtime before checking whether it is needed, and both BuildDotnetProgramImageAsync and ExecuteDotnetPublishAsync resolve it unconditionally. Removing this filter adds wslc container ls -n 1 and potentially wslc info to those archive builds, contrary to the promised no-WSLc-command behavior, and makes them wait for probe completion or timeouts. Skip runtime resolution for SDK archives without container-file layering. Add coverage with automatic selection; the new archive tests explicitly configure WSLc and bypass discovery.

Medium severity Preserve drive-root separators during context normalization

src/​Aspire.Hosting/​Publishing/​WslcContainerRuntime.cs:78

The copied normalization strips the separator from a drive-root context such as C:\, producing the drive-relative path C:. WSLc can then build from that drive's current directory instead of the requested root. Preserve the full path; ArgumentList already handles trailing backslashes safely. Please also cover a drive-root context in the argument tests.

🧠 Review effort: Balanced

@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.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b35fa7a4-1433-4b70-9840-5f5866230ff4
@github-actions

This comment has been minimized.

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.

🔵 Needs a closer look

An argument-formatting issue remains unresolved, and registry operations and cross-platform execution require further human validation.

0 open findings

Previously missed (1)

In code that hasn't changed since last review

Medium severity Encode commas in WSLc secret paths as CSV fields

src/​Aspire.Hosting/​Publishing/​WslcContainerRuntime.cs:81

ArgumentList preserves process argument boundaries, but WSLc parses each --secret value as a CSV record. The shared helper formats C:\work\team,a\.npmrc as id=npmrc,type=file,src=C:\work\team,a\.npmrc; WSLc then rejects a\.npmrc because it is not a key=value field. Encode the individual CSV fields for WSLc, independently of process argument quoting, and add a regression test with a comma in the parent directory. Preserve Podman's existing secret syntax if changing the shared helper.

🧠 Review effort: Balanced

@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.

@github-actions

This comment has been minimized.

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.

🟢 Approval recommended

No active review issues are reported for the limited Windows-only WSLc publishing changes.

No open issues 🎉

Review effort: Balanced

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b35fa7a4-1433-4b70-9840-5f5866230ff4
@github-actions

github-actions Bot commented Nov 6, 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 739b13e.

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.

🔵 Needs a closer look

Human assessment is needed to weigh an unpublished documentation mismatch that misstates WSLc publishing support and omits required setup details.

No open issues 🎉

Review effort: Balanced

@github-actions

github-actions Bot commented Nov 6, 2026

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.

@danegsta
David Negstad (danegsta) merged commit 64ba1eb into main Nov 6, 2026
710 of 713 checks passed
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 17.1 milestone Nov 6, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Pull request created: #2081

Generated by PR Documentation Check · copilot · auto · 26.1 AIC · ⌖ 1.18 AIC · ⊞ 7.4K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

📝 Documentation has been drafted in microsoft/aspire.dev#2081 targeting release/17.0.

Updated WSLc docs from "no publish/deploy" to initial limited publish support. Signals: pr_body_has_user_facing_section (PR body "User-facing usage" on ASPIRE_CONTAINER_RUNTIME=wslc), pr_body_has_cli_flag_mention. Files: app-host/configuration.mdx, get-started/prerequisites.mdx.

Note

This draft PR needs human review before merging.

@danegsta

Copy link
Copy Markdown
Member Author

/backport to release/17.0

@github-actions

Copy link
Copy Markdown
Contributor

Started backporting to release/17.0 (link to workflow run)

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

David Negstad (@danegsta) backporting to release/17.0 failed, the patch most likely resulted in conflicts. Please backport manually!

git am output
$ git am --3way --empty=keep --ignore-whitespace --keep-non-patch changes.patch

Applying: Support WSLc in Aspire doctor runtime checks
Using index info to reconstruct a base tree...
M	docs/machine-requirements.md
M	src/Aspire.Cli/Aspire.Cli.csproj
M	src/Aspire.Cli/Utils/EnvironmentChecker/ContainerRuntimeCheck.cs
M	src/Aspire.Hosting/Aspire.Hosting.csproj
M	src/Aspire.Hosting/Publishing/ContainerRuntimeResolver.cs
M	src/Shared/ContainerRuntimeDetector.cs
M	src/Shared/KnownContainerRuntimes.cs
M	tests/Aspire.Cli.Tests/Utils/ContainerRuntimeCheckTests.cs
M	tests/Aspire.Hosting.TestUtilities/Utils/DockerUtils.cs
M	tests/Aspire.Hosting.Tests/Publishing/ContainerRuntimeDetectorTests.cs
Falling back to patching base and 3-way merge...
Auto-merging docs/machine-requirements.md
CONFLICT (content): Merge conflict in docs/machine-requirements.md
Auto-merging src/Aspire.Cli/Aspire.Cli.csproj
Auto-merging src/Aspire.Cli/Utils/EnvironmentChecker/ContainerRuntimeCheck.cs
CONFLICT (content): Merge conflict in src/Aspire.Cli/Utils/EnvironmentChecker/ContainerRuntimeCheck.cs
Auto-merging src/Aspire.Hosting/Aspire.Hosting.csproj
Auto-merging src/Aspire.Hosting/Publishing/ContainerRuntimeResolver.cs
CONFLICT (content): Merge conflict in src/Aspire.Hosting/Publishing/ContainerRuntimeResolver.cs
Auto-merging src/Shared/ContainerRuntimeDetector.cs
CONFLICT (content): Merge conflict in src/Shared/ContainerRuntimeDetector.cs
Auto-merging src/Shared/ContainerRuntimeProbe.cs
CONFLICT (add/add): Merge conflict in src/Shared/ContainerRuntimeProbe.cs
Auto-merging src/Shared/WslcContainerRuntimeProbe.cs
CONFLICT (add/add): Merge conflict in src/Shared/WslcContainerRuntimeProbe.cs
Auto-merging tests/Aspire.Cli.Tests/Utils/ContainerRuntimeCheckTests.cs
Auto-merging tests/Aspire.Hosting.Tests/Publishing/ContainerRuntimeDetectorTests.cs
CONFLICT (content): Merge conflict in tests/Aspire.Hosting.Tests/Publishing/ContainerRuntimeDetectorTests.cs
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Patch failed at 0001 Support WSLc in Aspire doctor runtime checks
Error: The process '/usr/bin/git' failed with exit code 128

Link to workflow output

Mitch Denny (mitchdenny) pushed a commit that referenced this pull request Nov 10, 2026
…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)
Mitch Denny (mitchdenny) pushed a commit that referenced this pull request Nov 10, 2026
…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)
Jose Perez Rodriguez (joperezr) pushed a commit that referenced this pull request Nov 11, 2026
…capability limits (#21991)

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.

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
David Fowler (davidfowl) added a commit that referenced this pull request Nov 11, 2026
#21009 added an expectation for the percent-escaped
RuntimeIdentifiers list; project builds now pass the quoted list.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
David Fowler (davidfowl) added a commit that referenced this pull request Nov 11, 2026
…d as one RID) (#21514)

## Description

### What failed

Multi-platform container builds of .NET programs fail in 13.6. With
`WithContainerBuildOptions(ctx => ctx.TargetPlatform =
ContainerTargetPlatform.AllLinux)`, project builds fail like this
([report on
#9281](#9281 (comment))):

```
error NETSDK1083: The specified RuntimeIdentifier 'linux-x64;linux-arm64' is not recognized.
```

File-based apps (`dotnet publish app.cs`) fail the same way, and quoting
the list alone makes them fail differently:

```
error NETSDK1083: The specified RuntimeIdentifier '"linux-x64' is not recognized.
error NETSDK1083: The specified RuntimeIdentifier 'linux-arm64"' is not recognized.
```

Two related multi-platform problems surfaced in review:
- A file-based app with a build environment
(`WithDotnetProgramBuildEnvironment`) fails with `MSBUILD : error
MSB1006: Property is not valid. Switch: linux-arm64`.
- An app or project that defines or inherits `RuntimeIdentifier` /
`ContainerRuntimeIdentifier` publishes successfully but produces a
single-platform image.

### Why

#19997 moved `AddTargetPlatformArguments` to
`MsBuildResponseFileFactory.CreatePropertyArgument`, which
percent-escapes `;` as `%3B`. That stops MSBuild's command-line parser
from splitting the switch. But an escaped `;` also stays literal when
MSBuild expands the property into items, so the SDK sees one RID,
`linux-x64;linux-arm64`. Before #19997 the list was passed quoted, which
is why 13.5.x worked.

Project files and file-based apps parse the switch differently:
- **Project files** (`dotnet msbuild` / `dotnet publish app.csproj`):
MSBuild's switch parser splits an unquoted value on `;`, so the list has
to be quoted.
- **File-based apps** (`dotnet build|publish app.cs`): the .NET CLI
parses the switch itself and passes it to the virtual project as a
global property. It keeps quote characters literally, and it appends `;`
segments without `=` to the previous value. So the list has to be
unquoted.

Two further causes:
- **Response file:** the build-environment response file wrapped each
switch in quotes. The .NET CLI does not recognize a quoted switch for a
file-based app, so it treated `app.cs` as an MSBuild argument and handed
everything to MSBuild, which then split the unquoted RID list.
- **Singular RIDs:** the SDK prefers `RuntimeIdentifier` and
`ContainerRuntimeIdentifier` over the plural lists, and can derive the
container RID from `RuntimeIdentifier`. Any inherited or project-defined
singular value therefore wins over the lists.

### Fix

- `MsBuildResponseFileFactory.CreateListPropertyArgument`
percent-escapes each entry and joins them with real `;` inside quotes
(`--property:RuntimeIdentifiers="linux-x64;linux-arm64"`). This is used
for project files.
- `MsBuildResponseFileFactory.CreateFileBasedAppListPropertyArgument`
emits the same list without quotes
(`--property:RuntimeIdentifiers=linux-x64;linux-arm64`). This is used
for file-based apps.
- `AddTargetPlatformArguments` chooses between them using
`IProjectMetadata.IsFileBasedApp`. It applies to `RuntimeIdentifiers`
and `ContainerRuntimeIdentifiers` for both the `publish` command and the
`ContainerWorkingDirectory` query. Single-RID and all other properties
are unchanged.
- For multi-platform targets, `AddTargetPlatformArguments` also emits
`--property:RuntimeIdentifier=` and
`--property:ContainerRuntimeIdentifier=` before the lists, so singular
defaults cannot collapse the build into one image.
- `MsBuildResponseFileFactory.CreateAsync` takes `isFileBasedApp`.
File-based apps get one unquoted `--property:Name=value;` per line. The
trailing `;` is consumed by the CLI parser and stops it from trimming
trailing Unicode whitespace; values are still percent-escaped. Projects
keep whole-switch quotes, and the project-only `Aspire.Hosting.Dotnet`
caller passes `false`.

### Confidence

High for both paths. Each form was checked through a real SDK container
publish for linux-x64 + linux-arm64, and each path now has a test that
runs the CLI parser actually used for it. The 14 tests that load real
images into Docker didn't run locally (see Validation); CI runs them.

### How we stop this recurring

- `BuildImageAsync_MultiPlatformArgumentsSurviveMsBuildParsing`
round-trips the emitted switches through the real parser for each path:
`dotnet msbuild properties.proj` for projects and `dotnet build app.cs`
(via `Directory.Build.props`) for file-based apps. It asserts both the
property string and the item expansion (`["linux-x64", "linux-arm64"]`).
The probe also defines both singular RIDs and asserts that they evaluate
empty. Before, the file-based variant probed a synthetic `.proj`, so it
couldn't see the file-based app behaviour.
- New `CanBuildMultiPlatformArchiveFromFileBasedCSharpApp` runs a real
`AllLinux` OCI archive publish of an `app.cs` through
`IResourceContainerImageManager`. It asserts that the archive's image
index contains `linux/amd64` and `linux/arm64`. It has three cases:
plain, with a build environment (response-file path), and with
`RuntimeIdentifier` / `ContainerRuntimeIdentifier` set in the app. The
archive reader only reads `index.json` and the index blobs, not the
layers.

### Before/after evidence

**File-based app, real SDK publish** (`dotnet publish app.cs
/t:PublishContainer`, archive output, SDK 11.0.100-rc.2):

| `RuntimeIdentifiers` switch value | Result |
|---|---|
| `"linux-x64;linux-arm64"` (previous commit) | `NETSDK1083 ...
'"linux-x64'` / `'linux-arm64"'` |
| `linux-x64%3Blinux-arm64` (main) | `NETSDK1083 ...
'linux-x64;linux-arm64'` |
| `linux-x64;linux-arm64` (this PR) | Builds both RIDs, creates the
image index and writes the archive |

**Project, real SDK publish** (`dotnet new web`, same switches): `%3B`
fails with NETSDK1083 (`'linux-x64;linux-arm64'`). The quoted list
builds `linux-x64` and `linux-arm64` images and an image index.

**Response file, real SDK publish** (`dotnet publish app.cs`, AllLinux
OCI archive, `@file.rsp`): `"--property:Foo=bar"` fails with `MSB1006
... Switch: linux-arm64`; `--property:Foo=bar;` writes the archive.

**Singular RID, real SDK publish** (`app.cs` with `#:property
RuntimeIdentifier=linux-x64`, AllLinux OCI archive): without the empty
singular properties, the archive has one image with no platform. With
them, it has `linux/amd64` and `linux/arm64`.

**Regression tests**, before (fix reverted in `src/`) and after:
- `CanBuildMultiPlatformArchiveFromFileBasedCSharpApp`: before, it fails
with `NETSDK1083: The specified RuntimeIdentifier '"linux-x64' is not
recognized`. After, it passes.
-
`BuildImageAsync_MultiPlatformArgumentsSurviveMsBuildParsing(fileBased:
True)`: before, it fails on the emitted arguments. After, it passes.
-
`CanBuildMultiPlatformArchiveFromFileBasedCSharpApp(withBuildEnvironment:
True)`: before, it fails with `MSB1006 ... Switch: linux-arm64`. After,
it passes.
-
`CanBuildMultiPlatformArchiveFromFileBasedCSharpApp(withProjectRuntimeIdentifiers:
True)`: before, `Expected "linux/amd64"`, `Actual "/"` (single image).
After, it passes.
- `BuildImageAsync_MultiPlatformArgumentsSurviveMsBuildParsing` (both
variants): before, they fail on the missing empty singular RIDs. After,
they pass.
- `CanBuildArchiveFromFileBasedCSharpApp` passes in both runs.

### Validation

- `ResourceContainerImageBuilderTests`, `DotnetProgramPublishingTests`
and `DockerContainerRuntimeTests`: 118 passed, 0 failed locally. This
includes both real file-based archive publishes. I excluded 14 tests
that load real images into Docker, because this machine runs out of disk
for base-image layers. CI runs them.
- `src/Aspire.Hosting.Dotnet`, which also compiles the shared
`MsBuildResponseFile.cs`, builds cleanly. Its
`DotnetProjectBuildEnvironmentTests` pass. Five
`DotnetProjectBuildCoordinatorTests` (traversal restore and
context-specific build) fail on this machine both with and without this
change, so those failures are environmental.
- `main` was merged in so I could update
`WslcDotnetPublishingTests.DotnetPublishing_ArchiveDoesNotInvokeWslc`
(from #21009) to expect the quoted RID list for
projects; the multi-platform expectation now also includes the empty
singular RIDs. That class is Windows-only (`SkipOnPlatform` on Linux and
macOS), so the Windows CI job verifies it.

Fixes #9281

## 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
      - [ ] No
  - [x] No

**🤖 Posted by AspireAgent (AI Agent)**

---------

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants