Definition for SDK projection / object model by florelis · Pull Request #40121 · microsoft/WSL

florelis · 2026-04-06T21:00:20Z

This is a proposal for a projection / object model for the SDK API, specifically intended for the C# projection.

It is written in MIDL 3, which means it represents a WinRT interface, but everything maps directly to C# so it should still allow us to talk about the design of the interface.

This is more or less a direct translation of the C header.

Mapped all the structs to classes.
Mapped the settings/options types that had required fields to classes with a single constructor taking the required fields, exposing them as read-only, and everything else as a settable property.
Mapped the creation of the main objects (like Session) to a static Create() factory method to avoid having constructors that may throw (and in case we ever want to have an async variant).
Mapped the handles used for loading an image to use an input stream type, based on what I understood of how it's used.
Removed the Release() functions.
Replaced the handle for the exit event by using an actual event.
Split WslcGetProcessIOHandle() into two functions to be able to return properly typed input/output streams.
Removed the error message out parameters, as the language supports exceptions.

This interface could be implemented in C++ as WinRT, and then using CsWinRT we can get a pretty natural C# projection with no or minimal changes. That would allow us to not have to deal with raw pointers and having to pin data from C#.

Copilot

Pull request overview

Adds a proposed WinRT (MIDL 3) object model for the WSLC SDK intended to enable a natural C# projection (e.g., via CsWinRT) without raw pointers/handles.

Changes:

Introduces a new WinRT IDL describing Sessions, Containers, Processes, and related settings/options types as runtimeclasses/enums/delegates.
Replaces several handle/callback-style patterns with WinRT-friendly constructs (streams, events/delegates, factory methods).
Defines supporting types for install/version reporting and image progress reporting.

src/windows/WslcSDK/wslcsdk-winrt.idl

florelis · 2026-04-06T21:05:25Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        Crashed = 2,
+    };
+
+    delegate void SessionTerminationHandler(Session session, SessionTerminationReason reason);


I changed "Callback" to "Handler" because I think that's more idiomatic in C#

florelis · 2026-04-06T21:09:58Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        void PullImage(PullImageOptions options);
+
+        // C# equivalent type: System.IO.StreamReader
+        void ImportImage(String imageName, Windows.Storage.Streams.IInputStream imageStream, ImportImageOptions options);


The C API uses a HANDLE for the image content. I changed it to a stream based on what I understood from how it's used, but I may be wrong.

florelis · 2026-04-06T21:11:56Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        UInt16 ContainerPort { get; };
+        PortProtocol Protocol { get; };
+
+        // TODO sockaddr_storage* WindowsAddress { get; set; };


This one I didn't know how to map, so I left it as a TODO for now.

florelis · 2026-04-06T21:13:58Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        IVector<String> CmdLine { get; set; };
+        // C# equivalent type: System.Collections.Specialized.StringDictionary
+        // C# projected type: System.Collections.Generic.IDictionary<string,string?>
+        IMap<String, String> EnvironmentVariables { get; set; };


This is an array of strings in the C API. I changed it to match the C# Process type.

florelis · 2026-04-06T21:16:58Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        // C# equivalent Windowstype: System.IO.StreamReader
+        Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle ioHandle);
+        // C# type: System.IO.StreamWriter
+        Windows.Storage.Streams.IOutputStream GetInputStream();


These are a single function in the C API. For WinRT there is no generic Stream type that can do both AFAICT, but if we do direct C# implementation it can be a System.IO.Stream and a single function to match.

florelis · 2026-04-06T21:18:48Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        // C# equivalent type: System.Collections.Specialized.StringDictionary
+        // C# projected type: System.Collections.Generic.IDictionary<string,string?>


C# equivalent type: What we could use if we define it in C# directly.
C# projected type: What we would get if we use CsWinRT to get a projection from the .idl.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 8 comments.

Copilot · 2026-04-07T22:14:19Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+
+        UInt32 CpuCount { get; set; };
+        UInt32 MemoryMb { get; set; };
+        UInt32 TimeoutMS { get; set; };


TimeoutMS uses a different casing convention than the other properties (MemoryMb, CpuCount). For C# projections this will surface as an awkward TimeoutMS property name. Consider using consistent PascalCase with standard abbreviations (e.g., TimeoutMs) to align with the rest of this IDL and typical .NET naming.

Suggested change

UInt32 TimeoutMS { get; set; };

UInt32 TimeoutMs { get; set; };

Copilot · 2026-04-07T22:14:19Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+    runtimeclass RegistryAuthenticationInformation
+    {
+        // TBD
+        String Placeholder {get; set;};


RegistryAuthenticationInformation currently exposes a Placeholder property. If this IDL is intended to be a public SDK surface, shipping a placeholder member is likely to become a breaking-change trap when real auth fields are introduced. Consider either omitting AuthInfo until the shape is defined, or defining a minimal but real contract (e.g., auth scheme + token/username/password) now.

Suggested change

runtimeclass RegistryAuthenticationInformation

{

// TBD

String Placeholder {get; set;};

enum RegistryAuthenticationScheme

{

None = 0,

Basic = 1,

BearerToken = 2,

};

runtimeclass RegistryAuthenticationInformation

{

RegistryAuthenticationScheme Scheme { get; set; };

String Username { get; set; };

String Password { get; set; };

String Token { get; set; };

Copilot · 2026-04-07T22:14:20Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        // C# projected type: System.Collections.Generic.IDictionary<string,string?>
+        IMap<String, String> EnvironmentVariables { get; set; };
+        ProcessEventHandlers EventHandlers { get; set; };
+    };


The API exposes both callback-style process I/O (ProcessSettings.EventHandlers) and stream-style I/O (Process.GetOutputStream/GetInputStream). In the existing C SDK these are mutually exclusive (callbacks consume the stdio handles), so the WinRT surface should either enforce the same exclusivity (fail fast if streams are requested when handlers are set) or clearly document which takes precedence to avoid surprising runtime failures.

Copilot · 2026-04-07T22:14:20Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        void PullImage(PullImageOptions options);
+
+        // C# type: System.IO.Stream
+        void ImportImage(String imageName, Windows.Storage.Streams.IInputStream imageStream, ImportImageOptions options);


ImportImage only takes an IInputStream, but the underlying WSLC APIs require a content length (COM IWSLCSession::ImportImage takes ContentLength). IInputStream doesn’t reliably expose length, so implementations may be forced to buffer the entire stream. Consider using a size-bearing WinRT type (e.g., IRandomAccessStream/IRandomAccessStreamReference) or add an explicit UInt64 contentLength parameter.

Suggested change

void ImportImage(String imageName, Windows.Storage.Streams.IInputStream imageStream, ImportImageOptions options);

void ImportImage(String imageName, Windows.Storage.Streams.IInputStream imageStream, UInt64 contentLength, ImportImageOptions options);

Copilot · 2026-04-07T22:14:20Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        void ImportImageFromFile(String imageName, String path, ImportImageOptions options);
+
+        // C# type: System.IO.Stream
+        void LoadImage(Windows.Storage.Streams.IInputStream imageStream, LoadImageOptions options);


LoadImage only takes an IInputStream, but the underlying WSLC APIs require a content length (COM IWSLCSession::LoadImage takes ContentLength). IInputStream doesn’t reliably expose length, so implementations may be forced to buffer the entire stream. Consider using a size-bearing WinRT type (e.g., IRandomAccessStream/IRandomAccessStreamReference) or add an explicit UInt64 contentLength parameter.

Suggested change

void LoadImage(Windows.Storage.Streams.IInputStream imageStream, LoadImageOptions options);

void LoadImage(Windows.Storage.Streams.IInputStream imageStream, UInt64 contentLength, LoadImageOptions options);

Copilot · 2026-04-07T22:14:20Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        // C# type: System.IO.Stream
+        Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle ioHandle);
+        // C# type: System.IO.Stream


The comments indicate these methods project to System.IO.Stream, but the WinRT signatures return IInputStream/IOutputStream. Unless your projection layer adds custom adapters, CsWinRT will surface WinRT stream interfaces here, so the comment may be inaccurate. Consider clarifying in the comment how .NET callers should obtain a Stream (or adjust the API surface accordingly).

Suggested change

// C# type: System.IO.Stream

Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle ioHandle);

// C# type: System.IO.Stream

// C# projected type: Windows.Storage.Streams.IInputStream

// .NET callers can adapt this to System.IO.Stream using the standard WinRT stream extension methods if needed.

Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle ioHandle);

// C# projected type: Windows.Storage.Streams.IOutputStream

// .NET callers can adapt this to System.IO.Stream using the standard WinRT stream extension methods if needed.

Copilot · 2026-04-07T22:14:20Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+        Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle ioHandle);
+        // C# type: System.IO.Stream
+        Windows.Storage.Streams.IOutputStream GetInputStream();


GetOutputStream returns an IInputStream (read end) and GetInputStream returns an IOutputStream (write end). The names are easy to misread as “stream you write output to” vs “stream you read input from”. Consider renaming to make direction explicit (e.g., GetStdOutStream/GetStdErrStream/GetStdInStream) so callers don’t accidentally invert read/write usage.

Suggested change

Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle ioHandle);

// C# type: System.IO.Stream

Windows.Storage.Streams.IOutputStream GetInputStream();

Windows.Storage.Streams.IInputStream GetStandardIoOutputReader(ProcessOutputHandle ioHandle);

// C# type: System.IO.Stream

Windows.Storage.Streams.IOutputStream GetStandardInputWriter();

Copilot · 2026-04-07T22:14:21Z

src/windows/WslcSDK/wslcsdk-winrt.idl

+
+Module Name:
+
+    wslcsdk.idl


Header comment has Module Name: wslcsdk.idl, but the file is wslcsdk-winrt.idl. Consider updating the module name to match the actual filename to avoid confusion when this is referenced in build/scripts.

Suggested change

wslcsdk.idl

wslcsdk-winrt.idl

Add IDL for SDK

8b32339

Copilot AI review requested due to automatic review settings April 6, 2026 21:00

Copilot started reviewing on behalf of florelis April 6, 2026 21:01 View session

Copilot AI reviewed Apr 6, 2026

View reviewed changes

florelis commented Apr 6, 2026

View reviewed changes

Typos and Copilot feedback

a40f54d

florelis requested a review from Copilot April 7, 2026 22:08

Copilot started reviewing on behalf of florelis April 7, 2026 22:08 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

		// C# equivalent type: System.Collections.Specialized.StringDictionary
		// C# projected type: System.Collections.Generic.IDictionary<string,string?>

	UInt32 TimeoutMS { get; set; };
	UInt32 TimeoutMs { get; set; };

-    runtimeclass RegistryAuthenticationInformation
-    {
-        // TBD
-        String Placeholder {get; set;};
+    enum RegistryAuthenticationScheme
+    {
+        None = 0,
+        Basic = 1,
+        BearerToken = 2,
+    };
+    runtimeclass RegistryAuthenticationInformation
+    {
+        RegistryAuthenticationScheme Scheme { get; set; };
+        String Username { get; set; };
+        String Password { get; set; };
+        String Token { get; set; };

	void ImportImage(String imageName, Windows.Storage.Streams.IInputStream imageStream, ImportImageOptions options);
	void ImportImage(String imageName, Windows.Storage.Streams.IInputStream imageStream, UInt64 contentLength, ImportImageOptions options);

	void LoadImage(Windows.Storage.Streams.IInputStream imageStream, LoadImageOptions options);
	void LoadImage(Windows.Storage.Streams.IInputStream imageStream, UInt64 contentLength, LoadImageOptions options);

Conversation

florelis commented Apr 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

florelis Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

florelis Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

florelis Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

florelis Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

florelis Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

florelis Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants