WSL-container

De WSL-containerfunctie heeft twee belangrijke onderdelen: een CLI die wordt aangeroepen wslc.exe voor het bouwen, uitvoeren en gebruiken van Linux-containers en een WSL-container-API waarmee Windows app-ontwikkelaars Linux-containers kunnen gebruiken als onderdeel van hun app-logica.

Important

Voor de WSL-containerfunctie is WSL versie 2.9.3 of hoger vereist. Deze versie is momenteel alleen beschikbaar als een voorlopige versie, dus u moet deze installeren door PowerShell te openen en het volgende in te voeren:

wsl --update --pre-release

Controleer uw geïnstalleerde versie op elk gewenst moment met wsl --version.

WSL-container-CLI

WSL bevat wslc.exe nu als een ingebouwd binair bestand. Het doel is om een vertrouwde CLI-interface te hebben, zodat u eenvoudig Linux-containers kunt bouwen, uitvoeren en ermee kunt werken.

Bekijk enkele van de onderstaande voorbeeldopdrachten:

# 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

In onze zelfstudie over containers vindt u meer informatie over hoe u aan de slag kunt met deze functie.

WSL-container-API

Windows toepassingen kunnen ook gebruikmaken van Linux-containers. Met het NuGet-pakket van de WSL-container-API kunt u programmatisch Linux-containers ophalen, uitvoeren en gebruiken, waaronder belangrijke interacties zoals stdin en stdout, bestandskoppelingen, netwerkkoppelingen, GPU-toegang en meer.

Zie de WSL-container-API-referentie voor het volledige API-oppervlak in de C-, C#- en C++-projecties.

De API installeren

De WSL-container-API wordt geleverd in het Microsoft.WSL.Containers NuGet-pakket, dat zowel de C#-projectie als de C++/WinRT-headers biedt.

C#

Voeg het pakket toe aan uw project met de .NET CLI:

dotnet add package Microsoft.WSL.Containers

Importeer vervolgens de naamruimte in uw code:

using Microsoft.WSL.Containers;

C++

Voeg het Microsoft.WSL.Containers NuGet-pakket toe aan uw C++/WinRT-project, neem vervolgens de geprojecteerde header op en breng de naamruimte binnen het bereik:

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

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

Note

De C++/WinRT-projection is een previewversie en kan ingrijpend worden gewijzigd.

API-overzicht

De API is georganiseerd rond een beperkt aantal objecten die de levenscyclus van een draaiende container weerspiegelen:

Object	Description
WslcService	Statisch toegangspunt voor bewerkingen op serviceniveau. Gebruik deze om te controleren of de vereiste WSL-onderdelen zijn geïnstalleerd, een query uitvoeren op de serviceversie en ontbrekende afhankelijkheden installeren.
Session	Een op WSL gebaseerde host waarop uw containers worden uitgevoerd. Een sessie beheert images (pullen, importeren, laden, pushen, taggen, verwijderen) en maakt containers.
Container	Een container die in een sessie is gemaakt. Gebruik deze om de container te starten, stoppen, inspecteren en verwijderen en om extra processen erin uit te voeren.
Process	Een Linux-proces dat wordt uitgevoerd in een container. Gebruik dit om te lezen stdout/stderr, naar stdin te schrijven, signalen te verzenden en afsluitcodes via gebeurtenissen te observeren.

Een gebruikelijke werkwijze is: controleren of aan de vereisten is voldaan met WslcService, een Session maken en starten, een installatiekopie ophalen, een Container configureren en maken, deze vervolgens starten en communiceren met de bijbehorende Process-objecten.

Voorbeeldfragmenten

In de onderstaande fragmenten ziet u dezelfde kernbouwstenen in elke ondersteunde taal. Gebruik de tabbladen om te schakelen tussen C# en C++.

C#

Controleer of de vereiste onderdelen zijn geïnstalleerd:

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

Een sessie maken en starten:

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

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

Een afbeelding ophalen met voortgangsrapportage:

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;

Maak een container, voer een opdracht uit en lees de uitvoer:

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

Wanneer u klaar bent, stopt en verwijdert u de container en beëindigt u vervolgens de sessie om resources vrij te geven:

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

C++

Deze fragmenten maken gebruik van C++/WinRT. De asynchrone aanroepen maken gebruik van co_await, dus ze moeten in een coroutine worden uitgevoerd.

Controleer of de vereiste onderdelen zijn geïnstalleerd:

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

Een sessie maken en starten:

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

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

Een afbeelding ophalen met voortgangsrapportage:

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;

Maak een container, voer een opdracht uit en lees de uitvoer:

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

Wanneer u klaar bent, stopt en verwijdert u de container en beëindigt u vervolgens de sessie om resources vrij te geven:

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

Volledige voorbeelden van begin tot eind

In de bovenstaande fragmenten ziet u de belangrijkste bouwstenen. Zie de stdin voor volledige, uitvoerbare voorbeelden waarin de volledige levenscyclus van containers, imagebeheer, poorttoewijzingen, volumekoppelingen, GPU-toegang en interactieve /stdout streaming aan bod komen.