WSL 容器 SDK C API 指南使用 InstallProgress 跟踪组件依赖安装进度【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSLInstallProgress是 WSL 容器 SDKWSLCC/WinRT 投影层中用于报告依赖组件安装进度的数据类由WslcService::InstallWithDependenciesAsync()在后台安装过程中触发。本指南将结合 API 文档与源码实现讲解该类的属性、与底层 C API 的对应关系以及如何在客户端代码中消费进度事件。核心主题在开发基于 Windows Subsystem for Linux 容器WSLC的应用时通常需要先确保宿主系统具备运行所需的组件如 Virtual Machine Platform 和 WSL 运行时包。InstallProgress就是为这一前置检查与安装环节设计的进度载体它把底层 C 接口WslcInstallWithDependencies的逐组件进度回调封装成 WinRT 数据对象让 C/WinRT 应用可以通过IAsyncActionWithProgressInstallProgress的Progress事件获得实时更新。阅读完本文后你将掌握InstallProgress的三个属性Component()、Progress()、Total()各自代表什么它如何与Component枚举和WslcService静态方法配合完成检查缺失组件 → 异步安装 → 订阅进度的完整流程从 C 回调到 WinRT 对象的转换链路便于在需要调试或扩展时定位源码。关联上下文WSLC 的 C/WinRT 投影InstallProgress位于winrt::Microsoft::WSL::Containers命名空间属于 WSL 容器 API 的 C/WinRT 投影层。根据 C API 参考索引 的说明该投影以Session → Container → Process为分层模型图像与安装类操作使用IAsyncActionWithProgressT返回类型——安装正是这类带进度的异步操作。投影层对应的头文件为#include winrt/Microsoft.WSL.Containers.h这是由 wslcsdk.idl 中的 WinRT 接口定义生成的。在 IDL 中InstallProgress被声明为runtimeclass InstallProgress { Component Component { get; }; UInt32 Progress { get; }; UInt32 Total { get; }; }实现上InstallProgress.cpp 是一个简单的值对象构造函数接收component、progress、total三个值三个属性方法只是原样返回内部成员。属性详解InstallProgress共提供三个只读属性属性类型含义Component()Component当前正在安装的组件见下方枚举说明Progress()uint32_t当前组件已完成/正在进行的进度步数Total()uint32_t当前组件的总进度步数其中Component是一个位掩码枚举定义在 Component 枚举文档 中底层取值如下VirtualMachinePlatform 1Virtual Machine Platform 可选功能提供的服务安装该组件后需要重启系统WslPackage 2WSL 运行时包需为支持 WSLC 的适当版本SdkNeedsUpdate 4WSLC SDK 自身需要更新。这些值与底层 C API wslcsdk.h 中的WslcComponentFlags位标志一一对应。注意Progress与Total反映的是步骤数steps不是字节数或百分比。要计算百分比可自行计算Progress() * 100 / Total()注意Total()为 0 时需做保护。使用示例订阅安装进度原文档提供了最直接的用法调用WslcService::InstallWithDependenciesAsync()获取异步操作用.Progress(...)订阅回调然后co_await等待完成。auto install WslcService::InstallWithDependenciesAsync(); install.Progress([](auto, InstallProgress const p) { printf(component%d step%u/%u\n, static_castint(p.Component()), p.Progress(), p.Total()); }); co_await install;注意示例中Progress()与Total()是uint32_t因此格式化用%uComponent()是枚举需要static_castint后再以%d输出。完整前置检查 安装流程在实际应用中InstallProgress通常与WslcService::GetMissingComponents()搭配使用。完整模式如下同时见于 WslcService 文档auto missing WslcService::GetMissingComponents(); if (missing ! static_castComponent(0)) { auto install WslcService::InstallWithDependenciesAsync(); install.Progress([](auto, InstallProgress const p) { printf(install %u/%u\n, p.Progress(), p.Total()); }); co_await install; }这里的关键点是进度回调只针对本次调用实际安装的组件。正如 wslcsdk.h 注释所强调的Callbacks will only be made for components that are actively installed by this call而所需组件列表应在调用前通过WslcGetMissingComponents获取。底层实现从 C 回调到 WinRT 进度InstallWithDependenciesAsync最终会调用底层 C 函数WslcInstallWithDependencies其签名见 wslcsdk.h为STDAPI WslcInstallWithDependencies( _In_ WslcComponentFlags components, _In_ WslcInstallOptions options, _In_opt_ WslcInstallCallback progressCallback, _In_opt_ PVOID context);其中进度回调类型为typedef __callback void(CALLBACK* WslcInstallCallback)( _In_ WslcComponentFlags component, _In_ uint32_t progressSteps, _In_ uint32_t totalSteps, _In_opt_ PVOID context);在 WslcService.cpp 中WinRT 层注册了一个InstallProgressCallback每当底层报告一次进度它就把component、progressSteps、totalSteps包装成一个新的InstallProgress对象并通过ProgressCallbackHelper::ReportProgress转发给IAsyncActionWithProgressInstallProgress的订阅者。这正是你看到p.Component()、p.Progress()、p.Total()与回调参数一一对应的来源。可选的组件指定与修复选项InstallWithDependenciesAsync还接受一个可选的InstallOptions参数见 wslcsdk.idlInstallOptions::Components显式指定要安装的组件列表。若提供则跳过GetMissingComponents检查若列表中包含SdkNeedsUpdate会直接抛出WSLC_E_SDK_UPDATE_NEEDED。InstallOptions::Repair对应底层WSLC_INSTALL_OPTION_REPAIR允许重新安装组件。未指定组件时WinRT 层会先调用WslcGetMissingComponents自动确定所需组件见 WslcService.cpp。与其他进度类的对比WSLC 投影中还定义了ImageProgress用于镜像 pull/import/load/push 操作它与InstallProgress的区别在于ImageProgress报告的是镜像层粒度的进度属性为Id()层 ID、Status()状态枚举、CurrentBytes()/TotalBytes()字节数见 ImageProgress 文档InstallProgress报告的是系统组件安装粒度的进度属性为Component()和步骤数。两者都通过IAsyncActionWithProgressT的Progress事件上报消费模式一致。参考阅读InstallProgress API 文档Component 枚举文档WslcService 文档C API 参考索引端到端示例源码\src/windows/WslcSDK/winrt/InstallProgress.h、InstallProgress.cpp、WslcService.cpp、wslcsdk.h【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考