Microsoft.WSL.Containers

⚠️ Preview: This SDK is currently in preview and is subject to breaking changes in future releases without prior notice. Do not rely on API stability for production workloads.

The WSL Containers SDK provides APIs for creating and managing Linux containers running inside WSL, and MSBuild/CMake integration for building container images as part of your project.

Supported platforms: x64 and ARM64.

Using the native C/C++ API

MSBuild (via NuGet) and CMake both configure include directories and link libraries automatically when you reference the package. Include the header and link:

#include <wslcsdk.h>

MSBuild: No manual configuration needed — wslcsdk.lib and the include directory are wired up by the imported targets.

CMake: cmake find_package(Microsoft.WSL.Containers REQUIRED) target_link_libraries(my_app PRIVATE Microsoft.WSL.Containers::SDK)

The runtime DLL (wslcsdk.dll) is automatically copied to the output directory.

Using the WinRT projection

C++/WinRT

The package includes a WinRT metadata file and automatically: - Adds Microsoft.WSL.Containers.winmd as a reference so C++/WinRT generates projection headers - Injects an activation manifest into your binary so RoGetActivationFactory resolves the classes to wslcsdk.dll without COM registration

MSBuild — C++/WinRT (requires the Microsoft.Windows.CppWinRT NuGet package): ```cpp #include

auto settings = winrt::Microsoft::WSL::Containers::SessionSettings(L"my-session", L"C:\path\to\storage"); ```

To disable C++/WinRT integration (suppress the winmd reference and manifest injection): xml <PropertyGroup> <WslcEnableCppWinRT>false</WslcEnableCppWinRT> </PropertyGroup>

C#/WinRT

MSBuild — C# (.NET 8+): The wslcsdkcs.dll projection assembly is referenced automatically. ```csharp using Microsoft.WSL.Containers;

var settings = new SessionSettings("my-session", @"C:\path\to\storage"); ```

Building container images

The package integrates the wslc CLI into your build system so container images are built and saved as part of your normal project build, with incremental rebuild support (images rebuild when tracked sources or image build options change).

MSBuild

Add WslcImage items to your project. Each item builds an image and saves it to a .tar archive at build time:

<ItemGroup>
  <WslcImage Include="my-server"
             Image="ghcr.io/myorg/my-server:latest"
             Dockerfile="container/Dockerfile"
             Context="container/"
             Sources="container/src/**"
             TarLocation="$(OutDir)my-server.tar"
             BuildArgs="VERSION=1.2.3;COMMIT=abcdef"
             Labels="org.opencontainers.image.source=https://example.com/repo" />
</ItemGroup>

<PropertyGroup>
  <WslcImageBuildPull>true</WslcImageBuildPull>
  <WslcImageBuildNoCache>false</WslcImageBuildNoCache>
</PropertyGroup>

Metadata	Required	Description
`Image`	Yes	Container image reference (`:latest` appended if no tag)
`Dockerfile`	Yes	Path to the Dockerfile
`Context`	Yes	Build context directory
`Sources`	No	Glob patterns for incremental rebuild tracking (defaults to all files in `Context`)
`TarLocation`	No	Output path for the saved `.tar` (defaults to `$(OutDir)<name>.tar`)
`BuildArgs`	No	Semicolon-separated `KEY=VALUE` build-time variables (each forwarded as `--build-arg`)
`Labels`	No	Semicolon-separated `KEY=VALUE` image labels (each forwarded as `--label`)

Optional MSBuild properties:

Property	Default	Description
`WslcCliPath`	`wslc`	Path to the `wslc` CLI executable
`WslcImageBuildPull`	`false`	Always attempt to pull newer base images (`--pull`)
`WslcImageBuildNoCache`	`false`	Build images without the layer cache (`--no-cache`)
`WslcPruneAfterBuild`	`false`	Run `wslc image prune` after each successful build
`WslcTreatPruneFailureAsError`	`false`	Fail the build if the post-build prune fails

CMake

find_package(Microsoft.WSL.Containers REQUIRED)

set(WSLC_IMAGE_BUILD_PULL ON)
set(WSLC_IMAGE_BUILD_NO_CACHE OFF)

wslc_add_image(my-server
    IMAGE        ghcr.io/myorg/my-server:latest
    DOCKERFILE   container/Dockerfile
    CONTEXT      container/
    SOURCES      container/src/*.cpp container/src/*.h
    TAR_LOCATION ${CMAKE_CURRENT_BINARY_DIR}/my-server.tar
    BUILD_ARGS   VERSION=1.2.3 COMMIT=abcdef
    LABELS       org.opencontainers.image.source=https://example.com/repo
)

add_dependencies(my_app my-server)

Argument	Required	Description
`<target>`	Yes	Name of the CMake target to create (first positional argument)
`IMAGE`	Yes	Container image reference (`:latest` appended if no tag)
`DOCKERFILE`	Yes	Path to the Dockerfile
`CONTEXT`	Yes	Build context directory
`SOURCES`	No	Files or glob patterns for incremental rebuild tracking (defaults to all files in `CONTEXT`)
`TAR_LOCATION`	No	Output path for the saved `.tar` (defaults to `${CMAKE_CURRENT_BINARY_DIR}/<target>.tar`)
`BUILD_ARGS`	No	`KEY=VALUE` build-time variables (each forwarded as `--build-arg`)
`LABELS`	No	`KEY=VALUE` image labels (each forwarded as `--label`)

Project-wide CMake variables:

Variable	Default	Description
`WSLC_CLI_PATH`	Found on `PATH`	Path to the `wslc` CLI executable
`WSLC_IMAGE_BUILD_PULL`	`OFF`	Always attempt to pull newer base images (`--pull`)
`WSLC_IMAGE_BUILD_NO_CACHE`	`OFF`	Build images without the layer cache (`--no-cache`)
`WSLC_PRUNE_AFTER_BUILD`	`OFF`	Run `wslc image prune` after each successful build
`WSLC_TREAT_PRUNE_FAILURE_AS_ERROR`	`OFF`	Fail the build if the post-build prune fails

Prerequisites

WSL — Install with wsl --install --no-distribution (provides the wslc CLI)
C++/WinRT — Install the Microsoft.Windows.CppWinRT NuGet package for C++/WinRT projection support

#Microsoft.WSL.Containers

#Using the native C/C++ API

#Using the WinRT projection

#C++/WinRT

#C#/WinRT

#Building container images

#MSBuild

#CMake

#Prerequisites