| 1 | # Microsoft.WSL.Containers |
| 2 | |
| 3 | > **⚠️ Preview:** This SDK is currently in preview and is subject to breaking changes |
| 4 | > in future releases without prior notice. Do not rely on API stability for production |
| 5 | > workloads. |
| 6 | |
| 7 | 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. |
| 8 | |
| 9 | **Supported platforms:** x64 and ARM64. |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## Using the native C/C++ API |
| 14 | |
| 15 | MSBuild (via NuGet) and CMake both configure include directories and link libraries automatically when you reference the package. Include the header and link: |
| 16 | |
| 17 | ```cpp |
| 18 | #include <wslcsdk.h> |
| 19 | ``` |
| 20 | |
| 21 | **MSBuild:** No manual configuration needed — `wslcsdk.lib` and the include directory are wired up by the imported targets. |
| 22 | |
| 23 | **CMake:** |
| 24 | ```cmake |
| 25 | find_package(Microsoft.WSL.Containers REQUIRED) |
| 26 | target_link_libraries(my_app PRIVATE Microsoft.WSL.Containers::SDK) |
| 27 | ``` |
| 28 | |
| 29 | The runtime DLL (`wslcsdk.dll`) is automatically copied to the output directory. |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## Using the WinRT projection |
| 34 | |
| 35 | ### C++/WinRT |
| 36 | |
| 37 | The package includes a WinRT metadata file and automatically: |
| 38 | - Adds `Microsoft.WSL.Containers.winmd` as a reference so C++/WinRT generates projection headers |
| 39 | - Injects an activation manifest into your binary so `RoGetActivationFactory` resolves the classes to `wslcsdk.dll` without COM registration |
| 40 | |
| 41 | **MSBuild — C++/WinRT (requires the [Microsoft.Windows.CppWinRT](https://www.nuget.org/packages/Microsoft.Windows.CppWinRT) NuGet package):** |
| 42 | ```cpp |
| 43 | #include <winrt/Microsoft.WSL.Containers.h> |
| 44 | |
| 45 | auto settings = winrt::Microsoft::WSL::Containers::SessionSettings(L"my-session", L"C:\\path\\to\\storage"); |
| 46 | ``` |
| 47 | |
| 48 | To disable C++/WinRT integration (suppress the winmd reference and manifest injection): |
| 49 | ```xml |
| 50 | <PropertyGroup> |
| 51 | <WslcEnableCppWinRT>false</WslcEnableCppWinRT> |
| 52 | </PropertyGroup> |
| 53 | ``` |
| 54 | |
| 55 | ### C#/WinRT |
| 56 | |
| 57 | **MSBuild — C# (.NET 8+):** The `wslcsdkcs.dll` projection assembly is referenced automatically. |
| 58 | ```csharp |
| 59 | using Microsoft.WSL.Containers; |
| 60 | |
| 61 | var settings = new SessionSettings("my-session", @"C:\path\to\storage"); |
| 62 | ``` |
| 63 | |
| 64 | --- |
| 65 | |
| 66 | ## Building container images |
| 67 | |
| 68 | 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). |
| 69 | |
| 70 | ### MSBuild |
| 71 | |
| 72 | Add `WslcImage` items to your project. Each item builds an image and saves it to a `.tar` archive at build time: |
| 73 | |
| 74 | ```xml |
| 75 | <ItemGroup> |
| 76 | <WslcImage Include="my-server" |
| 77 | Image="ghcr.io/myorg/my-server:latest" |
| 78 | Dockerfile="container/Dockerfile" |
| 79 | Context="container/" |
| 80 | Sources="container/src/**" |
| 81 | TarLocation="$(OutDir)my-server.tar" |
| 82 | BuildArgs="VERSION=1.2.3;COMMIT=abcdef" |
| 83 | Labels="org.opencontainers.image.source=https://example.com/repo" /> |
| 84 | </ItemGroup> |
| 85 | |
| 86 | <PropertyGroup> |
| 87 | <WslcImageBuildPull>true</WslcImageBuildPull> |
| 88 | <WslcImageBuildNoCache>false</WslcImageBuildNoCache> |
| 89 | </PropertyGroup> |
| 90 | ``` |
| 91 | |
| 92 | | Metadata | Required | Description | |
| 93 | |---|---|---| |
| 94 | | `Image` | Yes | Container image reference (`:latest` appended if no tag) | |
| 95 | | `Dockerfile` | Yes | Path to the Dockerfile | |
| 96 | | `Context` | Yes | Build context directory | |
| 97 | | `Sources` | No | Glob patterns for incremental rebuild tracking (defaults to all files in `Context`) | |
| 98 | | `TarLocation` | No | Output path for the saved `.tar` (defaults to `$(OutDir)<name>.tar`) | |
| 99 | | `BuildArgs` | No | Semicolon-separated `KEY=VALUE` build-time variables (each forwarded as `--build-arg`) | |
| 100 | | `Labels` | No | Semicolon-separated `KEY=VALUE` image labels (each forwarded as `--label`) | |
| 101 | |
| 102 | **Optional MSBuild properties:** |
| 103 | |
| 104 | | Property | Default | Description | |
| 105 | |---|---|---| |
| 106 | | `WslcCliPath` | `wslc` | Path to the `wslc` CLI executable | |
| 107 | | `WslcImageBuildPull` | `false` | Always attempt to pull newer base images (`--pull`) | |
| 108 | | `WslcImageBuildNoCache` | `false` | Build images without the layer cache (`--no-cache`) | |
| 109 | | `WslcPruneAfterBuild` | `false` | Run `wslc image prune` after each successful build | |
| 110 | | `WslcTreatPruneFailureAsError` | `false` | Fail the build if the post-build prune fails | |
| 111 | |
| 112 | ### CMake |
| 113 | |
| 114 | ```cmake |
| 115 | find_package(Microsoft.WSL.Containers REQUIRED) |
| 116 | |
| 117 | set(WSLC_IMAGE_BUILD_PULL ON) |
| 118 | set(WSLC_IMAGE_BUILD_NO_CACHE OFF) |
| 119 | |
| 120 | wslc_add_image(my-server |
| 121 | IMAGE ghcr.io/myorg/my-server:latest |
| 122 | DOCKERFILE container/Dockerfile |
| 123 | CONTEXT container/ |
| 124 | SOURCES container/src/*.cpp container/src/*.h |
| 125 | TAR_LOCATION ${CMAKE_CURRENT_BINARY_DIR}/my-server.tar |
| 126 | BUILD_ARGS VERSION=1.2.3 COMMIT=abcdef |
| 127 | LABELS org.opencontainers.image.source=https://example.com/repo |
| 128 | ) |
| 129 | |
| 130 | add_dependencies(my_app my-server) |
| 131 | ``` |
| 132 | |
| 133 | | Argument | Required | Description | |
| 134 | |---|---|---| |
| 135 | | `<target>` | Yes | Name of the CMake target to create (first positional argument) | |
| 136 | | `IMAGE` | Yes | Container image reference (`:latest` appended if no tag) | |
| 137 | | `DOCKERFILE` | Yes | Path to the Dockerfile | |
| 138 | | `CONTEXT` | Yes | Build context directory | |
| 139 | | `SOURCES` | No | Files or glob patterns for incremental rebuild tracking (defaults to all files in `CONTEXT`) | |
| 140 | | `TAR_LOCATION` | No | Output path for the saved `.tar` (defaults to `${CMAKE_CURRENT_BINARY_DIR}/<target>.tar`) | |
| 141 | | `BUILD_ARGS` | No | `KEY=VALUE` build-time variables (each forwarded as `--build-arg`) | |
| 142 | | `LABELS` | No | `KEY=VALUE` image labels (each forwarded as `--label`) | |
| 143 | |
| 144 | **Project-wide CMake variables:** |
| 145 | |
| 146 | | Variable | Default | Description | |
| 147 | |---|---|---| |
| 148 | | `WSLC_CLI_PATH` | Found on `PATH` | Path to the `wslc` CLI executable | |
| 149 | | `WSLC_IMAGE_BUILD_PULL` | `OFF` | Always attempt to pull newer base images (`--pull`) | |
| 150 | | `WSLC_IMAGE_BUILD_NO_CACHE` | `OFF` | Build images without the layer cache (`--no-cache`) | |
| 151 | | `WSLC_PRUNE_AFTER_BUILD` | `OFF` | Run `wslc image prune` after each successful build | |
| 152 | | `WSLC_TREAT_PRUNE_FAILURE_AS_ERROR` | `OFF` | Fail the build if the post-build prune fails | |
| 153 | |
| 154 | --- |
| 155 | |
| 156 | ## Prerequisites |
| 157 | |
| 158 | - **WSL** — Install with `wsl --install --no-distribution` (provides the `wslc` CLI) |
| 159 | - **C++/WinRT** — Install the [Microsoft.Windows.CppWinRT](https://www.nuget.org/packages/Microsoft.Windows.CppWinRT) NuGet package for C++/WinRT projection support |