WSL 容器

WSL 容器功能有两个主要组件：调用 wslc.exe CLI 来生成、运行和与 Linux 容器以及 WSL 容器 API 进行交互，允许Windows应用开发人员使用 Linux 容器作为其应用逻辑的一部分。

WSL 容器命令行界面

WSL 现在已内置 wslc.exe 二进制文件。 其目标是拥有熟悉的 CLI 界面，使你能够轻松生成、运行和与 Linux 容器交互。

请参阅下面的一些示例命令：

# Run a container
wslc run --rm -it ubuntu:latest bash -c "echo Hello world from WSL container!"
# List available images
wslc image ls
# Run a web server
wslc run -it --rm -d -p 8080:80 --name web nginx
# Get its content
curl localhost:8080
# List the container
wslc container ps
# Stop the container
wslc container stop web

可以在 容器教程中详细了解如何开始使用此功能。

WSL 容器 API

Windows应用程序也可以使用 Linux 容器！ WSL 容器 API NuGet 程序包允许你通过编程方式拉取、运行 Linux 容器并与其交互，包括 stdin 和 stdout、文件挂载、网络挂载、GPU 访问等关键交互操作。

有关 C、C# 和 C++ 投影的完整 API 外围应用，请参阅 WSL 容器 API 参考。

安装 API

WSL 容器 API 随附在 Microsoft.WSL.Containers NuGet 包中，该包提供 C# 投影和 C++/WinRT 标头。

C#

使用 .NET CLI 将包添加到项目：

dotnet add package Microsoft.WSL.Containers

然后在代码中导入命名空间：

using Microsoft.WSL.Containers;

C++

将 Microsoft.WSL.Containers NuGet 包添加到你的 C++/WinRT 项目，然后包含投影头文件并将命名空间引入作用域：

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

using namespace winrt::Microsoft::WSL::Containers;

注释

C++/WinRT 投影处于预览状态，可能会发生中断性变更。

API 概述

API 围绕一小部分对象进行组织，这些对象反映了运行容器的生命周期：

对象	Description
WslcService	服务级操作的静态入口点。 使用它检查是否已安装所需的 WSL 组件、查询服务版本并安装缺少的依赖项。
Session	运行你的容器的 WSL 后端主机。 会话管理映像（拉取、导入、加载、推送、标记、删除）并创建容器。
Container	在会话中创建的容器。 使用它可以启动、停止、检查和删除容器，并在其中运行其他进程。
Process	在容器中运行的 Linux 进程。 使用它读取 stdout/stderr、向 stdin 写入、发送信号，并通过事件观察退出代码。

典型的流是：验证先决条件 WslcService，创建和启动 Session、拉取映像、配置和创建一个 Container，然后启动它并与其 Process 对象交互。

示例代码片段

下面的代码片段显示了每个受支持的语言中的相同核心构建基块。 使用选项卡在 C# 和 C++ 之间切换。

C#

检查是否已安装所需的组件：

ComponentFlags missing = WslcService.GetMissingComponents();
if (missing != ComponentFlags.None)
{
    Console.WriteLine($"WSL components are missing ({missing}). Run: wsl --install");
    return;
}

创建并启动会话：

var sessionSettings = new SessionSettings("MyApp", @"C:\WslcData")
{
    CpuCount = 4,
    MemoryMB = 4096
};

var session = new Session(sessionSettings);
session.Start();

拉取包含进度报告的映像：

var pull = session.PullImageAsync(new PullImageOptions("docker.io/library/alpine:latest"));
pull.Progress = (op, progress) =>
    Console.WriteLine($"Pull: {progress.Status} {progress.CurrentBytes}/{progress.TotalBytes}");
await pull;

创建容器、运行命令并读取其输出：

var initProcess = new ProcessSettings
{
    CmdLine = new[] { "/bin/echo", "Hello from WSL Container!" },
    OutputMode = ProcessOutputMode.Event
};

var containerSettings = new ContainerSettings("alpine:latest")
{
    Name = "hello-container",
    InitProcess = initProcess
};

var container = session.CreateContainer(containerSettings);

container.InitProcess.OutputReceived += data =>
    Console.Write(Encoding.UTF8.GetString(data));

container.Start();

完成后，停止并删除容器，然后终止会话以释放资源：

container.Stop(Signal.SIGTERM, TimeSpan.FromSeconds(10));
container.Delete(DeleteContainerFlags.None);
session.Terminate();

C++

这些代码片段使用 C++/WinRT。 异步调用使用 co_await，因此它们必须在协程内运行。

检查是否已安装所需的组件：

auto missing = WslcService::GetMissingComponents();
if (missing != ComponentFlags::None)
{
    printf("WSL components are missing. Run: wsl --install\n");
    return;
}

创建并启动会话：

SessionSettings sessionSettings{ L"MyApp", L"C:\\WslcData" };
sessionSettings.CpuCount(4);
sessionSettings.MemoryMB(4096);

Session session{ sessionSettings };
session.Start();

拉取包含进度报告的映像：

PullImageOptions pullOptions{ L"docker.io/library/alpine:latest" };
auto pull = session.PullImageAsync(pullOptions);
pull.Progress([](auto&&, ImageProgress const& progress)
{
    printf("Pull: %d %llu/%llu\n",
        static_cast<int>(progress.Status()),
        progress.CurrentBytes(),
        progress.TotalBytes());
});
co_await pull;

创建容器、运行命令并读取其输出：

using namespace winrt::Windows::Foundation::Collections;

ProcessSettings initProcess;
initProcess.OutputMode(ProcessOutputMode::Event);

auto cmdLine = single_threaded_vector<hstring>();
cmdLine.Append(L"/bin/echo");
cmdLine.Append(L"Hello from WSL Container!");
initProcess.CmdLine(cmdLine);

ContainerSettings containerSettings{ L"alpine:latest" };
containerSettings.Name(L"hello-container");
containerSettings.InitProcess(initProcess);

auto container = session.CreateContainer(containerSettings);

container.InitProcess().OutputReceived([](auto const& data)
{
    std::string text(data.begin(), data.end());
    printf("%s", text.c_str());
});

container.Start();

完成后，停止并删除容器，然后终止会话以释放资源：

container.Stop(Signal::SIGTERM, std::chrono::seconds(10));
container.Delete(DeleteContainerFlags::None);
session.Terminate();

完整端到端示例

上面的代码片段显示了核心构建基块。 有关涵盖整个容器生命周期、映像管理、端口映射、卷挂载、GPU 访问以及交互式 stdin/stdout 流传输的完整可运行示例，请参阅 WSL 容器 API 示例。