0704fa160b
* Update WSLC SDK API documentation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update docs * Update docs * Quick fixes --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Craig Loewen <crloewen@microsoft.com>
4.5 KiB
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::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();