WSL Containers SDK 的 ProcessOutputHandle 枚举：以 C 甄别容器进程的 stdout 与 stderr

WSL Containers SDK 的 ProcessOutputHandle 枚举：以 C# 甄别容器进程的 stdout 与 stderr

【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL

ProcessOutputHandle 是 WSL（Windows Subsystem for Linux）容器 SDK（Microsoft.WSL.Containers）中用于显式指定进程输出通道的核心枚举：它把 Linux 容器进程的"标准输出（stdout）"与"标准错误（stderr）"建模为两个可独立获取的句柄，配合Process.GetOutputStream()即可在宿主侧以 WinRT 流的方式读取容器内进程的输出。本文将围绕该枚举的取值、与ProcessOutputMode的配合关系、C# 侧完整用法以及仓库源码级的底层实现逐一展开，帮助你写出健壮、可复用的容器进程 I/O 处理代码。

ProcessOutputHandle 枚举定义

ProcessOutputHandle属于 WSL 容器 SDK 的 C#（WinRT 投影）API，定义在 doc/docs/api-reference/csharp/enumerations/processoutputhandle.md：

public enum ProcessOutputHandle { StandardOutput = 1, StandardError = 2 }

语义要点如下：

• 该枚举只建模 stdout 与 stderr 两个输出方向；标准输入（stdin）不在其中，而是通过Process.GetInputStream()单独访问。
• 枚举值采用 1 和 2 两个显式数值，不包含 0。这是因为底层WslcProcessIOHandle原生枚举中 0 被保留给 stdin（见下文"源码实现"），对外只暴露输出方向的句柄更符合该 SDK 的职责划分。

输出通道与输出模式的配合：ProcessOutputMode

ProcessOutputHandle本身只是"选择哪条输出通道"的标识，真正决定"如何拿到输出"的是配套的ProcessOutputMode枚举（见 doc/docs/api-reference/csharp/enumerations/processoutputmode.md）：

public enum ProcessOutputMode { Discard = 0, // 丢弃输出，仅保留进程运行 Stream = 1, // 允许通过 GetOutputStream(ProcessOutputHandle) 流式读取 Event = 2 // 允许订阅 OutputReceived / ErrorReceived 事件 }

两者在Process与ProcessSettings上的约束关系（来自 doc/docs/api-reference/csharp/core-classes/process.md 与 doc/docs/api-reference/csharp/settings-classes/processsettings.md）：

ProcessSettings.OutputMode在创建进程前配置：

var processSettings = new ProcessSettings { WorkingDirectory = "/workspace", CommandLine = new List<string> { "/bin/sh", "-c", "env | sort" }, EnvironmentVariables = new Dictionary<string, string> { ["DEMO"] = "1", ["PATH"] = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }, OutputMode = ProcessOutputMode.Event };

若模式与读取方式不匹配，SDK 会直接抛出E_ILLEGAL_METHOD_CALL（hresult_illegal_method_call），例如在Discard/Event模式下调用GetOutputStream。这一点有源码与测试双重佐证，详见下文。

C# 实战：分别读取 stdout 与 stderr

流式读取（OutputMode.Stream）

当OutputMode = ProcessOutputMode.Stream时，用Process.GetOutputStream(ProcessOutputHandle.StandardOutput)获取标准输出流，用Process.GetOutputStream(ProcessOutputHandle.StandardError)获取标准错误流。返回类型为 WinRT 的IInputStream，可直接配合DataReader使用：

using Windows.Storage.Streams; using IInputStream stdout = process.GetOutputStream(ProcessOutputHandle.StandardOutput); using var reader = new DataReader(stdout); await reader.LoadAsync(4096); string text = reader.ReadString(reader.UnconsumedBufferLength); Console.WriteLine(text);

stderr 的读取方式完全相同，只需把枚举参数换成ProcessOutputHandle.StandardError。

事件式读取（OutputMode.Event）

当OutputMode = ProcessOutputMode.Event时，订阅事件并按需甄别数据来源：

using System.Text; process.OutputReceived += data => Console.Write(Encoding.UTF8.GetString(data)); process.ErrorReceived += data => Console.Error.Write(Encoding.UTF8.GetString(data));

事件回调携带的是UInt8[]原始字节，需按进程实际编码解码（上例按 UTF-8）。

标准输入：GetInputStream()

stdin 不属于ProcessOutputHandle的管辖范围，通过Process.GetInputStream()（返回IOutputStream）写入：

using Windows.Storage.Streams; using IOutputStream stdin = process.GetInputStream(); using var writer = new DataWriter(stdin); writer.WriteString("hello from C#\n"); await writer.StoreAsync(); await writer.FlushAsync();

值得注意：底层实现中 stdin 对应的句柄值是 0（WSLC_PROCESS_IO_HANDLE_STDIN = 0），这与ProcessOutputHandle从 1 开始编号的设计相互呼应——输出句柄从 1 起、输入句柄单独访问，避免了两者在 API 层面混淆。

容器 Init 进程与 Secondary 进程的差异

使用输出句柄前必须清楚进程的启动方式：

• Init 进程由Container.Start()启动，不在你手上调用Start()。若其OutputMode为Event或Stream，Container.Start()会自动请求 native attach（见 doc/docs/api-reference/csharp/core-classes/container.md 与 doc/docs/api-reference/csharp/known-gaps.md）。
• Secondary 进程由Container.CreateProcess(...)创建，需显式调用process.Start()后才会真正执行，GetOutputStream才能取到有效流。

从 doc/docs/api-reference/csharp/end-to-end-example.md 可以看到一个完整链路：先以ProcessOutputMode.Event配置 init 进程，再在container.Start()之前订阅OutputReceived与Exited，从而在容器启动后拿到输出并等待退出码：

var initProcSettings = new ProcessSettings { CommandLine = new[] { "/bin/echo", "Hello from WSL Container!" }, OutputMode = ProcessOutputMode.Event }; var containerSettings = new ContainerSettings("alpine:latest") { Name = "hello-container", InitProcess = initProcSettings }; var container = session.CreateContainer(containerSettings); var exited = new TaskCompletionSource<int>(TaskCreationOptions.RunContinuationsAsynchronously); container.InitProcess.OutputReceived += data => Console.Write(Encoding.UTF8.GetString(data)); container.InitProcess.Exited += code => exited.TrySetResult(code); container.Start(); var completed = await Task.WhenAny(exited.Task, Task.Delay(TimeSpan.FromSeconds(30))); int exitCode = completed == exited.Task ? exited.Task.Result : -1; Console.WriteLine($"Process exited with code: {exitCode}");

源码级实现：从 C# 枚举到原生句柄

WinRT IDL 中的声明

ProcessOutputHandle与ProcessOutputMode首先在 IDL 中声明（src/windows/WslcSDK/winrt/wslcsdk.idl）：

enum ProcessOutputHandle { StandardOutput = 1, StandardError = 2, }; enum ProcessOutputMode { Discard = 0, Stream = 1, Event = 2, };

Processruntimeclass 中与输出句柄相关的成员（同文件 wslcsdk.idl）：

runtimeclass Process : Windows.Foundation.IClosable { ... Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle outputHandle); Windows.Storage.Streams.IOutputStream GetInputStream(); ... event ProcessOutputHandler OutputReceived; event ProcessOutputHandler ErrorReceived; event ProcessExitHandler Exited; };

WinRT 投影实现：模式校验与句柄获取

在 src/windows/WslcSDK/winrt/Process.cpp 中，GetOutputStream的实现清晰呈现了"模式校验 + 原生句柄转换"的逻辑：

winrt::Windows::Storage::Streams::IInputStream Process::GetOutputStream( winrt::Microsoft::WSL::Containers::ProcessOutputHandle const& outputHandle) { if (m_outputMode != ProcessOutputMode::Stream) { throw winrt::hresult_illegal_method_call(L"GetOutputStream requires OutputMode::Stream"); } wil::unique_handle handle; winrt::check_hresult(WslcGetProcessIOHandle(ToHandle(), static_cast<WslcProcessIOHandle>(outputHandle), handle.put())); return winrt::make<IOHandleInputStream>(std::move(handle)); } winrt::Windows::Storage::Streams::IOutputStream Process::GetInputStream() { wil::unique_handle handle; winrt::check_hresult(WslcGetProcessIOHandle(ToHandle(), WSLC_PROCESS_IO_HANDLE_STDIN, handle.put())); return winrt::make<IOHandleOutputStream>(std::move(handle)); }

对应地，OutputReceived/ErrorReceived事件要求m_outputMode == ProcessOutputMode::Event，否则同样抛出hresult_illegal_method_call（见 Process.cpp）。

底层原生枚举与句柄映射

ProcessOutputHandle直接对映 SDK 原生枚举WslcProcessIOHandle（src/windows/WslcSDK/wslcsdk.h）：

typedef enum WslcProcessIOHandle { WSLC_PROCESS_IO_HANDLE_STDIN = 0, WSLC_PROCESS_IO_HANDLE_STDOUT = 1, WSLC_PROCESS_IO_HANDLE_STDERR = 2 } WslcProcessIOHandle;

可以看到StandardOutput = 1与WSLC_PROCESS_IO_HANDLE_STDOUT = 1、StandardError = 2与WSLC_PROCESS_IO_HANDLE_STDERR = 2完全一致——C# 层的枚举值是原生句柄号的直接透传。WslcGetProcessIOHandle则由 src/windows/WslcSDK/wslcsdk.cpp 导出实现。

测试验证：正反用例覆盖

仓库的 SDK WinRT 测试 test/windows/WslcSdkWinRTTests.cpp 对ProcessOutputHandle给出了系统性的正反用例验证：

• 正常读取：通过GetOutputStream(ProcessOutputHandle::StandardOutput)与StandardError分别读取进程输出并断言内容（WslcSdkWinRTTests.cpp）。
• 模式不匹配即抛错：在Discard模式下调用GetOutputStream会抛出ERROR_INVALID_STATE（WslcSdkWinRTTests.cpp）。
• 非法调用校验：多个用例验证在非Stream模式下调用GetOutputStream(StandardOutput/StandardError)抛出E_ILLEGAL_METHOD_CALL（WslcSdkWinRTTests.cpp、#L1257、#L1364-L1367）。

这些测试同时印证了上文的两个关键结论：一是ProcessOutputHandle只覆盖 stdout/stderr 两条输出通道；二是输出模式必须与读取 API 严格匹配，否则 SDK 会以异常形式快速失败，而不是静默返回错误数据。

常见问题与最佳实践

• 为什么没有StandardInput成员？因为 stdin 是"输入"而非"输出"，SDK 有意将输入通道独立为GetInputStream()，与ProcessOutputHandle的输出职责分离，使用时不要尝试在枚举中寻找 stdin。
• Discard模式下还能拿到退出码吗？可以。Process.ExitCode在进程退出后始终有效，Exited事件对所有输出模式均可用（见 doc/docs/api-reference/csharp/core-classes/process.md），输出模式的取舍只影响输出数据的获取方式。
• 何时选 Stream、何时选 Event？需要按需拉取（如对接自有的读取循环、控制背压）时选Stream+GetOutputStream；希望以回调方式即时消费、代码更简洁时选Event+OutputReceived/ErrorReceived；完全不需要输出时选Discard以节省资源。
• 尽量分别订阅/读取 stdout 与 stderr：借助ProcessOutputHandle区分两条通道，可在宿主侧把错误信息单独归档或染色显示，避免将程序输出与诊断信息混为一谈；若只要合并输出，可分别读取后在应用层拼接。

小结

ProcessOutputHandle是 WSL 容器 SDK 中体积小、职责明确的枚举：StandardOutput = 1、StandardError = 2，只覆盖输出通道，stdin 交由Process.GetInputStream()处理。它的实际价值体现在与ProcessOutputMode的组合使用中——Stream模式配合GetOutputStream(ProcessOutputHandle)拉取流、Event模式配合OutputReceived/ErrorReceived消费回调；模式不匹配时 SDK 会立即抛错。其枚举值直接映射底层WslcProcessIOHandle原生句柄号，且有完整的 WinRT 测试用例护航，值得在容器进程 I/O 编程中放心使用。

【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL