Contentor WSL

A funcionalidade do contentor WSL tem dois componentes principais: uma CLI chamada wslc.exe para construir, executar e interagir com contentores Linux e uma API de contentores WSL que permite aos programadores de aplicações Windows usar contentores Linux como parte da lógica da sua aplicação.

Importante

A funcionalidade do contentor WSL requer a versão WSL 2.9.3 ou superior. Esta versão está atualmente disponível apenas como pré-lançamento, por isso precisa de a instalar abrindo o PowerShell e inserindo:

wsl --update --pre-release

Verifique a sua versão instalada a qualquer momento com wsl --version.

CLI de contentores do WSL

O WSL inclui wslc.exe agora como um binário incorporado. O seu objetivo é ter uma interface CLI familiar, permitindo-lhe construir, executar e interagir facilmente com contentores Linux.

Veja alguns dos comandos de exemplo abaixo:

# 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

Pode saber mais sobre como começar com esta funcionalidade no nosso tutorial de contentores.

API de contentores WSL

As aplicações Windows também podem utilizar contentores Linux! O pacote NuGet da API de contentores WSL permite-lhe puxar, executar e interagir programaticamente com containers Linux, incluindo interações chave como stdin e stdout, montagens de ficheiros, montagens de rede, acesso à GPU e mais.

Para a superfície completa da API nas projeções de C, C# e C++, consulte a referência da API do contentor WSL.

Instalar a API

A API de contentores WSL é incluída no Microsoft.WSL.Containers pacote NuGet, que fornece tanto a projeção C# como os cabeçalhos C++/WinRT.

C#

Adicione o pacote ao seu projeto com a CLI .NET:

dotnet add package Microsoft.WSL.Containers

Depois importa o namespace no teu código:

using Microsoft.WSL.Containers;

C++

Adicione o Microsoft.WSL.Containers pacote NuGet ao seu projeto C++/WinRT, depois inclua o cabeçalho projetado e traga o namespace para o âmbito:

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

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

Note

A projeção C++/WinRT está em pré-visualização e está sujeita a alterações variadas.

Visão geral da API

A API está organizada em torno de um pequeno conjunto de objetos que espelham o ciclo de vida da execução de um contentor:

Objeto	Description
WslcService	Ponto de entrada estático para operações de nível de serviço. Utilize-o para verificar se os componentes WSL necessários estão instalados, consultar a versão do serviço e instalar dependências em falta.
Session	Um host apoiado por WSL que executa os teus containers. Uma sessão gere imagens (puxar, importar, carregar, empurrar, etiquetar, eliminar) e cria contentores.
Container	Um contentor criado dentro de uma sessão. Use-o para iniciar, parar, inspecionar e eliminar o contentor, e para executar processos adicionais dentro dele.
Process	Um processo Linux a correr num contentor. Use-o para ler stdout/stderr, escrever para stdin, enviar sinais e observar códigos de saída através de eventos.

Um fluxo típico é: verificar os pré-requisitos com WslcService, criar e iniciar um Session, obter uma imagem, configurar e criar um Container, depois iniciá-lo e interagir com os respetivos objetos Process.

Exemplos de excertos

Os excertos abaixo mostram os mesmos blocos de construção essenciais em cada linguagem suportada. Utiliza os separadores para mudar entre C# e C++.

C#

Verifique se os componentes necessários estão instalados:

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

Crie e inicie uma sessão:

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

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

Obtenha uma imagem com indicação do progresso:

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;

Crie um contentor, execute um comando e leia a sua saída:

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

Quando terminares, para e apaga o contentor, depois termina a sessão para libertar recursos:

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

C++

Estes excertos usam C++/WinRT. As chamadas assíncronas usam co_await, pelo que devem ser executadas numa corrotina.

Verifique se os componentes necessários estão instalados:

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

Crie e inicie uma sessão:

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

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

Obtenha uma imagem com indicação do progresso:

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;

Crie um contentor, execute um comando e leia a sua saída:

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

Quando terminares, para e apaga o contentor, depois termina a sessão para libertar recursos:

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

Exemplos completos de ponta a ponta

Os excertos acima mostram os blocos de construção essenciais. Para exemplos completos e executáveis que abrangem todo o ciclo de vida do contentor, gestão de imagens, mapeamentos de portas, montagens de volume, acesso à GPU e streaming interativo stdin/stdout , consulte os exemplos da API do contentor WSL.