Kontejner WSL

Funkce kontejneru WSL má dvě hlavní komponenty: rozhraní příkazového řádku označované wslc.exe k sestavení, spouštění a interakci s kontejnery Linuxu a rozhraní API kontejneru WSL, které Windows vývojářům aplikací umožňuje používat kontejnery linuxových aplikací jako součást logiky aplikace.

Important

Funkce kontejnerů WSL vyžaduje WSL verzi 2.9.3 nebo vyšší. Tato verze je aktuálně dostupná jenom jako předběžná verze, takže ji musíte nainstalovat tak, že otevřete PowerShell a zadáte:

wsl --update --pre-release

Nainstalovanou verzi můžete kdykoli zkontrolovat pomocí wsl --version.

CLI kontejnerů WSL

WSL teď obsahuje wslc.exe jako integrovaný binární soubor. Jejím cílem je mít známé rozhraní příkazového řádku, které vám umožní snadno sestavovat, spouštět a pracovat s kontejnery Linuxu.

Podívejte se na některé z následujících ukázkových příkazů:

# 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

Další informace o tom, jak začít s touto funkcí, najdete v našem kurzu kontejneru.

Rozhraní API kontejneru WSL

Windows aplikace můžou využívat i kontejnery Linuxu. Balíček NuGet rozhraní API kontejneru WSL umožňuje programově načíst, spustit a pracovat s kontejnery Linuxu, včetně interakcí s klíči, jako jsou stdin a stdout, připojení souborů, síťové připojení, přístup GPU a další.

Kompletní plochu rozhraní API pro projekce jazyka C, C# a C++ najdete v referenčních informacích k rozhraní API kontejneru WSL.

Instalace rozhraní API

Rozhraní API kontejnerů WSL je součástí balíčku Microsoft.WSL.Containers NuGet, který poskytuje jak projekci pro C#, tak hlavičkové soubory C++/WinRT.

C#

Přidejte balíček do projektu pomocí .NET CLI:

dotnet add package Microsoft.WSL.Containers

Potom naimportujte obor názvů do kódu:

using Microsoft.WSL.Containers;

C++

Přidejte do svého projektu C++/WinRT balíček NuGet Microsoft.WSL.Containers, potom zahrňte vygenerovanou hlavičku a zaveďte obor názvů do aktuálního oboru platnosti:

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

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

Note

Projekce C++/WinRT je ve verzi Preview a podléhá zásadním změnám.

Přehled rozhraní API

Rozhraní API je uspořádané kolem malé sady objektů, které zrcadlí životní cyklus spuštění kontejneru:

Object	Description
WslcService	Statický vstupní bod pro operace na úrovni služby Slouží ke kontrole, jestli jsou nainstalované požadované součásti WSL, dotazují se na verzi služby a nainstalují chybějící závislosti.
Session	Hostitel využívající WSL, který spouští vaše kontejnery. Relace spravuje image (stahování, import, načítání, odesílání, tagování, odstraňování) a vytváří kontejnery.
Container	Kontejner vytvořený v rámci relace. Můžete ho použít ke spuštění, zastavení, kontrole a odstranění kontejneru a ke spouštění dalších procesů uvnitř kontejneru.
Process	Proces Linuxu spuštěný v kontejneru Použijte ho ke čtení stdout/stderr, k zápisu do stdin, k odesílání signálů a ke sledování ukončovacích kódů prostřednictvím událostí.

Typický postup je: ověřit požadavky pomocí WslcService, vytvořit a spustit Session, stáhnout image, nakonfigurovat a vytvořit Container, poté jej spustit a pracovat s jeho objekty Process.

Ukázkové fragmenty kódu

Níže uvedené fragmenty kódu zobrazují stejné základní stavební bloky v každém podporovaném jazyce. Pomocí karet můžete přepínat mezi C# a C++.

C#

Zkontrolujte, jestli jsou nainstalované požadované komponenty:

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

Vytvoření a spuštění relace:

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

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

Stáhněte image se zobrazením průběhu:

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;

Vytvořte kontejner, spusťte příkaz a přečtěte si jeho výstup:

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();

Až budete hotovi, zastavte a odstraňte kontejner a ukončete relaci a uvolněte prostředky:

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

C++

Tyto fragmenty kódu používají C++/WinRT. Asynchronní volání používají co_await, takže musí běžet uvnitř korutiny.

Zkontrolujte, jestli jsou nainstalované požadované komponenty:

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

Vytvoření a spuštění relace:

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

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

Stáhněte image se zobrazením průběhu:

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;

Vytvořte kontejner, spusťte příkaz a přečtěte si jeho výstup:

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();

Až budete hotovi, zastavte a odstraňte kontejner a ukončete relaci a uvolněte prostředky:

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

Kompletní ukázky od začátku do konce

Výše uvedené fragmenty kódu zobrazují základní stavební bloky. Úplné spustitelné příklady, které pokrývají celý životní cyklus kontejneru, správu imagů, mapování portů, připojování svazků, přístup ke GPU a interaktivní stdin/stdout streamování, najdete v ukázkách rozhraní WSL Container API.