WSL 容器 SDK（WslcSDK）未实现能力与已知差距全解析：C API 与 WinRT 投影的差异、限制与工程规避

本篇技术指南以 WSL 仓库中 not-yet-implemented-and-known-gaps.md 为骨架，系统梳理 WslcSDK（WSL Containers SDK）中 C 接口与 WinRT 投影之间的全部已知差距：镜像导入/加载的句柄与路径之争、容器启动 flags 的隐式处理、进程回调管道的隐藏，以及 WinRT 包装源文件的快照缺失问题。读者读完后将掌握每个差距的具体表现、底层源码成因，以及在基于 C API 或 WinRT API 开发容器编排工具时如何规避这些限制。

WslcSDK 是 WSL 中面向 Windows 容器（WSLC）场景的官方 SDK，同时提供两套编程接口：一套是导出 DLL 的扁平 C API，另一套是基于 MIDL 定义、生成 Microsoft.WSL.Containers.winmd 的 C++/WinRT 投影。两套接口在能力上并非一一对应——部分底层能力只有 C API 暴露，而 WinRT 投影选择了更安全的路径参数与事件模型。理解这些差距，是避免在集成时踩坑的前提。

---

一、背景：WslcSDK 的双 API 形态与差距来源

WslcSDK 的 C API 全部声明在 wslcsdk.h，实现集中在 wslcsdk.cpp，并通过 wslcsdk.def 导出符号，例如 WslcCreateSession、WslcStartContainer、WslcImportSessionImage 等。

WinRT 投影位于 src/windows/WslcSDK/winrt 目录：由 wslcsdk.idl 定义 Microsoft.WSL.Containers 命名空间的运行时类（Session、Container、Process、ProcessSettings 等），再由 Container.cpp、Session.cpp、Process.cpp 等实现，构建产物为 Microsoft.WSL.Containers.winmd（见 winrt/CMakeLists.txt 的拷贝步骤）。

差距的根源在于：C API 面向底层、追求完整能力（句柄、回调、flags 一应俱全）；WinRT 投影面向托管式开发、追求安全与简洁（路径字符串、事件、异步），于是对底层能力做了有意裁剪与重新包装。下面的四类差距正是这一设计取舍的直接体现。

---

二、差距一：镜像导入/加载的 HANDLE 与路径之争

2.1 C API 的完整句柄能力

C API 暴露了两组镜像导入/加载接口，均支持从 HANDLE 读取镜像内容：

• WslcImportSessionImage：从 HANDLE imageContent 导入命名镜像；
• WslcLoadSessionImage：从 HANDLE imageContent 加载（未命名）镜像；
• 另有两个路径变体 WslcImportSessionImageFromFile / WslcLoadSessionImageFromFile，直接从磁盘路径读取。

声明见 wslcsdk.h，签名要点如下：

STDAPI WslcImportSessionImage(
    _In_ WslcSession session,
    _In_z_ PCSTR imageName,                 // 镜像名（ANSI）
    _In_ HANDLE imageContent,               // 镜像内容的文件句柄
    _In_ uint64_t imageContentLength,       // 内容字节数
    _In_opt_ const WslcImportImageOptions* options,   // 可携带进度回调
    _Outptr_opt_result_z_ PWSTR* errorMessage);

STDAPI WslcLoadSessionImage(
    _In_ WslcSession session,
    _In_ HANDLE imageContent,
    _In_ uint64_t imageContentBytes,
    _In_opt_ const WslcLoadImageOptions* options,
    _Outptr_opt_result_z_ PWSTR* errorMessage);

实现层面，两者共享同一个内部核心 WslcImportSessionImageImpl / WslcLoadSessionImageImpl（见 wslcsdk.cpp）。WslcImportImageOptions 中携带 progressCallback 与 progressCallbackContext（wslcsdk.h），内部通过 ProgressCallback::CreateIf(options) 桥接到会话的镜像拉取进度回调，进而把镜像内容交给底层容器运行时。注意 C API 侧 imageName 使用 PCSTR（ANSI 编码），上限为 WSLC_IMAGE_NAME_LENGTH（256 字节，255 字符 + 终止符，见 wslcsdk.h）。

2.2 WinRT 投影只暴露路径版本

在 wslcsdk.idl 中，WinRT 投影只声明了路径版本的四个方法：

void ImportImage(String path, String imageName);
Windows.Foundation.IAsyncActionWithProgress<ImageProgress> ImportImageAsync(String path, String imageName);
void LoadImage(String path);
Windows.Foundation.IAsyncActionWithProgress<ImageProgress> LoadImageAsync(String path);

对应的实现（Session.cpp）在内部调用的是 C API 的 WslcImportSessionImageFromFile / WslcLoadSessionImageFromFile（路径变体），而不是句柄变体：

auto hr = WslcImportSessionImageFromFile(ToHandle(), name.c_str(), path.c_str(), &importOptions, errorMessage.put());
...
auto hr = WslcLoadSessionImageFromFile(ToHandle(), path.c_str(), &loadOptions, errorMessage.put());

IDL 中甚至保留了一条显眼的 TODO 注释：// TODO: Explore additional overloads for other types of input streams（wslcsdk.idl），从源码结构看，这正说明“非路径输入流”的能力目前仅存在于 C API 层。

2.3 对开发者的工程影响

• 如果你的镜像内容来自内存缓冲、网络流、压缩包解压流等非落盘场景，WinRT 投影无法直接消费——必须先把内容落盘成临时文件，或直接使用 C API 的 WslcImportSessionImage / WslcLoadSessionImage 传入 HANDLE。
• 从 HANDLE 导入时，imageContentLength 必须与实际句柄可读长度一致，底层会按该长度进行 I/O，长度不实将导致导入失败或镜像截断。
• 若需要进度反馈，C API 侧通过 WslcImportImageOptions.progressCallback 提供；WinRT 侧则通过 IAsyncActionWithProgress<ImageProgress> 获得 ImageProgress 进度对象，两者事件模型不同，迁移时需注意桥接。

---

三、差距二：容器启动 flags 的隐式处理

3.1 C API 的显式 flags

C API 中 WslcStartContainer 接收显式 flags：

typedef enum WslcContainerStartFlags
{
    WSLC_CONTAINER_START_FLAG_NONE = 0x00000000,
    WSLC_CONTAINER_START_FLAG_ATTACH = 0x00000001,
} WslcContainerStartFlags;

定义见 wslcsdk.h，并有 DEFINE_ENUM_FLAG_OPERATORS 支持按位组合。ATTACH 标志的核心语义是：启动容器时让调用方附加到 init 进程的 I/O——在 wslcsdk.cpp 中可以看到强制约束：

bool hasIOCallback = IOCallback::HasIOCallback(internalType->ioCallbackOptions);
// If callbacks were provided, ATTACH must be used.
RETURN_HR_IF(E_INVALIDARG, WI_IsFlagClear(flags, WSLC_CONTAINER_START_FLAG_ATTACH) && hasIOCallback);

即：一旦通过 WslcSetContainerInitProcessIOCallbacks 注册了 I/O 回调，而启动 flags 中未设置 ATTACH，WslcStartContainer 会直接返回 E_INVALIDARG。这正是文档所述“显式容器启动 flags”在 C API 中的完整形态。

3.2 WinRT 的隐式强制

WinRT 投影中 Container::Start() 不接受任何参数（见 Container.h）。在 Container.cpp，包装层自动决定是否附加：

if (m_initProcess)
{
    WI_SetFlagIf(
        startFlags,
        WSLC_CONTAINER_START_FLAG_ATTACH,
        m_initProcess->OutputMode() == ProcessOutputMode::Event || m_initProcess->OutputMode() == ProcessOutputMode::Stream);
}

也就是说：只要 init 进程的输出模式是 Event 或 Stream，WinRT 就会无条件自动置位 ATTACH；反之若输出模式为 Discard（默认值，见 ProcessSettings.h），则不附加。这一逻辑保证了 WinRT 侧永远不会触发上面那个 E_INVALIDARG，代价是调用方无法在 WinRT 层自定义任何启动 flags。

3.3 对开发者的工程影响

• 在 WinRT 投影中，你无法表达“我想附加 I/O 但不想接管输出流”之类的中间态——OutputMode 是唯一的开关。
• 如果业务上需要完全控制启动 flags（例如未来新增标志位、或刻意以 NONE 启动后再接管），必须回退到 C API 的 WslcStartContainer。
• 从源码结构看，ATTACH 标志位目前是唯一定义的值（WSLC_CONTAINER_START_FLAG_NONE = 0 之外仅此一位），后续 WSL 若扩展标志位，WinRT 投影的“自动置位”策略也需要同步演进，届时差距可能进一步扩大。

---

四、差距三：进程回调管道的隐藏

4.1 C API 的原始管道能力

C API 层暴露了一套“原始”的进程 I/O 管道机制：

• WslcSetProcessSettingsCallbacks(processSettings, callbacks, context)：为 WslcProcessSettings 挂接回调；
• WslcGetProcessExitEvent(process, &exitEvent)：取出进程退出事件句柄，供 WaitForSingleObject 等原生等待；
• WslcGetProcessIOHandle：直接获取 init 进程的原始 I/O 句柄（stdin/stdout/stderr）。

回调结构定义在 wslcsdk.h：

typedef __callback void(CALLBACK* WslcProcessExitCallback)(INT32 exitCode, _In_opt_ PVOID context);

typedef struct WslcProcessCallbacks
{
    WslcStdIOCallback onStdOut;   // stdout 数据回调
    WslcStdIOCallback onStdErr;   // stderr 数据回调
    WslcProcessExitCallback onExit; // 退出回调
} WslcProcessCallbacks;

头文件中还有两条极易被忽略的关键约束注释（wslcsdk.h）：

Using any callbacks will consume the IO handles, preventing acquisition through WslcGetProcessIOHandle. If using IO callbacks, also use the exit callback to prevent a race between process exit and IO buffer flushing.

含义是：一旦使用 I/O 回调，原始 I/O 句柄即被回调消费，不能再通过 WslcGetProcessIOHandle 获取；同时必须同时注册 onExit 退出回调，否则进程退出与 I/O 缓冲区刷盘之间存在竞态。这是 C API 层相对“危险”的原始能力，需要开发者自行管理同步。

4.2 WinRT 的托管式隐藏

WinRT 投影把这些底层细节全部藏进 ProcessSettings 与 Process：

• ProcessSettings.OutputMode：Discard = 0、Stream = 1、Event（事件模式），见 wslcsdk.idl；
• Process.OutputReceived / Process.ErrorReceived / Process.Exited 三个事件（Process.h）；
• Process.GetInputStream() / GetOutputStream(outputHandle) 流式接口（Process.h）。

底层桥接逻辑在 Process.cpp 中清晰可见：

// ApplyCallbacksToSettings
auto settingsPtr = GetStructPointer(m_settings);
WslcProcessCallbacks callbacks = GetEventCallbacks();
winrt::check_hresult(WslcSetProcessSettingsCallbacks(settingsPtr, &callbacks, this));

以及等待退出的异步封装：

wil::unique_handle exitEventHandle;
winrt::check_hresult(WslcGetProcessExitEvent(ToHandle(), exitEventHandle.put()));
// Allow the wait to be cancelled even if suspended for resume_on_signal.
auto cancellation = co_await winrt::get_cancellation_token();
cancellation.enable_propagation();

即 WinRT 层在内部完成 WslcSetProcessSettingsCallbacks → 回调转发到 winrt::event → WslcGetProcessExitEvent → co_await 取消感知等待的完整链路。开发者只需订阅事件或读写流，无需关心句柄、竞态与回调生命周期（Process.h 中还有一条工程细节：m_process 句柄被刻意放在成员末尾以便最先释放，防止事件对象在可能仍被触发时被销毁，见 Process.h）。

4.3 对开发者的工程影响

• Event 模式（推荐）：订阅 OutputReceived/ErrorReceived/Exited，语义清晰、天然避免竞态，适合绝大多数业务；
• Stream 模式：通过 GetInputStream/GetOutputStream 获得 IInputStream/IOutputStream，适合把进程 I/O 接到管道、文件或网络流；
• 只有需要与 WaitForMultipleObjects、OVERLAPPED 等原生 Win32 同步机制协作时，才值得下沉到 C API 的 WslcGetProcessExitEvent 与 WslcGetProcessIOHandle——此时务必遵守“回调会消费句柄、必须同时注册 onExit”的约束。

---

五、差距四：WinRT 包装源文件的缺失与当前仓库现状

原文档记录的最后一项差距是“本版本快照中缺失的 WinRT 包装源文件”：构建脚本引用了 PullImageOptions、PushImageOptions、TagImageOptions、VhdOptions 与 ServiceVersion，但当时的 drop 中缺少对应实现文件。

需要特别说明的是，这一差距针对的是文档撰写时的代码快照；在当前仓库中，这些文件均已补齐。证据如下：

• winrt/CMakeLists.txt 与 winrt/CMakeLists.txt 的源文件/头文件列表中，PullImageOptions.cpp/.h、PushImageOptions.cpp/.h、TagImageOptions.cpp/.h、VhdOptions.cpp/.h、ServiceVersion.cpp/.h 全部在列；
• 这些文件也确实存在于 src/windows/WslcSDK/winrt 目录中；
• 对应的能力也已在 Session.h 中落地：PullImage/PullImageAsync、PushImage/PushImageAsync、TagImage、CreateVhdVolume 等均以 PullImageOptions、PushImageOptions、TagImageOptions、VhdOptions 为参数。

从这组现状可以推断，该条目属于历史快照的临时性缺口，而非设计上的长期差距。这也提示读者：查阅“known gaps”类文档时，应以当前仓库源码为准进行二次核实，避免基于过时快照做出错误的兼容性判断。

---

六、总结与实践建议

将四类差距汇总如下：

差距	C API 能力	WinRT 投影	影响与规避
镜像导入/加载	WslcImportSessionImage / WslcLoadSessionImage 支持 HANDLE 输入	仅 ImportImage / LoadImage 路径版本（内部走 FromFile 变体）	内存/流式镜像内容须落盘或改用 C API
容器启动 flags	WslcStartContainer 显式接收 WslcContainerStartFlags（ATTACH）	Container::Start() 无参数，按 OutputMode 隐式置位 ATTACH	WinRT 层无法自定义 flags
进程回调管道	WslcSetProcessSettingsCallbacks、WslcGetProcessExitEvent、WslcGetProcessIOHandle 原始句柄/回调	OutputMode + OutputReceived/ErrorReceived/Exited 事件 + 流接口	托管语义安全，原生同步场景需下沉 C API
WinRT 包装源文件缺失	—	当前仓库中 PullImageOptions 等 5 组文件均已存在	历史快照缺口，已补齐

给开发者的三条实操建议：

1. 默认走 WinRT 投影：OutputMode/事件/异步进度模型足够覆盖绝大多数容器编排需求，且规避了 C API 的回调竞态与句柄消费陷阱；
2. C API 作为逃生通道：遇到内存流镜像导入、自定义启动 flags、原生事件等待三类场景时，直接调用 wslcsdk.h 中的对应函数，并严格遵循头文件中的约束注释；
3. 以源码为最终依据：本仓库的 wslcsdk.idl（接口定义）、wslcsdk.h（C 声明）、wslcsdk.def（导出符号表）三者互相印证，是核实任何“已知差距”是否仍然成立的最可靠材料。