尧图网站建设 
WSL C# API 深度解析用 PullImageOptions 从容器镜像仓库拉取镜像【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL本文围绕 WSLWindows Subsystem for LinuxWSLCWindows Subsystem for Linux ContainersSDK 的 C# 配置类PullImageOptions展开说明其两个核心属性Uri与RegistryAuth的用法、底层 C 结构体映射关系以及Session.PullImage/PullImageAsync的调用链与错误语义。读完后可掌握如何用 C# 从公共或私有镜像仓库拉取容器镜像、处理拉取进度事件并理解该选项类在 WinRT 层与 C API 之间的转换机制。类定义与基本用法PullImageOptions是 C# API 设置类之一用于描述从镜像仓库拉取镜像操作的参数。其完整定义为public sealed class PullImageOptions { public PullImageOptions(string uri); public string Uri { get; set; } public string RegistryAuth { get; set; } }最小使用示例来自 官方文档var pullOptions new PullImageOptions(docker.io/library/alpine:latest) { RegistryAuth string.Empty // optional for public registries };要点构造函数的uri参数是唯一的必选项指定要拉取的镜像地址通常包含registry/namespace/image:tag形式如docker.io/library/alpine:latest以及本地 registry 的localhost:5000/hello-world:latestRegistryAuth对公共仓库可省略置为空字符串即可匿名拉取拉取私有仓库镜像时必须提供认证凭据。属性语义从源码确认的约束WinRT 实现位于 PullImageOptions.cpp 与 PullImageOptions.h可从中确认以下行为约束Uri不可为空。构造函数和 setter 都会检查if (uri.empty()) { throw hresult_invalid_argument(LURI cannot be empty); }即传入空字符串会抛出hresult_invalid_argumentC# 中表现为ArgumentException。选项类是一次应用后冻结的。两个属性的 setter 在选项已被 SDK 消费后内部m_pullImageOptions已分配都会拒绝修改if (m_pullImageOptions) { throw hresult_illegal_state_change(LCannot change value after options have been applied); }这意味着一个PullImageOptions实例参与拉取操作后不应再被修改复用如需不同参数应新建实例。RegistryAuth为空串等价于匿名拉取。在转换为 C 结构体时m_pullImageOptions-registryAuth m_registryAuth.empty() ? nullptr : m_registryAuth.c_str();空串会被转换为nullptr与 C 结构体中registryAuth字段标注的_In_opt_可选一致。底层映射WinRT 选项类到 WslcPullImageOptions 结构体C# 层的PullImageOptions最终通过ToStruct()转换为 C API 的结构体 WslcPullImageOptions定义于 wslcsdk.htypedef struct WslcPullImageOptions { _In_z_ PCSTR uri; WslcContainerImageProgressCallback progressCallback; PVOID progressCallbackContext; _In_opt_z_ PCSTR registryAuth; } WslcPullImageOptions; STDAPI WslcPullSessionImage(_In_ WslcSession session, _In_ const WslcPullImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);C 字段说明C# 对应uri_In_z_必填镜像地址Uri属性registryAuth_In_opt_可选仓库认证凭据RegistryAuth属性progressCallback/progressCallbackContext进度回调C# 层不直接暴露见下文PullImageAsync注意 WinRT 转换实现中有两处细节PullImageOptions.cppToStruct()是惰性且幂等的首次调用时分配结构体并写入字段之后重复调用返回同一缓存结构体的引用结构体中的progressCallback被置为nullptr——C# 用户不通过函数指针接收进度而是走PullImageAsync的IAsyncActionWithProgress事件通道。对应的拉取接口在 IDL 中声明wslcsdk.idlvoid PullImage(PullImageOptions options); Windows.Foundation.IAsyncActionWithProgressImageProgress PullImageAsync(PullImageOptions options);即同步与异步两个入口PullImageOptions运行时类定义于 wslcsdk.idlruntimeclass PullImageOptions { PullImageOptions(String uri); String Uri; String RegistryAuth; };拉取进度ImageProgress 与 ImageProgressStatus异步拉取会回调进度事件进度类型为 ImageProgress字段为Id层 ID 或 digest、Status、CurrentBytes、TotalBytes。Status对应 C 层枚举wslcsdk.h与docker pull的常见输出阶段一一对应typedef enum WslcImageProgressStatus { WSLC_IMAGE_PROGRESS_STATUS_UNKNOWN 0, WSLC_IMAGE_PROGRESS_STATUS_PULLING 1, // Pulling fs layer WSLC_IMAGE_PROGRESS_STATUS_WAITING 2, // Waiting WSLC_IMAGE_PROGRESS_STATUS_DOWNLOADING 3, // Downloading WSLC_IMAGE_PROGRESS_STATUS_VERIFYING 4, // Verifying Checksum WSLC_IMAGE_PROGRESS_STATUS_EXTRACTING 5, // Extracting WSLC_IMAGE_PROGRESS_STATUS_COMPLETE 6 // Pull complete } WslcImageProgressStatus;完整实战创建会话并异步拉取镜像端到端示例演示了PullImageOptions在完整生命周期中的位置// 1. 创建会话4 CPU / 4 GB 内存 var sessionSettings new SessionSettings(MyApp, C:\WslcData) { CpuCount 4, MemorySizeInMB 4096 }; var session new Session(sessionSettings); session.Start(); // 2. 拉取镜像并输出进度 var pullOp session.PullImageAsync(new PullImageOptions(docker.io/library/alpine:latest)); pullOp.Progress (op, progress) Console.WriteLine($Pull: {progress.Status} {progress.CurrentBytes}/{progress.TotalBytes}); await pullOp; // 3. 用拉下来的镜像创建容器 var containerSettings new ContainerSettings(alpine:latest) { Name hello-container, InitProcess new ProcessSettings { CommandLine new[] { /bin/echo, Hello from WSL Container! }, OutputMode ProcessOutputMode.Event } }; var container session.CreateContainer(containerSettings); container.Start();仓库中的 WSLC-NextCloud 示例则展示了同步版本的简写用法session.PullImage(new PullImageOptions(imageName))——公共仓库镜像只需提供 URI 一个参数即可完成拉取。错误语义与私有仓库认证测试用例佐证单元测试 WslcSdkTests.cpp 的PullImage测试方法用真实场景验证了该选项类的边界行为可据此建立可预期的错误处理场景结果从本地 registry 真实拉取镜像先删除本地镜像确保是真实拉取成功HasImage校验通过且拉取后可直接运行容器输出 Hello from Docker!拉取 registry 中不存在的镜像返回WSLC_E_IMAGE_NOT_FOUNDuri为nullptr返回E_INVALIDARG私有 registry 未提供凭据WslcPullSessionImage返回E_FAIL并输出错误信息提供错误凭据返回E_FAIL对于私有仓库测试用例WslcSdkTests.cpp展示了推荐凭据流先调用WslcSessionAuthenticate换取认证串其输出可以不做任何转换直接作为registryAuth传入VERIFY_SUCCEEDED(WslcSessionAuthenticate( m_defaultSession, registryAddress.c_str(), c_username, c_password, authToken, nullptr, nullptr)); WslcPullImageOptions opts{}; opts.uri image.c_str(); opts.registryAuth authToken.get(); VERIFY_SUCCEEDED(WslcPullSessionImage(m_defaultSession, opts, nullptr));即 C# 场景下的组合模式为Session.Authenticate(...)获得认证结果 → 将其赋给PullImageOptions.RegistryAuth→ 调用PullImageAsync。这与 C 层registryAuth标注为_In_opt_且测试注释output can be passed as registryAuth without any transformation相吻合。小结与相关文档PullImageOptions仅两个属性Uri必填、不可为空与RegistryAuth可选空串等价匿名拉取选项类在参与一次拉取应用后应视为冻结修改属性会抛hresult_illegal_state_change异步拉取通过PullImageAsync的IAsyncActionWithProgressImageProgress获得与docker pull一致的阶段化进度Pulling/Downloading/Verifying/Extracting/Complete错误语义已被单元测试覆盖镜像不存在返回WSLC_E_IMAGE_NOT_FOUND参数非法返回E_INVALIDARG凭据错误返回E_FAIL。可继续深入的相关文档C# API 总览 与 Session 核心类C API 的 WslcPullImageOptions 结构体 与 WslcPullSessionImagePushImageOptions、TagImageOptions拉取/推送/打标构成镜像管理闭环C 端到端示例对照同构的 C 拉取流程【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WSL C API 深度解析：用 PullImageOptions 从容器镜像仓库拉取镜像
WSL C# API 深度解析用 PullImageOptions 从容器镜像仓库拉取镜像【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL本文围绕 WSLWindows Subsystem for LinuxWSLCWindows Subsystem for Linux ContainersSDK 的 C# 配置类PullImageOptions展开说明其两个核心属性Uri与RegistryAuth的用法、底层 C 结构体映射关系以及Session.PullImage/PullImageAsync的调用链与错误语义。读完后可掌握如何用 C# 从公共或私有镜像仓库拉取容器镜像、处理拉取进度事件并理解该选项类在 WinRT 层与 C API 之间的转换机制。类定义与基本用法PullImageOptions是 C# API 设置类之一用于描述从镜像仓库拉取镜像操作的参数。其完整定义为public sealed class PullImageOptions { public PullImageOptions(string uri); public string Uri { get; set; } public string RegistryAuth { get; set; } }最小使用示例来自 官方文档var pullOptions new PullImageOptions(docker.io/library/alpine:latest) { RegistryAuth string.Empty // optional for public registries };要点构造函数的uri参数是唯一的必选项指定要拉取的镜像地址通常包含registry/namespace/image:tag形式如docker.io/library/alpine:latest以及本地 registry 的localhost:5000/hello-world:latestRegistryAuth对公共仓库可省略置为空字符串即可匿名拉取拉取私有仓库镜像时必须提供认证凭据。属性语义从源码确认的约束WinRT 实现位于 PullImageOptions.cpp 与 PullImageOptions.h可从中确认以下行为约束Uri不可为空。构造函数和 setter 都会检查if (uri.empty()) { throw hresult_invalid_argument(LURI cannot be empty); }即传入空字符串会抛出hresult_invalid_argumentC# 中表现为ArgumentException。选项类是一次应用后冻结的。两个属性的 setter 在选项已被 SDK 消费后内部m_pullImageOptions已分配都会拒绝修改if (m_pullImageOptions) { throw hresult_illegal_state_change(LCannot change value after options have been applied); }这意味着一个PullImageOptions实例参与拉取操作后不应再被修改复用如需不同参数应新建实例。RegistryAuth为空串等价于匿名拉取。在转换为 C 结构体时m_pullImageOptions-registryAuth m_registryAuth.empty() ? nullptr : m_registryAuth.c_str();空串会被转换为nullptr与 C 结构体中registryAuth字段标注的_In_opt_可选一致。底层映射WinRT 选项类到 WslcPullImageOptions 结构体C# 层的PullImageOptions最终通过ToStruct()转换为 C API 的结构体 WslcPullImageOptions定义于 wslcsdk.htypedef struct WslcPullImageOptions { _In_z_ PCSTR uri; WslcContainerImageProgressCallback progressCallback; PVOID progressCallbackContext; _In_opt_z_ PCSTR registryAuth; } WslcPullImageOptions; STDAPI WslcPullSessionImage(_In_ WslcSession session, _In_ const WslcPullImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);C 字段说明C# 对应uri_In_z_必填镜像地址Uri属性registryAuth_In_opt_可选仓库认证凭据RegistryAuth属性progressCallback/progressCallbackContext进度回调C# 层不直接暴露见下文PullImageAsync注意 WinRT 转换实现中有两处细节PullImageOptions.cppToStruct()是惰性且幂等的首次调用时分配结构体并写入字段之后重复调用返回同一缓存结构体的引用结构体中的progressCallback被置为nullptr——C# 用户不通过函数指针接收进度而是走PullImageAsync的IAsyncActionWithProgress事件通道。对应的拉取接口在 IDL 中声明wslcsdk.idlvoid PullImage(PullImageOptions options); Windows.Foundation.IAsyncActionWithProgressImageProgress PullImageAsync(PullImageOptions options);即同步与异步两个入口PullImageOptions运行时类定义于 wslcsdk.idlruntimeclass PullImageOptions { PullImageOptions(String uri); String Uri; String RegistryAuth; };拉取进度ImageProgress 与 ImageProgressStatus异步拉取会回调进度事件进度类型为 ImageProgress字段为Id层 ID 或 digest、Status、CurrentBytes、TotalBytes。Status对应 C 层枚举wslcsdk.h与docker pull的常见输出阶段一一对应typedef enum WslcImageProgressStatus { WSLC_IMAGE_PROGRESS_STATUS_UNKNOWN 0, WSLC_IMAGE_PROGRESS_STATUS_PULLING 1, // Pulling fs layer WSLC_IMAGE_PROGRESS_STATUS_WAITING 2, // Waiting WSLC_IMAGE_PROGRESS_STATUS_DOWNLOADING 3, // Downloading WSLC_IMAGE_PROGRESS_STATUS_VERIFYING 4, // Verifying Checksum WSLC_IMAGE_PROGRESS_STATUS_EXTRACTING 5, // Extracting WSLC_IMAGE_PROGRESS_STATUS_COMPLETE 6 // Pull complete } WslcImageProgressStatus;完整实战创建会话并异步拉取镜像端到端示例演示了PullImageOptions在完整生命周期中的位置// 1. 创建会话4 CPU / 4 GB 内存 var sessionSettings new SessionSettings(MyApp, C:\WslcData) { CpuCount 4, MemorySizeInMB 4096 }; var session new Session(sessionSettings); session.Start(); // 2. 拉取镜像并输出进度 var pullOp session.PullImageAsync(new PullImageOptions(docker.io/library/alpine:latest)); pullOp.Progress (op, progress) Console.WriteLine($Pull: {progress.Status} {progress.CurrentBytes}/{progress.TotalBytes}); await pullOp; // 3. 用拉下来的镜像创建容器 var containerSettings new ContainerSettings(alpine:latest) { Name hello-container, InitProcess new ProcessSettings { CommandLine new[] { /bin/echo, Hello from WSL Container! }, OutputMode ProcessOutputMode.Event } }; var container session.CreateContainer(containerSettings); container.Start();仓库中的 WSLC-NextCloud 示例则展示了同步版本的简写用法session.PullImage(new PullImageOptions(imageName))——公共仓库镜像只需提供 URI 一个参数即可完成拉取。错误语义与私有仓库认证测试用例佐证单元测试 WslcSdkTests.cpp 的PullImage测试方法用真实场景验证了该选项类的边界行为可据此建立可预期的错误处理场景结果从本地 registry 真实拉取镜像先删除本地镜像确保是真实拉取成功HasImage校验通过且拉取后可直接运行容器输出 Hello from Docker!拉取 registry 中不存在的镜像返回WSLC_E_IMAGE_NOT_FOUNDuri为nullptr返回E_INVALIDARG私有 registry 未提供凭据WslcPullSessionImage返回E_FAIL并输出错误信息提供错误凭据返回E_FAIL对于私有仓库测试用例WslcSdkTests.cpp展示了推荐凭据流先调用WslcSessionAuthenticate换取认证串其输出可以不做任何转换直接作为registryAuth传入VERIFY_SUCCEEDED(WslcSessionAuthenticate( m_defaultSession, registryAddress.c_str(), c_username, c_password, authToken, nullptr, nullptr)); WslcPullImageOptions opts{}; opts.uri image.c_str(); opts.registryAuth authToken.get(); VERIFY_SUCCEEDED(WslcPullSessionImage(m_defaultSession, opts, nullptr));即 C# 场景下的组合模式为Session.Authenticate(...)获得认证结果 → 将其赋给PullImageOptions.RegistryAuth→ 调用PullImageAsync。这与 C 层registryAuth标注为_In_opt_且测试注释output can be passed as registryAuth without any transformation相吻合。小结与相关文档PullImageOptions仅两个属性Uri必填、不可为空与RegistryAuth可选空串等价匿名拉取选项类在参与一次拉取应用后应视为冻结修改属性会抛hresult_illegal_state_change异步拉取通过PullImageAsync的IAsyncActionWithProgressImageProgress获得与docker pull一致的阶段化进度Pulling/Downloading/Verifying/Extracting/Complete错误语义已被单元测试覆盖镜像不存在返回WSLC_E_IMAGE_NOT_FOUND参数非法返回E_INVALIDARG凭据错误返回E_FAIL。可继续深入的相关文档C# API 总览 与 Session 核心类C API 的 WslcPullImageOptions 结构体 与 WslcPullSessionImagePushImageOptions、TagImageOptions拉取/推送/打标构成镜像管理闭环C 端到端示例对照同构的 C 拉取流程【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考