Microsoft.WSL.Containers 2.9.3

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:

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

#include <winrt/Microsoft.WSL.Containers.h>

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

<PropertyGroup>
  <WslcEnableCppWinRT>false</WslcEnableCppWinRT>
</PropertyGroup>

C#/WinRT

MSBuild — C# (.NET 8+): The wslcsdkcs.dll projection assembly is referenced automatically.

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 only rebuild when sources 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" />
</ItemGroup>

Optional MSBuild properties:

CMake

find_package(Microsoft.WSL.Containers REQUIRED)

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
)

add_dependencies(my_app my-server)

Set WSLC_CLI_PATH to override the wslc executable location. Pass PRUNE_AFTER_BUILD to prune dangling images after each build.

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