WSL C# SDK 镜像推送PushImageOptions 完整配置指南【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL本文围绕 WSLWindows Subsystem for Linux容器 SDKWSLCC# 投影中的PushImageOptions配置类展开讲解如何将 WSL 容器会话内的镜像推送至远程镜像仓库涵盖参数语义、底层调用链、错误处理与异步进度用法。读完本文你将掌握 WSL C# SDK 中PushImageOptions的完整配置与实战调用方式并理解其与底层 C/WinRT 实现的对应关系。一、概述PushImageOptions 是什么PushImageOptions是 WSL 容器 SDK 中用于配置镜像推送Push操作的参数对象。在 WSL 容器工作流中开发者通常先在本地构造、拉取或导入镜像随后需要将其推送到 Docker Registry 等远程仓库以便分发或备份此时即可使用Session.PushImage/Session.PushImageAsync配合PushImageOptions完成。该类的定位与PullImageOptions、TagImageOptions同属 SDK 的设置类Settings Classes一族相关的类索引见 doc/docs/api-reference/csharp/settings-classes/index.md。类定义与构造根据 doc/docs/api-reference/csharp/settings-classes/pushimageoptions.md该类在 C# 投影中的定义为public sealed class PushImageOptions { public PushImageOptions(string image, string registryAuth); public string Image { get; set; } public string RegistryAuth { get; set; } }要点构造时需同时提供image与registryAuth两个参数Image与RegistryAuth均提供可读写的属性类是sealed密封的不可被继承表明其作为纯数据承载对象使用。与底层 API 的对应关系PushImageOptions并非凭空设计它在 SDK 各语言层有一一对应的实现C# 层本文主角src/windows/WslcSDK/csharp/下的投影类作为 WinRT 投影暴露给 C# 开发者WinRT 层src/windows/WslcSDK/winrt/PushImageOptions.h与 PushImageOptions.cpp 中的winrt::Microsoft::WSL::Containers::implementation::PushImageOptionsMIDL 定义src/windows/WslcSDK/winrt/wslcsdk.idl中的runtimeclass PushImageOptions它是 WinRT 投影的契约来源runtimeclass PushImageOptions { PushImageOptions(String image, String registryAuth); String Image; String RegistryAuth; };C API 层WslcPushImageOptions结构体定义见 doc/docs/api-reference/c/structures/wslcpushimageoptions.md结构体比 C# 类多出progressCallback与progressCallbackContext两个用于进度回调的字段。二、字段详解2.1 Image镜像引用Image指定要推送的镜像引用。它必须包含完整的仓库地址registry 主机 仓库路径 标签例如var pushOptions new PushImageOptions(registry.example.com/demo:latest, authToken);镜像引用通常形如registry.example.com/demo:latest其中片段说明示例registry 主机镜像仓库服务器地址含端口可省略registry.example.com仓库路径仓库与命名空间demo标签版本标签缺省一般为latestlatest实战提示推送前通常先用TagImage将本地镜像打上带 registry 前缀的标签再执行推送。测试代码 test/windows/WslcSdkWinRTTests.cpp 中正是先TagImage(imageName, registryRepo, tag)再构造带 registry 前缀的PushImageOptions进行推送并在推送后用DELETE_IMAGE_ON_SCOPE_EXIT清理临时镜像。2.2 RegistryAuth注册表认证RegistryAuth指定访问私有镜像仓库所需的认证信息。从 C API 注释可知该字段语义是Base64 编码的X-Registry-AuthHTTP 请求头值见 doc/docs/api-reference/c/structures/wslcpushimageoptions.md。也就是说推送私有仓库镜像时需要把 Docker 风格的认证令牌token或用户名/密码构造为 registry auth 头再进行 Base64 编码后传入。SDK 内部在src/windows/WslcSDK/wslcsdk.cpp中提供了BuildRegistryAuthHeader辅助逻辑用于在认证后生成合法的 registry auth 头字符串说明该字段承载的是完整的鉴权头载荷而非裸的用户名密码。三、构造约束与校验规则从 PushImageOptions.cpp 的实现可以总结出以下严格的参数校验规则3.1 空值校验E_INVALIDARG无论是构造函数还是属性 setterimage与registryAuth都不允许为空字符串// 以下均会抛出异常 new PushImageOptions(, authToken); // Image cannot be empty new PushImageOptions(repo/img:tag, ); // Registry auth cannot be empty对应 WinRT 实现抛出的异常为hresult_invalid_argumentHRESULTE_INVALIDARG错误信息分别为Image cannot be empty与Registry auth cannot be empty。测试代码 test/windows/WslcSdkWinRTTests.cpp 中亦有对应验证VERIFY_THROWS_HR(m_defaultSession.PushImageAsync(WSLCSDK::PushImageOptions(L, winrt::to_hstring(xRegistryAuth))).get(), E_INVALIDARG);3.2 应用后锁定E_ILLEGAL_STATE_CHANGEPushImageOptions在把参数转换为底层结构体ToStruct()之后属性值即被锁定。若在选项已被应用后再尝试修改Image或RegistryAuth会抛出hresult_illegal_state_change错误信息为Cannot change value after options have been applied。这保证了在一次推送操作中参数的一致性避免调用中途静默篡改配置。因此推荐的最佳实践是先完整构造并配置好PushImageOptions再调用Session.PushImage/PushImageAsync不要在调用后复用并修改同一个选项对象。四、与 Session 的协作从选项到推送完成4.1 底层调用链PushImageOptions最终通过Session的推送方法发挥作用。以异步版本为例Session.cpp 中PushImageAsync的实现流程为空指针检查options为 null 时抛出hresult_error(E_POINTER, Options for push cannot be null)EnsureStarted()确保 Session 已启动否则操作无法执行GetStruct(options)将 WinRT 对象转换为底层WslcPushImageOptions结构体即触发ToStruct()与应用后锁定挂接progressCallback与progressCallbackContext异步版本将进度事件桥接到 WinRT 的IAsyncActionWithProgressImageProgress调用 C APIWslcPushSessionImage(ToHandle(), pushOptions, errorMessage.put())见 wslcsdk.cpp并在失败时抛出携带错误消息的 HRESULT 异常。同步版本PushImage的流程与此一致只是不挂接进度回调。C API 的签名定义在 doc/docs/api-reference/c/image-apis/wslcpushsessionimage.mdSTDAPI WslcPushSessionImage(_In_ WslcSession session, _In_ const WslcPushImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);C API 层同样会校验options、options-image、options-registryAuth不为空空则返回E_INVALIDARG随后调用内部运行时internalType-session-PushImage(...)。4.2 同步与异步两种调用方式// 同步方式阻塞直到推送完成或抛异常 session.PushImage(pushOptions); // 异步方式返回带进度的 IAsyncActionWithProgressImageProgress var progress session.PushImageAsync(pushOptions);异步版本可配合ProgressImageProgress接收推送过程中的阶段事件。进度事件类型ImageProgress在wslcsdk.idl中定义包含Id、Status、CurrentBytes、TotalBytes等字段可用于展示推送的拉取/下载/校验/解压等阶段状态。4.3 完整调用示例综合以上内容一次完整的镜像推送流程如下// 1. 构造推送选项image 与 registryAuth 均不能为空 var pushOptions new PushImageOptions(registry.example.com/demo:latest, authToken); // 2. 通过已启动的 Session 执行推送异步 进度 var progress session.PushImageAsync(pushOptions); progress.Progress (asyncInfo, imageProgress) { Console.WriteLine($Image {imageProgress.Id}: {imageProgress.Status}, ${imageProgress.CurrentBytes}/{imageProgress.TotalBytes} bytes); }; await progress;五、常见错误与排查场景表现原因与对策image或registryAuth为空抛出E_INVALIDARGImage/Registry auth cannot be empty构造参数不合法检查是否传入了空字符串选项对象为 null 传入 Session抛出E_POINTEROptions for push cannot be null未实例化选项先new PushImageOptions(...)Session 未启动抛出无效状态相关错误先调用Session.Start()再推送推送不存在的镜像测试中以E_FAIL捕获如推送does-not-exist确认镜像已在会话内存在先用PullImage/ImportImage/TagImage准备修改已应用的选项抛出E_ILLEGAL_STATE_CHANGE不要复用已用于推送的选项对象重新构造新实例私有仓库认证失败推送报错确认registryAuth是 Base64 编码的X-Registry-Auth头值依据 test/windows/WslcSdkWinRTTests.cpp 中的相关测试空镜像参数L会按E_INVALIDARG捕获而推送不存在的镜像则按E_FAIL处理可作为异常语义的参考。六、小结PushImageOptions是 WSL 容器 SDK C# 投影中面向镜像推送场景的配置对象核心只有两个字段Image目标镜像引用与RegistryAuthBase64 编码的 registry 认证头。使用时需注意三点两个字段均不可为空选项在应用调用Session.PushImage/PushImageAsync后即锁定推送前确保 Session 已启动且镜像已在会话中。其实现横跨 MIDL 契约wslcsdk.idl、WinRT 包装PushImageOptions.cpp与 C APIwslcsdk.cpp并得到 WinRT 测试WslcSdkWinRTTests.cpp的覆盖验证是理解 WSL 容器镜像分发链路的一个典型切入点。【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
