WSL Container SDK C 枚举详解SessionTerminationReason 的取值、事件通知与 C API 映射【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSLSessionTerminationReason 是 WSLWindows Subsystem for Linux容器 SDKWSLCWinRT 投影中用于描述会话为何结束的枚举它由 C API 层的WslcSessionTerminationReason直接转换而来并通过Session.Terminated事件暴露给 C/WinRT 调用方。阅读本文后你将掌握该枚举的每个取值含义、它与底层 C 枚举的数值对应关系、Terminated事件从线程池等待到回调触发的完整链路以及如何结合测试用例验证Shutdown/Crashed等不同终止场景。枚举定义与三个取值在 C/WinRT 命名空间Microsoft.WSL.Containers中SessionTerminationReason的取值与 C API 枚举WslcSessionTerminationReason的数值完全一致定义于 IDL 文件 wslcsdk.idlenum SessionTerminationReason { Unknown 0, Shutdown 1, Crashed 2, };对应的底层 C 枚举定义在 wslcsdk.htypedef enum WslcSessionTerminationReason { WSLC_SESSION_TERMINATION_REASON_UNKNOWN 0, WSLC_SESSION_TERMINATION_REASON_SHUTDOWN 1, WSLC_SESSION_TERMINATION_REASON_CRASHED 2, } WslcSessionTerminationReason;C 枚举值C 枚举值数值语义UnknownWSLC_SESSION_TERMINATION_REASON_UNKNOWN0未知/未确定的原因通常作为初始化默认值ShutdownWSLC_SESSION_TERMINATION_REASON_SHUTDOWN1会话被主动、优雅地关闭如调用WslcTerminateSession或WslcReleaseSessionCrashedWSLC_SESSION_TERMINATION_REASON_CRASHED2会话因异常如容器内进程崩溃而非正常退出从源码结构看Unknown0是所有查询类 API 的未初始化默认值在 wslcsdk.h 的调用约定中调用方通常先将 out 参数初始化为WSLC_SESSION_TERMINATION_REASON_UNKNOWN再传入WslcGetSessionTerminationReason获取真实原因。双重投影C API 与 WinRT 枚举如何衔接WSLC SDK 采用C 核心 API WinRT 投影的分层设计C 层是唯一的实现真相所有真实状态查询都通过WslcGetSessionTerminationReason(_In_ WslcSession session, _Out_ WslcSessionTerminationReason* reason)完成返回HRESULT原型见 wslcsdk.hWinRT 层Microsoft.WSL.Containers把该枚举直接转换directlystatic_cast为同名的SessionTerminationReason二者数值一一对应不存在重映射这正是 API 参考文档中Session::OnTerminatedconvertsWslcSessionTerminationReasondirectly to the WinRT enum这句话的含义。C 层的WslcGetSessionTerminationReason单独使用时形如WslcSessionTerminationReason reason WSLC_SESSION_TERMINATION_REASON_UNKNOWN; HRESULT hr WslcGetSessionTerminationReason(session, reason); if (SUCCEEDED(hr) reason WSLC_SESSION_TERMINATION_REASON_CRASHED) { // 会话崩溃 }该 C 接口的完整签名与参数说明可参考 wslcgetsessionterminationreason.md枚举值表见 wslcsessionterminationreason.md。使用方式订阅 Session.Terminated 事件在 C/WinRT 中推荐的做法是订阅Session对象的Terminated事件。该事件通过委托SessionTerminationHandler(SessionTerminationReason reason)回调定义于 wslcsdk.idl事件成员声明在 Session.hsession.Terminated([](SessionTerminationReason reason) { if (reason static_castSessionTerminationReason(2)) { // crashed } else if (reason SessionTerminationReason::Shutdown) { // 正常关闭 } });几点实践建议由于SessionTerminationReason与 C 枚举数值一一对应既可以使用枚举名SessionTerminationReason::Shutdown也可以像官方示例那样用static_castSessionTerminationReason(2)判断崩溃场景但从可读性出发优先使用枚举名事件订阅应在Session::Start()之后进行因为终止事件句柄是在Start()内部获取并注册的见下文底层机制事件是一次性的会话终止后不会再次触发订阅关系会随Session对象释放而清理。底层机制从终止事件句柄到 Terminated 回调Terminated事件并非简单的属性回调其背后是事件句柄 线程池等待的完整链路实现在 Session.cpp 中获取终止事件句柄Session::Start()创建底层会话后调用WslcGetSessionTerminationEvent取得一个内核事件句柄Session.cpp。该句柄由调用方持有即使后续释放会话仍保持有效注册线程池等待通过CreateThreadpoolWait(Session::OnTerminated, this, nullptr)创建线程池等待对象并用SetThreadpoolWait挂到终止事件上Session.cpp。这意味着会话终止通知是在 Windows 线程池线程上异步派发的不会阻塞调用方回调触发当会话终止、事件被置位时线程池调用静态回调Session::OnTerminated它先调用WslcGetSessionTerminationReason从 C 层读出真实原因再执行session-m_terminatedEvent(static_castSessionTerminationReason(reason))把枚举原样派发给所有订阅者Session.cpp清理Session::Close()会释放线程池等待对象与底层句柄final_release在引用计数归零时兜底调用Close()Session.cpp。从源码结构可以推断之所以在OnTerminated中先查询原因、再派发事件是为了让回调一次性携带准确的终止原因避免订阅者各自再查一次 C API。各取值的触发场景与测试验证仓库自带的 SDK 测试 WslcSdkTests.cpp 直接印证了各枚举值的触发场景Shutdown1—— 显式终止测试方法TerminationEventViaTerminateWslcSdkTests.cpp先创建会话并获取终止事件然后调用WslcTerminateSession触发优雅关闭等待事件置位后用WslcGetSessionTerminationReason断言原因恰为WSLC_SESSION_TERMINATION_REASON_SHUTDOWNShutdown1—— 释放句柄测试方法TerminationEventViaReleaseWslcSdkTests.cpp验证了调用WslcReleaseSession也会优雅关闭并置位终止事件同时证明终止事件句柄归调用方所有、在会话释放后依然有效Crashed2用于描述会话非正常结束如容器运行环境崩溃。值得注意的是一旦发生崩溃通常还会伴随WslcSessionCrashDumpInfo结构含 dumpPath、processName、pid、signal、timestamp见 wslcsdk.h可通过WslcRegisterSessionCrashDumpCallback注册的崩溃转储回调获取更详细的故障现场信息与Terminated事件形成互补。注意事项该 SDK 目前处于PREVIEW预览阶段wslcsdk.h 明确声明 API 可能在后续版本发生破坏性变更生产负载不应依赖其稳定性SessionTerminationReason的数值约束永远是 0、1、2 三者之一与 C 层枚举一一对应若底层返回其他值从代码看会被static_cast原样透传因此调用方应做好未知值的容错处理可参考Unknown 0的兜底语义判断终止原因时优先使用Terminated事件回调中携带的参数而非事件触发后再手动调用 C API避免竞态与重复查询相关枚举与接口的完整清单含ContainerState、ProcessState、Error、Signal等见 Enumerations 索引。【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考