microsoft / microsoft/WSL

wslc: expose container lifecycle events in Microsoft.WSL.Containers

Open
#41,624 1 comment 0 reactions 0 assignees View on GitHub
feature wslc
Dominant language
C++
Stars
33.7k
Forks
1.8k
Avg merge
3d 17h
Merged PRs (30d)
116

Description

**Is your feature request related to a problem? Please describe.**

WSLC already has a Docker-style container event stream through the underlying COM API added in #40971:

* `IWSLCSession::GetEvents`
* `IWSLCEventStream::GetNext`

The same functionality is also available from the CLI through `wslc events`.

However, it doesn't appear to be exposed through the public `Microsoft.WSL.Containers` C#/WinRT API.

As of the 2.9.12 prerelease, the public `Session` API exposes events such as `Terminated` and `ProcessCrashed`, but there is no supported way to subscribe to container lifecycle events such as:

* `create`
* `start`
* `kill`
* `stop`
* `destroy`

For an application using the SDK directly, this means container state has to be refreshed by polling even though WSLC already has the underlying event stream.

My use case is a desktop container manager. Ideally it would take an initial snapshot of the containers, apply lifecycle events as incremental updates, and occasionally reconcile the full state in case an event was missed or the stream had to reconnect.

Without an events API in the public SDK, the alternatives are polling or launching `wslc events` as a separate process.

**Describe the solution you'd like**

Expose the existing container event stream through `Microsoft.WSL.Containers`.

It doesn't necessarily need to mirror the COM API exactly, but it would be useful to expose the same basic capabilities:

* container lifecycle events;
* `since` / `until` ranges;
* event filters;
* an asynchronous way to consume events;
* cancellation / disposal;
* a way to detect lost events and the end of the stream.

For example, conceptually:

```csharp
var stream = session.GetEvents(options);

while (true)
{
var containerEvent = await stream.GetNextAsync();
// Update the affected container.
}
```

An event-based API or an async-stream-style API would work as well. I'm mainly looking for a supported public API for the event stream that already exists underneath the SDK.

It would also be useful if the public API preserved equivalents of the existing `WSLC_E_EVENTS_LOST` and `WSLC_E_EVENT_STREAM_FINISHED` conditions so callers can reconcile state or stop reading as appropriate.

**Describe alternatives you've considered**

**Polling container state**

Periodically refresh the container list or inspect individual containers.

This works, but adds unnecessary polling and makes UI updates less immediate.

**Invoking `wslc events`**

Launch the CLI and parse its output.

This provides the information, but adds an extra process and parsing/lifetime management for functionality that already exists in WSLC.

**Using the underlying COM API directly**

`IWSLCSession::GetEvents` already exposes the functionality, but relying on the underlying COM interface directly doesn't seem like a good long-term dependency for a third-party application.

**Additional context**

The underlying event-stream implementation was added in #40971, so this request is mainly about making that capability available through the supported `Microsoft.WSL.Containers` API.

This would be useful for desktop container managers, IDE integrations, monitoring tools, and other SDK consumers that need to react to container state changes in real time.

I'd be happy to contribute an implementation once the preferred public API shape is agreed on.

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing IWSLCSession::GetEvents and IWSLCEventStream::GetNext interfaces from #40971, then inspect the public Microsoft.WSL.Containers Session API and the wslc events entry point. Define and expose a supported asynchronous event-stream API with lifecycle events, filtering, cancellation or disposal, and equivalents for lost or finished streams; add coverage for the public API behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, csharp
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.