Add MSBuild and CMake build integration for WSLC container images

[shuaiyuanxx]

Summary of the Pull Request

Add build-system integration to the Microsoft.WSL.Containers NuGet package so developers can declaratively build WSLC container images and export them to tar files as part of their MSBuild (C++/C#) and CMake workflows, with full incremental rebuild support.

Developers declare <WslcImage> items (MSBuild) or call wslc_add_image() (CMake) in their project, and the build system automatically runs wslc image build followed by wslc image save after the main build, skipping both when sources haven't changed.

PR Checklist

• Closes: Link to issue #xxx
• Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
• Tests: Added/updated if needed and all pass
• Localization: All end user facing strings can be localized
• Dev docs: Added/updated if needed
• Documentation updated: If checked, please file a pull request on our docs repo and link it here: #xxx

Detailed Description of the Pull Request / Additional comments

New files

File	Description
build/Microsoft.WSL.Containers.common.targets	Core MSBuild targets shared by C++ and C#: wslc CLI validation (WSLC0001), item metadata validation (WSLC0002–WSLC0004), incremental image build, image save to tar (atomic via .tmp + <Move>), optional prune, design-time build guard, and clean target
build/native/Microsoft.WSL.Containers.targets	C++ specific: writes .tlog files (one path per line via ItemGroup) for VS Fast Up-to-Date Check
build/net/Microsoft.WSL.Containers.targets	C# specific: registers CPS UpToDateCheckInput/UpToDateCheckBuilt items for VS up-to-date check
cmake/Microsoft.WSL.ContainersConfig.cmake	wslc_add_image() CMake function: target-name validation, IMAGE parsing with auto-:latest append, path normalization, CONFIGURE_DEPENDS glob, atomic save via cmake -E rename

Usage — MSBuild (C++ / C#)

<ItemGroup>
  <WslcImage Include="echo-server"
             Image="echo-server:latest"
             Dockerfile="container\server\Dockerfile"
             Context="container\server"
             Sources="container\server;container\shared"
             TarLocation="$(OutDir)echo-server.tar" />
</ItemGroup>

• Image is the full image reference (may include a tag); :latest is appended automatically when no tag is given.
• TarLocation is the output path for the saved tar (defaults to $(OutDir)<Identity>.tar).
• Set <WslcPruneAfterBuild>true</WslcPruneAfterBuild> to also run wslc image prune after save (off by default).

Usage — CMake

find_package(Microsoft.WSL.Containers REQUIRED)
wslc_add_image(echo-server
    IMAGE        ghcr.io/myorg/echo-server:latest
    DOCKERFILE   container/Dockerfile
    CONTEXT      container/
    SOURCES      container/src/*.cpp container/src/*.h
    TAR_LOCATION ${CMAKE_CURRENT_BINARY_DIR}/echo-server.tar
)
add_dependencies(my_app echo-server)

• IMAGE is the container image reference (required); :latest is appended automatically when no tag is given.
• TAR_LOCATION defaults to ${CMAKE_CURRENT_BINARY_DIR}/<target>.tar. The tar is removed by cmake --build . --target clean (and Visual Studio's Clean).
• Pass PRUNE_AFTER_BUILD to also run wslc image prune after save (off by default).

Key design decisions

• Image build + save chain — wslc image build produces the image; wslc image save -o <path> then exports it to a tar that downstream code can load via WslcLoadSessionImageFromFile or wslc image load. Both steps run as part of the build, with full incremental tracking.
• Atomic save via .tmp + rename — wslc image save uses CREATE_ALWAYS, which truncates the destination on entry. The integration writes to <tar>.tmp and renames on success (cmake -E rename / MSBuild <Move>), so a failed save never leaves a partial tar that would mislead the incremental check.
• Incremental tracking — MSBuild Inputs/Outputs and CMake add_custom_command(OUTPUT ...) track sources to skip both image build and save when nothing has changed. MSBuild uses a stamp file for the image build step (since image build doesn't produce a host file); CMake uses the tar directly as the output.
• Optional prune — wslc image prune affects the entire daemon image store, so it's off by default. Opt in via <WslcPruneAfterBuild>true</WslcPruneAfterBuild> (MSBuild) or PRUNE_AFTER_BUILD flag (CMake).
• Semicolon-safe property passing — Sources metadata is escaped via $([MSBuild]::Escape()) before being passed through MSBuild task Properties=, and unescaped at the consumption site, so multi-directory paths work correctly.
• Design-time build guard — All build and validation targets are skipped when $(DesignTimeBuild) == 'true' to avoid slowing the VS IDE.
• wslc CLI on PATH — The integration relies on wslc.exe being on PATH (the WSL MSI puts it there) rather than guessing install locations. CMake uses find_program(WSLC_CLI_PATH wslc); MSBuild defaults WslcCliPath to bare wslc so cmd.exe resolves it.
• Input validation — Dockerfile and Context are required; Identity is validated against invalid filename characters with actionable error codes (WSLC0001–WSLC0004).

Validation Steps Performed

All tests run locally against wslc 2.7.3+ on Windows 11 (26200):

Test	Result
C++ MSBuild: fresh build (image build + save)	Pass
C++ MSBuild: incremental skip — no changes (both build and save skipped)	Pass
C++ MSBuild: rebuild on source change (image rebuilt, tar re-saved)	Pass
C++ MSBuild: clean removes both stamp and tar	Pass
C++ MSBuild: opt-in prune (/p:WslcPruneAfterBuild=true)	Pass
C# (.NET 8): fresh build	Pass
C# (.NET 8): incremental skip	Pass
C# (.NET 8): rebuild on source change	Pass
CMake (VS 2022 generator): configure	Pass
CMake: fresh build (image build + save + optional prune)	Pass
CMake: incremental skip	Pass
CMake: rebuild on source change	Pass
CMake: cmake --build . --target clean removes the tar	Pass
CMake: opt-in prune (PRUNE_AFTER_BUILD flag)	Pass
Validation: missing Dockerfile → error WSLC0002	Pass
Validation: Identity with / → error WSLC0004	Pass
CMake: invalid target name → FATAL_ERROR	Pass
CMake: empty SOURCES defaults to CONTEXT contents	Pass
End-to-end: build → save tar → load via WslcLoadSessionImageFromFile → start container → capture stdout	Pass

[benhillis]

Hey @shuaiyuanxx 👋 — Following up on this draft PR. There are 11 unresolved review threads covering design and implementation feedback (flag file vs tar output, image save requirement, target naming, GLOB_RECURSE validation, VS design-time build interference, etc.).

Is this still actively being developed? The PR is marked DO NOT MERGE — just checking in on the status and whether the approach is still the planned direction.

[shuaiyuanxx]

Hey @shuaiyuanxx 👋 — Following up on this draft PR. There are 11 unresolved review threads covering design and implementation feedback (flag file vs tar output, image save requirement, target naming, GLOB_RECURSE validation, VS design-time build interference, etc.).

Is this still actively being developed? The PR is marked DO NOT MERGE — just checking in on the status and whether the approach is still the planned direction.

Hi @benhillis, thanks for following up.

Yes — this is still actively being developed. The design direction has been reviewed and approved via the spec. This PR is ready for review now.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.