Kontener WSL

Funkcja kontenera WSL ma dwa główne składniki: interfejs wiersza polecenia wywoływany wslc.exe do kompilowania, uruchamiania i interakcji z kontenerami systemu Linux oraz interfejsu API kontenera WSL umożliwiającego deweloperom aplikacji Windows używanie kontenerów systemu Linux w ramach logiki aplikacji.

Important

Funkcja kontenera WSL wymaga programu WSL w wersji 2.9.3 lub nowszej. Ta wersja jest obecnie dostępna tylko jako wersja wstępna, dlatego należy ją zainstalować, otwierając program PowerShell i wprowadzając następujące polecenie:

wsl --update --pre-release

Sprawdź zainstalowaną wersję w dowolnym momencie za pomocą polecenia wsl --version.

Interfejs wiersza poleceń kontenera WSL

WSL zawiera wslc.exe teraz jako wbudowany plik binarny. Jego celem jest posiadanie znanego interfejsu wiersza polecenia, który umożliwia łatwe kompilowanie, uruchamianie i interakcję z kontenerami systemu Linux.

Zapoznaj się z poniższymi przykładowymi poleceniami:

# 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

Więcej informacji na temat rozpoczynania pracy z tą funkcją można znaleźć w naszym samouczku dotyczącym kontenera.

Interfejs API kontenera WSL

Windows aplikacje mogą również korzystać z kontenerów systemu Linux. Pakiet NuGet interfejsu API kontenerów WSL umożliwia programowe pobieranie, uruchamianie i komunikację z kontenerami Linuksa, w tym wykonywanie kluczowych operacji, takich jak obsługa stdin i stdout, montowanie plików, montowanie zasobów sieciowych, dostęp do GPU i nie tylko.

Aby uzyskać pełną powierzchnię interfejsu API w projekcjach C, C# i C++, zobacz dokumentację interfejsu API kontenera WSL.

Instalowanie interfejsu API

Interfejs API kontenera WSL jest dostarczany w Microsoft.WSL.Containers pakiecie NuGet, który udostępnia zarówno projekcję języka C#, jak i nagłówki języka C++/WinRT.

C#

Dodaj pakiet do projektu przy użyciu interfejsu wiersza polecenia platformy .NET:

dotnet add package Microsoft.WSL.Containers

Następnie zaimportuj przestrzeń nazw w kodzie:

using Microsoft.WSL.Containers;

C++

Dodaj pakiet NuGet Microsoft.WSL.Containers do projektu C++/WinRT, a następnie dołącz wygenerowany plik nagłówkowy i wprowadź przestrzeń nazw do zakresu:

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

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

Note

Projekcja C++/WinRT jest w wersji zapoznawczej i może ulec zmianie powodującej niezgodność.

Przegląd interfejsu API

Interfejs API jest zorganizowany wokół małego zestawu obiektów, które dublują cykl życia uruchamiania kontenera:

Object	Description
WslcService	Statyczny punkt wejścia dla operacji na poziomie usługi. Użyj go, aby sprawdzić, czy wymagane składniki WSL są zainstalowane, wykonać zapytanie o wersję usługi i zainstalować brakujące zależności.
Session	Host oparty na WSL, na którym są uruchamiane kontenery. Sesja zarządza obrazami (ściąganie, importowanie, ładowanie, wypychanie, tag, usuwanie) i tworzy kontenery.
Container	Kontener utworzony wewnątrz sesji. Służy do uruchamiania, zatrzymywania, inspekcji i usuwania kontenera oraz uruchamiania w nim dodatkowych procesów.
Process	Proces systemu Linux uruchomiony w kontenerze. Służy do odczytywania stdout/stderr, zapisu do stdin, wysyłania sygnałów i obserwowania kodów zakończenia za pośrednictwem zdarzeń.

Typowy przebieg jest następujący: zweryfikować wymagania wstępne za pomocą polecenia WslcService, utworzyć i uruchomić Session, pobrać obraz, skonfigurować i utworzyć obiekt Container, a następnie uruchomić go i wchodzić w interakcję z jego obiektami Process.

Przykładowe fragmenty kodu

Poniższe fragmenty kodu pokazują te same podstawowe bloki konstrukcyjne w każdym obsługiwanym języku. Użyj kart, aby przełączać się między językami C# i C++.

C#

Sprawdź, czy wymagane składniki są zainstalowane:

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

Utwórz i rozpocznij sesję:

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

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

Pobierz obraz z raportowaniem postępu:

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;

Utwórz kontener, uruchom polecenie i odczytaj jego dane wyjściowe:

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

Po zakończeniu zatrzymaj i usuń kontener, a następnie zakończ sesję, aby zwolnić zasoby:

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

C++

Te fragmenty kodu używają języka C++/WinRT. Wywołania asynchroniczne używają metody co_await, więc muszą być uruchamiane wewnątrz kohroutyny.

Sprawdź, czy wymagane składniki są zainstalowane:

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

Utwórz i rozpocznij sesję:

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

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

Pobierz obraz z raportowaniem postępu:

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;

Utwórz kontener, uruchom polecenie i odczytaj jego dane wyjściowe:

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

Po zakończeniu zatrzymaj i usuń kontener, a następnie zakończ sesję, aby zwolnić zasoby:

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

Kompletne przykłady end-to-end

Powyższe fragmenty kodu pokazują podstawowe bloki konstrukcyjne. Pełne, gotowe do uruchomienia przykłady obejmujące pełny cykl życia kontenera, zarządzanie obrazami, mapowanie portów, montowanie woluminów, dostęp do GPU oraz interakcyjne stdin/stdout strumieniowanie znajdziesz w przykładach interfejsu API kontenera WSL.