Session¶

Represents a WSL-backed container host session.

public sealed class Session : IDisposable
{
    public Session(SessionSettings settings);

    public event SessionTerminationHandler Terminated;
    public event ProcessCrashHandler ProcessCrashed;

    public void Start();
    public void Terminate();
    public Container CreateContainer(ContainerSettings containerSettings);
    public Container OpenContainer(string nameOrId, ProcessOutputMode initProcessOutputMode);
    public void PullImage(PullImageOptions options);
    public IAsyncActionWithProgress<ImageProgress> PullImageAsync(PullImageOptions options);
    public void ImportImage(string path, string imageName);
    public IAsyncActionWithProgress<ImageProgress> ImportImageAsync(string path, string imageName);
    public void LoadImage(string path);
    public IAsyncActionWithProgress<ImageProgress> LoadImageAsync(string path);
    public void PushImage(PushImageOptions options);
    public IAsyncActionWithProgress<ImageProgress> PushImageAsync(PushImageOptions options);
    public void DeleteImage(string nameOrId);
    public void TagImage(TagImageOptions options);
    public void CreateVhdVolume(VhdOptions options);
    public void DeleteVhdVolume(string name);
    public AuthenticateResult Authenticate(Uri serverAddress, string username, string password);
    public IReadOnlyList<ImageInfo> GetImages();
    public IReadOnlyList<NetworkInfo> GetNetworks();
    public NetworkInfo CreateNetwork(NetworkSettings settings);
    public void DeleteNetwork(string nameOrId);
    public void Dispose();
}

Session constructor¶

var session = new Session(sessionSettings);

Session.Start()¶

Starts the session VM and registers the internal termination wait.

session.Start();

Session.Terminate()¶

Terminates the session.

session.Terminate();

Session.CreateContainer(ContainerSettings)¶

Creates a container object owned by the session.

Container container = session.CreateContainer(containerSettings);

Session.OpenContainer(string, 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.

using Container container = session.OpenContainer(
    "demo-container",
    ProcessOutputMode.Event);

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

try
{
    using Container container = session.OpenContainer("demo", ProcessOutputMode.Event);
}
catch (Exception exception) when (exception.HResult == (int)Error.ContainerNotFound)
{
    Console.WriteLine("Container not found.");
}

Session.PullImage(PullImageOptions)¶

Synchronous image pull.

session.PullImage(new PullImageOptions("docker.io/library/alpine:latest"));

Session.PullImageAsync(PullImageOptions)¶

Awaitable pull with progress.

var pull = session.PullImageAsync(new PullImageOptions("docker.io/library/alpine:latest"));
pull.Progress = (op, progress) =>
    Console.WriteLine($"pull: {progress.Status} {progress.Id} {progress.CurrentBytes}/{progress.TotalBytes}");
await pull;

Session.ImportImage(string path, string imageName)¶

Synchronous image import from a file path.

session.ImportImage(@"C:\images\demo.tar", "demo:imported");

Session.ImportImageAsync(string path, string imageName)¶

Imports an image tarball from a file path.

var importOp = session.ImportImageAsync(@"C:\images\demo.tar", "demo:imported");
importOp.Progress = (op, progress) =>
    Console.WriteLine($"import: {progress.Status} {progress.Id}");
await importOp;

Session.LoadImage(string path)¶

Synchronous image load from disk.

session.LoadImage(@"C:\images\docker-save.tar");

Session.LoadImageAsync(string path)¶

Loads an image archive from disk.

var loadOp = session.LoadImageAsync(@"C:\images\docker-save.tar");
loadOp.Progress = (op, progress) =>
    Console.WriteLine($"load: {progress.Status} {progress.Id}");
await loadOp;

Session.PushImage(PushImageOptions)¶

Synchronous image push to a registry.

session.PushImage(new PushImageOptions("registry.example.com/demo:latest", authToken));

Session.PushImageAsync(PushImageOptions)¶

Pushes an image to a registry.

var pushOp = session.PushImageAsync(new PushImageOptions("registry.example.com/demo:latest", authToken));
pushOp.Progress = (op, progress) =>
    Console.WriteLine($"push: {progress.Status} {progress.Id}");
await pushOp;

Session.DeleteImage(string nameOrId)¶

Deletes an image by name or ID.

session.DeleteImage("demo:old");

Session.TagImage(TagImageOptions)¶

Applies a new repository/tag to an existing image.

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

Session.CreateVhdVolume(VhdOptions)¶

Creates a named session VHD volume.

var vhd = new VhdOptions("cache", 2UL * 1024 * 1024 * 1024, VhdType.Dynamic)
{
    Owner = new VhdOwner { Uid = 1000, Gid = 1000 }
};
session.CreateVhdVolume(vhd);

Session.DeleteVhdVolume(string name)¶

Deletes a named session VHD volume.

session.DeleteVhdVolume("cache");

Session.Authenticate(Uri, string, string)¶

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

AuthenticateResult authentication = session.Authenticate(
    new Uri("https://registry.example.com"),
    "user1",
    "password");

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

Session.GetImages()¶

Returns a snapshot of images known to the session.

foreach (var image in session.GetImages())
{
    Console.WriteLine(image.Name);
}

Session.GetNetworks()¶

Returns a snapshot of networks in the session.

foreach (var network in session.GetNetworks())
{
    Console.WriteLine($"{network.Name} ({network.Driver})");
}

Session.CreateNetwork(NetworkSettings settings)¶

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.

var network = session.CreateNetwork(new NetworkSettings("backend"));

Session.DeleteNetwork(string nameOrId)¶

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

Session.Terminated event¶

Raised when the session termination event is signaled.

session.Terminated += reason =>
    Console.WriteLine($"Session terminated: {reason}");

Session.ProcessCrashed event¶

Raised when a process crash dump is reported.

session.ProcessCrashed += information =>
    Console.WriteLine($"Process crashed: {information.ProcessName} ({information.Pid})");

Session.Dispose()¶

Releases the underlying WinRT session object.

session.Dispose();