WSL 容器 SDK 镜像管理指南WslcDeleteSessionImage 删除会话镜像 API 详解【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSLWslcDeleteSessionImage是 Windows Subsystem for LinuxWSL容器 SDKWslcSDK中负责从会话Session内删除容器镜像的 C 语言 API。本文以官方 API 参考文档 wslcdeletesessionimage.md 为核心结合仓库内 SDK 头文件、实现源码与测试用例讲解该 API 的函数签名、参数语义、错误码、完整调用示例及其底层实现原理帮助开发者正确地在 WSL 容器应用中管理镜像生命周期。功能定位镜像生命周期中的删除环节在 WSL 容器 SDK 中镜像Image是创建容器的模板。SDK 围绕镜像提供了一整套生命周期管理 API见 image-apis/index.md拉取与导入WslcPullSessionImage、WslcImportSessionImage、WslcImportSessionImageFromFile加载WslcLoadSessionImage、WslcLoadSessionImageFromFile删除WslcDeleteSessionImage本文主角查询WslcListSessionImages打标签与推送WslcTagSessionImage、WslcPushSessionImageWslcDeleteSessionImage即其中删除一环用于从指定会话中移除不再需要的镜像或镜像标签释放磁盘与元数据空间。例如当开发者完成demo/imported:latest镜像的验证后即可调用本 API 将其清理掉。需要特别提醒根据 wslcsdk.h 文件头部的 PREVIEW NOTICE整个 WSL 容器 SDK 当前仍处于预览阶段API 可能在未来的版本中发生破坏性变更请勿在正式生产负载中依赖其稳定性。函数签名与参数详解WslcDeleteSessionImage的完整声明位于 wslcsdk.h签名如下STDAPI WslcDeleteSessionImage( _In_ WslcSession session, _In_z_ PCSTR nameOrID, _Outptr_opt_result_z_ PWSTR* errorMessage);各参数含义与方向如下表所示参数类型方向说明sessionWslcSessionin目标会话句柄必须是由WslcCreateSession创建且仍然有效的会话nameOrIDPCSTRin要删除的镜像名称如repo:tag或镜像 IDANSI 字符串errorMessagePWSTR*out, optional可选输出参数失败时返回详细的错误信息字符串宽字符以\0结尾可传NULL忽略函数返回值为HRESULT类型S_OK表示删除成功。其中nameOrID支持两种定位方式镜像名称形如hello-world:latest、demo/imported:latest、debian:sdk-test-tag的仓库:标签格式。测试用例 WslcSdkTests.cpp 中即使用该格式删除镜像。镜像 ID由WslcImageInfo.sha256字段32 字节 SHA-256 摘要标识的镜像唯一 ID测试用例中以image.c_str()从列表查询得到的 ID 字符串传入删除见 WslcSdkTests.cpp。从数据结构看镜像名长度上限为WSLC_IMAGE_NAME_LENGTH255 个字符 结束符\0见 wslcsdk.h。返回值与错误码作为HRESULT返回值的 API调用方必须通过SUCCEEDED(hr)/FAILED(hr)宏判断结果。结合头文件定义与测试用例可以归纳出以下关键返回值HRESULT含义依据S_OK删除成功WslcSdkTests.cpp 正向用例E_POINTER传入的nameOrID为NULL实现中的RETURN_HR_IF_NULL(E_POINTER, nameOrID)见 wslcsdk.cpp测试见 WslcSdkTests.cppHRESULT_FROM_WIN32(ERROR_INVALID_STATE)会话句柄内部状态无效如已被终止wslcsdk.cppWSLC_E_IMAGE_NOT_FOUND0x80040601指定的镜像或标签不存在头文件宏定义见 wslcsdk.h删除不存在的镜像返回该错误码见 WslcSdkTests.cpp此外wslcsdk.h 还定义了一系列 WSL 容器专属错误码WSLC_E_BASE 0x0600起包括WSLC_E_CONTAINER_NOT_FOUND、WSLC_E_SESSION_NOT_FOUND、WSLC_E_VOLUME_NOT_FOUND等删除操作可能间接返回其中部分错误码例如会话对应状态异常时。建议调用方对HRESULT进行统一记录以便排查。关于errorMessage当传入非NULL指针且操作失败时SDK 会通过内部的ErrorInfoWrapper填充人类可读的错误描述。测试用例 WslcSdkTests.cpp 验证了失败场景下errorMsg非空且可被日志输出。调用方在成功返回后无需处理该字符串失败时若不再使用应释放其内存SDK 中此类输出字符串通常由CoTaskMemAlloc分配应配合CoTaskMemFree释放。完整可运行的 C 示例原 API 文档给出了最小示例HRESULT hr WslcDeleteSessionImage(session, demo/imported:latest, NULL);但在真实应用中session需要先通过会话创建流程获得。结合 wslcsdk.h 中WslcInitSessionSettings、WslcCreateSession、WslcReleaseSession的声明下面给出一个带完整错误处理的实战示例#include windows.h #include wslcsdk.h HRESULT DeleteImageDemo(void) { HRESULT hr; // 1. 初始化会话设置名称 存储路径 WslcSessionSettings sessionSettings; hr WslcInitSessionSettings(Ldemo-session, LC:\\wslc\\demo, sessionSettings); if (FAILED(hr)) { return hr; } // 2. 创建会话 WslcSession session nullptr; wil::unique_cotaskmem_string errorMessage; hr WslcCreateSession(sessionSettings, session, errorMessage); if (FAILED(hr)) { // errorMessage 中包含失败原因描述 return hr; } // 3. 删除镜像按名称tag 指向的镜像层若被其他标签引用仅移除该标签 hr WslcDeleteSessionImage(session, demo/imported:latest, errorMessage); if (FAILED(hr)) { // 常见失败WSLC_E_IMAGE_NOT_FOUND镜像不存在、E_POINTER名称/ID 为 NULL return hr; } // 4. 释放会话句柄 hr WslcReleaseSession(session); return hr; }要点说明会话创建后即可反复执行镜像操作删除镜像后再创建的容器将无法引用该镜像WslcCreateContainer对不存在的镜像会返回WSLC_E_IMAGE_NOT_FOUND参见 WslcSdkTests.cpp。errorMessage每次调用前可复用同一个wil::unique_cotaskmem_string管理内存SDK 内部会正确处理其生命周期。源码级实现剖析WslcDeleteSessionImage的实现位于 wslcsdk.cpp核心调用链如下错误信息包装创建ErrorInfoWrapper errorInfoWrapper{errorMessage}将调用方传入的errorMessage输出指针接入统一错误收集机制。会话有效性校验通过CheckAndGetInternalType(session)取得会话内部类型若底层session为空则返回HRESULT_FROM_WIN32(ERROR_INVALID_STATE)。参数校验nameOrID为NULL时直接返回E_POINTER。构造删除选项填充WSLCCompatDeleteImageOptions options{}并将options.Image置为nameOrID。从源码注释// TODO: Flags? (Force and NoPrune)可以看出当前公开版本只支持按名称/ID 定位删除尚未暴露强制删除Force与不清理NoPrune等底层 Docker 兼容选项这是可以合理推断的后续演进方向。下发底层实现调用internalType-session-DeleteImage(options, deletedImageInformation, deletedImageInformation.size_addressULONG())由会话层完成实际删除并收集被删除镜像的信息数组。结果汇总通过errorInfoWrapper.CaptureResult(...)将底层HRESULT结果与错误信息统一返回给调用方。此外该函数通过 wslcsdk.def 导出为 DLL 公共接口可供链接wslcsdk.lib的应用程序调用。SDK 同时提供 WinRT 封装层在 winrt/Session.cpp 中可见Session::DeleteImage的对应实现说明该能力同时暴露给 C/WinRT 调用方。测试验证与行为边界仓库测试 WslcSdkTests.cpp 中的ImageDelete测试用例清晰刻画了本 API 的行为边界WSLC_TEST_METHOD(ImageDelete) { VERIFY_IS_TRUE(HasImage(hello-world:latest)); // 正向删除已存在的镜像 wil::unique_cotaskmem_string errorMsg; VERIFY_SUCCEEDED(WslcDeleteSessionImage(m_defaultSession, hello-world:latest, errorMsg)); // 验证镜像已从列表中移除 VERIFY_IS_FALSE(HasImage(hello-world:latest)); // 重新加载镜像供后续测试使用 LoadTestImage(hello-world:latest); // 负向null 名称必须失败 VERIFY_ARE_EQUAL(WslcDeleteSessionImage(m_defaultSession, nullptr, nullptr), E_POINTER); }由此可以确认以下行为删除成功后可验证删除后调用WslcListSessionImages测试中的HasImage即基于镜像列表实现将不再看到该镜像空指针保护nameOrID传NULL必然返回E_POINTER且不会产生副作用不存在的镜像按名称删除不存在的镜像返回WSLC_E_IMAGE_NOT_FOUND见 WslcSdkTests.cpp标签删除语义在TagImage测试中WslcDeleteSessionImage(m_defaultSession, debian:sdk-test-tag, nullptr)被用作清理临时标签的手段见 WslcSdkTests.cpp说明该 API 同样适用于按标签删除——当同一镜像被多个标签引用时删除单个标签不会影响其他标签下的镜像层数据与 Docker 的 tag 删除语义一致从代码调用关系与测试用途可以推断。此外测试在镜像导入WslcImportSessionImage、拉取等用例的清理阶段大量使用本 API如 WslcSdkTests.cpp是验证镜像操作闭环的标准清理手段。与镜像生命周期其他 API 的协同一个典型的镜像管理流程可以这样组织获取镜像WslcPullSessionImage从仓库拉取或WslcImportSessionImage/WslcLoadSessionImage从本地导入查询WslcListSessionImages枚举镜像列表包含名称、SHA-256、大小与创建时间用于确认删除目标打标签WslcTagSessionImage为镜像添加额外标签便于按业务维度组织删除WslcDeleteSessionImage按名称或 ID 删除不再使用的镜像推送WslcPushSessionImage将本地镜像发布到远端仓库。各 API 的详细签名可分别查阅同目录下的 wslcpullsessionimage.md、wslcimportsessionimage.md、wslclistsessionimages.md、wslctagsessionimage.md 与 wslcpushsessionimage.md。注意事项与最佳实践预览期约束SDK 处于预览阶段函数签名与行为可能变更升级 SDK 版本后需回归验证删除逻辑头文件声明见 wslcsdk.h。会话必须存活删除操作依赖有效会话会话已终止时返回ERROR_INVALID_STATE用完会话记得WslcReleaseSession。名称/ID 的字符串编码nameOrID是 ANSI 字符串PCSTR而errorMessage是宽字符PWSTR混用时注意编码转换。删除前确认建议先调用WslcListSessionImages确认目标存在避免对WSLC_E_IMAGE_NOT_FOUND的误判删除操作不可撤销请确认镜像确无容器引用后再清理。错误信息日志化生产代码中请把errorMessage记录进日志测试中同样以LogInfo(Import error: %ws, errorMsg.get())方式输出这能显著缩短排障时间。引用计数语义按标签删除只移除该标签只有当镜像没有任何标签引用时镜像数据才会被真正回收这与底层容器运行时的镜像引用计数机制一致。综上所述WslcDeleteSessionImage是 WSL 容器 SDK 镜像管理中简单但高频的 API掌握其参数语义、错误码与底层调用链即可在容器应用中加入可靠的镜像清理能力。【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考