WSL C API 枚举类型完全指南Microsoft.WSL.Containers 与 Wslc C API 的数值契约与实战用法【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL本篇指南系统讲解 WSLWindows Subsystem for LinuxC API基于 C/WinRT 的Microsoft.WSL.Containers命名空间由 WslcSDK 提供中全部 13 个枚举类型。这些枚举贯穿容器生命周期管理、进程信号控制、端口映射、VHD 卷创建、镜像拉取进度回调、SDK 组件安装与错误码处理等核心场景。读完本文你将掌握每个枚举的精确数值、底层 C API 对应关系、典型代码写法以及源码级的设计意图可直接用于编写 WSL 容器管理工具。数值契约C 枚举与 C API 的直接对齐WSL C API 是底层 C API头文件 src/windows/WslcSDK/wslcsdk.h之上的一层 C/WinRT 封装。API 参考文档 index.md 在最开头就声明了一条贯穿所有枚举的核心约定For enums that are directlystatic_castto/from the C API, the numeric values match the correspondingWslc*enum inwslcsdk.h.即凡是直接与 C API 互相static_cast的 C 枚举其数值与wslcsdk.h中对应的Wslc*枚举逐字节一致。这意味着你可以在 C 与 C 两层 API 之间无损传递枚举值可以通过static_castWslcXxx(cppEnum)回传给 C API 函数阅读 src/windows/WslcSDK/wslcsdk.h 即可获得这些枚举最权威的定义与注释。该 SDK 的 C API 导出清单见 wslcsdk.def实现集中在 wslcsdk.cppC/WinRT 封装则位于 winrt 目录。文档树中每个枚举均有独立页面见 enumerations 目录下文按使用场景分组逐一展开。容器状态枚举ContainerState容器的五态生命周期Container::State()直接从 C API 的WslcContainerState强转而来。C 侧定义见 wslcsdk.h#L303-L310读取函数为WslcGetContainerState声明 wslcsdk.h#L312实现 wslcsdk.cpp#L1196。枚举值数值含义Invalid0无效状态Created1已创建Running2运行中Exited3已退出Deleted4已删除auto state container.State(); if (state static_castContainerState(2)) { // running }由于 C 枚举自带类型名实际更推荐直接比较具名值if (container.State() ContainerState::Running) { // 容器正在运行 }ProcessState进程的四态Process::State()从WslcProcessState强转而来。与容器状态不同进程多了一个Signalled被信号终止状态枚举值数值含义Unknown0未知Running1运行中Exited2已正常退出Signalled3被信号终止if (process.State() static_castProcessState(1)) { // running }SessionTerminationReason会话终止原因Session::OnTerminated事件把 C API 的WslcSessionTerminationReason直接转换为 WinRT 枚举C 侧定义见 wslcsdk.h#L126-L131对应查询函数WslcGetSessionTerminationReason见 wslcsdk.cpp#L598枚举值数值含义Unknown0未知原因Shutdown1正常关闭Crashed2崩溃session.Terminated([](SessionTerminationReason reason) { if (reason static_castSessionTerminationReason(2)) { // crashed —— 可在此收集崩溃转储或做日志上报 } });值得注意的是WSLC 还提供WslcSessionCrashDumpInfo结构与崩溃转储回调见 wslcsdk.h#L133-L144Crashed状态常与崩溃转储机制配合使用。操作参数枚举DeleteContainerOption删除容器的选项Container::Delete()接受DeleteContainerOption。C 侧对应WslcDeleteContainerFlagswslcsdk.h#L327-L331删除函数为WslcDeleteContainerwslcsdk.h#L335枚举值数值含义None0无附加选项Force1强制删除container.Delete(DeleteContainerOption::Force);Force选项常用于容器处于非正常状态、常规删除失败时的兜底操作。SignalLinux 信号枚举Container::Stop()与Process::Signal()都会把枚举直接强转为WslcSignalC 侧定义见 wslcsdk.h#L315-L323对应WslcStopContainer见 wslcsdk.cpp#L1219、WslcSignalProcess见 wslcsdk.cpp#L1370枚举值数值Linux 语义None0无信号保留给未来使用SIGHUP1挂断/重载SIGINT2中断Ctrl-CSIGQUIT3退出并产生 core dumpSIGKILL9立即终止SIGTERM15优雅关闭process.Signal(Signal::SIGINT); container.Stop(Signal::SIGTERM, std::chrono::seconds(10));从源码注释可以确认wslcsdk.h#L314-L323SIGKILL 是immediate termination、SIGTERM 是graceful shutdown。Container::Stop还接受超时参数C 侧timeoutSeconds为uint32_t用于控制等待优雅退出的最长时间。Process::Signal()的实现同样通过static_castWslcSignal(signal)传递见 Process.cpp#L186。PortProtocol端口映射协议ContainerPortMapping端口映射数据类文档见 containerportmapping.md使用PortProtocol指定协议。TCP是winrt_ContainerPortMapping.h中的默认值值会直接传递给 C 结构体WslcContainerPortMapping::protocol枚举值数值含义TCP0TCP默认UDP1UDPContainerPortMapping mapping{ 8080, 80, PortProtocol::TCP };上例表示将容器内 80 端口映射到宿主 8080 端口协议为 TCP。ContainerNetworkingMode容器网络模式ContainerSettings::NetworkingMode()接受ContainerNetworkingMode。C 侧定义见 wslcsdk.h#L85-L87其中注释明确None表示No networking / isolated无网络/隔离枚举值数值含义None0无网络隔离Bridged1桥接网络containerSettings.NetworkingMode(ContainerNetworkingMode::Bridged);API 文档特别提示winrt_ContainerSettings.cpp中显式校验的仅有None与Bridged两个取值。也就是说虽然底层 C 枚举未来可能扩展但当前 C/WinRT 设置层只接受这两个值其他值会在校验时被拒绝。VhdTypeVHD 卷类型VhdOptions::Type()设置卷类型。C 侧定义见 wslcsdk.h#L89-L93注释信息量很大枚举值数值含义Dynamic0动态扩展 VHDX默认Fixed1固定分配 VHDX仅WslcCreateSessionVhdVolume支持vhdOptions.Type(VhdType::Dynamic);关键注意点来自 wslcsdk.h#L91-L92Dynamic是默认且常规路径支持的扩容型 VHDX而Fixed预分配全部空间只被WslcCreateSessionVhdVolume这个创建卷的 API 支持在WslcSetSessionSettingsVhd这类设置接口中不生效。WinRT 层VhdOptions.cpp通过static_castWslcVhdType(m_type)传递该值VhdOptions.cpp#L102。进程 I/O 相关枚举ProcessOutputHandle输出流句柄Process::GetOutputStream(ProcessOutputHandle)接受以下取值用于获取进程的标准输出/标准错误流枚举值数值含义StandardOutput1标准输出stdoutStandardError2标准错误stderrauto stdoutStream process.GetOutputStream(ProcessOutputHandle::StandardOutput);底层 C API 使用更完整的WslcProcessIOHandle枚举见 wslcsdk.h#L348-L353STDIN 0、STDOUT 1、STDERR 2。C 层的ProcessOutputHandle只暴露读方向的 stdout/stderrstdin 走独立的写入通道。ProcessOutputMode输出处理模式ProcessSettings::OutputMode()决定进程 stdout/stderr 的投递方式这是进程 I/O 模型中最核心的枚举枚举值数值行为Discard0不产生任何 stdout/stderr 事件或输出流Stream1可通过GetOutputStream(...)主动拉取输出流Event2stdout/stderr 通过回调投递配合OutputReceived/ErrorReceived事件procSettings.OutputMode(ProcessOutputMode::Event);三种模式在 WinRT 实现层有严格的互斥校验见 Process.cpp模式为Stream时才允许调用GetOutputStream否则抛出hresult_illegal_method_callGetOutputStream requires OutputMode::StreamProcess.cpp#L191-L193模式为Event时才允许订阅OutputReceived否则同样抛出非法方法调用Process.cpp#L210-L212只有Event模式才会触发 I/O 回调Process.cpp#L46-L48。此外Container的初始化进程也有一个ProcessOutputMode参数见 Container.cpp#L37-L67用于决定容器 init 进程的 I/O 投递方式。安装与组件枚举Component缺失组件位掩码WslcService::GetMissingComponents()返回一个Component位掩码flags用按位或组合多个缺失组件。C 侧对应WslcComponentFlags定义与详细注释见 wslcsdk.h#L644-L654枚举值数值含义VirtualMachinePlatform1虚拟机平台可选功能安装后需要重启WslPackage2WSL 运行时包需能支撑 WSLC 的版本SdkNeedsUpdate4WSLC SDK 本身需要更新auto missing WslcService::GetMissingComponents(); if (missing ! static_castComponent(0)) { co_await WslcService::InstallWithDependenciesAsync(); }与 C API 的对应关系WslcGetMissingComponentswslcsdk.h#L658负责探测缺失组件WslcInstallWithDependencieswslcsdk.h#L682-L683负责按位掩码安装依赖——其注释明确callbacks 只会针对本次调用实际安装的组件触发。几个值得注意的源码细节VirtualMachinePlatform的注释指出其服务可能由其他可选功能提供且安装该组件需要重启系统——因此生产代码在探测到该位时应提示用户安排重启WslcInstallOptions中还有WSLC_INSTALL_OPTION_REPAIR 1wslcsdk.h#L671-L676允许重装组件对应修复场景位掩码类枚举在 C 侧通过DEFINE_ENUM_FLAG_OPERATORS启用了|、等位运算wslcsdk.h#L656。镜像进度枚举ImageProgressStatus拉取/导入镜像的阶段ImageProgress数据类的Status()直接从WslcImageProgressStatus强转而来。C 侧定义见 wslcsdk.h#L451-L460每个状态都对应 Docker 风格的进度字符串枚举值数值对应文案阶段Unknown0—未知Pulling1Pulling fs layer开始拉取文件系统层Waiting2Waiting等待Downloading3Downloading下载中Verifying4Verifying Checksum校验校验和Extracting5Extracting解压中Complete6Pull complete完成auto status progress.Status(); if (status static_castImageProgressStatus(6)) { // complete }C 层配套结构WslcImageProgressMessage携带id层 ID 或摘要、status与detail已下载/总字节数见 wslcsdk.h#L445-L467进度回调通过WslcPullSessionImage/WslcImportSessionImagewslcsdk.h#L481注册状态字符串到枚举的转换逻辑位于 ProgressCallback.cpp#L20 的ConvertStatus函数。这套枚举很适合驱动 UI 进度条与阶段文案。错误码枚举ErrorWSLC 专属 HRESULT 错误码Error枚举封装了 WSLC 层的自定义 HRESULT 错误码全部为负数失败从-2147219967连续排布到-2147219954即十六进制0x80040601~0x8004060E枚举值数值 (HRESULT)场景ImageNotFound-2147219967镜像未找到ContainerPrefixAmbiguous-2147219966容器名前缀存在歧义ContainerNotFound-2147219965容器未找到VolumeNotFound-2147219964卷未找到ContainerNotRunning-2147219963容器未在运行ContainerIsRunning-2147219962容器正在运行SessionReserved-2147219961会话被占用/保留InvalidSessionName-2147219960会话名非法NetworkNotFound-2147219959网络未找到WindowsUpdateSearchFailed-2147219958Windows Update 搜索失败SdkUpdateNeeded-2147219957SDK 需要更新ContainerDisabled-2147219956容器被禁用RegistryBlockedByPolicy-2147219955注册表操作被策略阻止VolumeNotAvailable-2147219954卷不可用用法示例将 HRESULT 与Error比较以精确诊断失败原因try { container.Start(); } catch (winrt::hresult_error const e) { if (e.code() static_castHRESULT(Error::ContainerNotFound)) { // 处理容器未找到 } }这组错误码覆盖了 WSLC 最常见的失败面镜像/容器/卷/网络的对象查找失败、生命周期状态冲突NotRunning / IsRunning、会话名校验、Windows Update 依赖、SDK 版本与策略限制等是编写健壮错误处理逻辑的重要依据。枚举使用要点与源码速查强转约定与模式匹配API 文档的核心提醒是不要假设某个枚举的数值在未来版本中不变除非确认它直接与 C API 对齐。判断标准很简单——查阅 wslcsdk.h 中是否有对应的Wslc*枚举定义C 枚举C API 枚举C 侧定义位置ComponentWslcComponentFlagswslcsdk.h#L644-L654DeleteContainerOptionWslcDeleteContainerFlagswslcsdk.h#L327-L331ContainerNetworkingModeWslcContainerNetworkingModewslcsdk.h#L85-L87ContainerStateWslcContainerStatewslcsdk.h#L303-L310SignalWslcSignalwslcsdk.h#L315-L323ProcessStateWslcProcessStatewslcsdk.hVhdTypeWslcVhdTypewslcsdk.h#L89-L93ImageProgressStatusWslcImageProgressStatuswslcsdk.h#L451-L460SessionTerminationReasonWslcSessionTerminationReasonwslcsdk.h#L126-L131位掩码与普通枚举的区别Component是位掩码flags支持组合检测DeleteContainerOption虽然只有 0/1 两个值但在 C 侧同样是 flags 类型WslcDeleteContainerFlags启用DEFINE_ENUM_FLAG_OPERATORS。其余枚举均为互斥的普通枚举比较时直接判等即可。文档中的代码风格API 文档示例刻意使用了static_castEnumType(N)的写法来强调底层数值与 C API 的对齐关系。在实际产品代码中推荐优先使用具名枚举值如ContainerState::Running以保证可读性仅在需要与 C API 互操作、序列化或日志输出数值时才做显式强转。进一步阅读枚举的消费方类容器见 container.md进程见 process.md会话见 session.md服务入口见 wslcservice.md携带枚举的设置类容器设置见 containersettings.md进程设置见 processsettings.mdVHD 选项见 vhdoptions.md携带枚举的数据类进度见 imageprogress.md端口映射见 containerportmapping.md一个完整的端到端示例见 end-to-end-example.md尚未实现的能力与已知缺口见 not-yet-implemented-and-known-gaps.md。总结WSL C API 的 13 个枚举覆盖了 WSLC 编程模型的全链路Component负责环境就绪检查ContainerState/ProcessState/SessionTerminationReason负责状态观测DeleteContainerOption/Signal/PortProtocol/ContainerNetworkingMode/VhdType负责操作配置ProcessOutputHandle/ProcessOutputMode负责 I/O 模型选择ImageProgressStatus负责镜像进度呈现Error负责精确错误诊断。它们的数值与 C API 中对应的Wslc*枚举严格一致这份契约正是 C/WinRT 封装与底层 C 实现之间稳定互操作的基础需要精确数值时随时查阅 wslcsdk.h 即可获得权威定义。【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考