Session

Represents a WSL-backed container host session.

Session constructor

The settings object must not be null.

Session session{ sessionSettings };

Session::Start()

Starts the session. Calling this method more than once throws an exception.

session.Start();

Session::Terminate()

Terminates the session.

session.Terminate();

Session::CreateContainer(ContainerSettings)

Creates a container object owned by the session.

auto container = session.CreateContainer(containerSettings);

Session::OpenContainer(hstring, ProcessOutputMode)

Opens an existing container by name, full ID, or unambiguous partial ID prefix. The output mode controls how the opened container's init-process I/O is exposed when it is started.

auto opened = session.OpenContainer(L"demo-container", ProcessOutputMode::Event);

The method throws a projected exception with Error::ContainerNotFound if no container matches or Error::ContainerPrefixAmbiguous if a partial ID is ambiguous.

Session::PullImage(PullImageOptions)

Pulls an image synchronously.

session.PullImage(PullImageOptions{ L"docker.io/library/alpine:latest" });

Session::PullImageAsync(PullImageOptions)

Pulls an image asynchronously and reports progress.

auto pullOp = session.PullImageAsync(PullImageOptions{ L"docker.io/library/alpine:latest" });
pullOp.Progress([](auto&&, ImageProgress const& progress)
{
    printf("pull status: %d\n", static_cast<int>(progress.Status()));
});
co_await pullOp;

Session::ImportImage(hstring, hstring)

Imports an image tarball synchronously from a file path.

session.ImportImage(L"C:\\images\\alpine.tar", L"demo/alpine:latest");

Session::ImportImageAsync(hstring, hstring)

Imports an image tarball asynchronously from a file path.

auto importOp = session.ImportImageAsync(L"C:\\images\\alpine.tar", L"demo/alpine:latest");
importOp.Progress([](auto&&, ImageProgress const& p) { /* progress */ });
co_await importOp;

Session::LoadImage(hstring)

Loads an image archive synchronously from a file path.

session.LoadImage(L"C:\\images\\bundle.tar");

Session::LoadImageAsync(hstring)

Loads an image archive asynchronously from a file path.

auto loadOp = session.LoadImageAsync(L"C:\\images\\bundle.tar");
co_await loadOp;

Session::PushImage(PushImageOptions)

Pushes an image synchronously to a registry.

session.PushImage(pushOptions);

Session::PushImageAsync(PushImageOptions)

Pushes an image asynchronously to a registry.

co_await session.PushImageAsync(pushOptions);

Session::DeleteImage(hstring)

Deletes an image by name or ID.

session.DeleteImage(L"demo/alpine:latest");

Session::TagImage(TagImageOptions)

Applies a new repository and tag to an existing image.

session.TagImage(TagImageOptions{ L"alpine:latest", L"registry.example.com/alpine", L"v1" });

Session::CreateVhdVolume(VhdOptions)

Creates a named session VHD volume.

session.CreateVhdVolume(vhdOptions);

Session::DeleteVhdVolume(hstring)

Deletes a named session VHD volume.

session.DeleteVhdVolume(L"build-cache");

Session::Authenticate(Uri, hstring, hstring)

Authenticates to a registry and returns registry authentication data suitable for PullImageOptions::RegistryAuth() or PushImageOptions::RegistryAuth().

auto authentication = session.Authenticate(
    winrt::Windows::Foundation::Uri{ L"https://registry.example.com" },
    L"user",
    L"password");

PullImageOptions authenticatedPull{ L"registry.example.com/demo:latest" };
authenticatedPull.RegistryAuth(authentication.IdentityToken());
session.PullImage(authenticatedPull);

Session::GetImages()

Returns a snapshot of images known to the session.

auto images = session.GetImages();
for (auto const& image : images)
{
    printf("%ws\n", image.Name().c_str());
}

Session::GetNetworks()

Returns a snapshot of networks in the session.

auto networks = session.GetNetworks();
for (auto const& network : networks)
{
    printf("%ws %ws\n", network.Name().c_str(), network.Driver().c_str());
}

Session::CreateNetwork(NetworkSettings)

Creates a bridge network in the session and returns it. Throws HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) if a network with the same name exists.

auto network = session.CreateNetwork(NetworkSettings{L"backend"});

Session::DeleteNetwork(hstring)

Deletes a network from the session by name, full ID, or unique ID prefix. An exact ID match takes precedence over a name match, and a name match takes precedence over an ID prefix match. Throws WSLC_E_NETWORK_NOT_FOUND if no network matches, or WSLC_E_NETWORK_PREFIX_AMBIGUOUS if an ID prefix matches more than one network.

session.DeleteNetwork(L"backend");

Session::Terminated event

Raised when the session termination event is signaled.

session.Terminated([](SessionTerminationReason reason)
{
    printf("session terminated: %d\n", static_cast<int>(reason));
});

Session::ProcessCrashed event

Raised when a process crash dump is reported.

session.ProcessCrashed([](ProcessCrashInformation const& information)
{
    printf("process crashed: %ws (%u)\n", information.ProcessName().c_str(), information.Pid());
});

Session::Close()

Releases the underlying WinRT session object.

session.Close();