Microsoft.WSL.Containers 3.0.3

Microsoft.WSL.Containers

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

Optional MSBuild properties:

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)

Project-wide CMake variables:

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