WSL 容器

WSL 容器功能包含兩個主要組件：一個用於wslc.exe建置、執行及與 Linux 容器互動的 CLI，以及一個 WSL 容器 API，讓 Windows 應用程式開發者能將 Linux 容器作為應用程式邏輯的一部分。

Important

WSL 容器功能需要 WSL 2.9.3 或更高版本。 此版本目前僅以預發布版本提供，因此您需要透過開啟 PowerShell 並輸入以下方式安裝：

wsl --update --pre-release

您可以隨時使用 wsl --version 檢查已安裝的版本。

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;

Note

C++/WinRT 投影目前處於預覽階段，可能會有重大變動。

API 概觀

API 以一小組物件為核心組織，這些物件反映容器運行的生命週期：

物件	Description
WslcService	服務層級操作的靜態入口點。 用它檢查所需的 WSL 元件是否已安裝、查詢服務版本，以及安裝缺少的相依關係。
Session	一個由 WSL 支援的主機來運行你的容器。 會話負責管理影像（拉取、匯入、載入、推送、標籤、刪除）並建立容器。
Container	一個在會話中建立的容器。 用它來啟動、停止、檢查和刪除容器，並在裡面執行額外的程序。
Process	一個在容器中運行的 Linux 程序。 用它來讀取 stdout/stderr、寫入 stdin、發送訊號，並透過事件觀察離場代碼。

典型流程是：使用 WslcService 驗證前置條件、建立並啟動 Session、拉取映像檔、設定並建立 Container，然後啟動它並與其 Process 物件互動。

範例片段

以下摘錄展示了每種支援語言中相同的核心建構模組。 用 Tab 鍵在 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 範例。