WSL 容器功能包含兩個主要組件:一個用於wslc.exe建置、執行及與 Linux 容器互動的 CLI,以及一個 WSL 容器 API,讓 Windows 應用程式開發者能將 Linux 容器作為應用程式邏輯的一部分。
Important
WSL 容器功能需要 WSL 2.9.3 或更高版本。 要更新到最新版本,請打開 PowerShell 並輸入:
wsl --update
您可以隨時使用 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
你可以在 我們的容器教學中了解更多如何開始使用此功能。
若要為 wslc.exe 設定資源及其他選項,如 CPU 數量、記憶體及儲存位置,請參閱 WSL 容器設定。
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 標頭檔。
使用 .NET CLI 將套件新增至專案:
dotnet add package Microsoft.WSL.Containers
然後在程式碼中匯入命名空間:
using Microsoft.WSL.Containers;
API 概觀
API 以一小組物件為核心組織,這些物件反映容器運行的生命週期:
| 物件 | Description |
|---|---|
WslcService |
服務層級操作的靜態入口點。 用它檢查所需的 WSL 元件是否已安裝、查詢服務版本,以及安裝缺少的相依關係。 |
Session |
一個由 WSL 支援的主機來運行你的容器。 會話負責管理影像(拉取、匯入、載入、推送、標籤、刪除)並建立容器。 |
Container |
一個在會話中建立的容器。 用它來啟動、停止、檢查和刪除容器,並在裡面執行額外的程序。 |
Process |
一個在容器中運行的 Linux 程序。 用它來讀取 stdout/stderr、寫入 stdin、發送訊號,並透過事件觀察離場代碼。 |
典型流程是:使用 WslcService 驗證前置條件、建立並啟動 Session、拉取映像檔、設定並建立 Container,然後啟動它並與其 Process 物件互動。
範例片段
以下摘錄展示了每種支援語言中相同的核心建構模組。 用 Tab 鍵在 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();
完整的端對端範例
上面的片段展示了核心的組件。 欲了解完整且可執行的範例,涵蓋完整的容器生命週期、映像管理、埠映射、卷掛載、GPU 存取及互動 stdin/stdout 式串流,請參閱 WSL 容器 API 範例。