WSL 容器 API 的 Session APIs 全面指南用 Wslc 系列函数管理容器会话生命周期【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL本指南以 WSL 容器 APIWSL Container APIC 语言参考中的 Session APIs 为绝对核心完整讲解从会话初始化、资源配额设置、会话创建、终止监听、崩溃转储订阅到会话清理的全部 14 个 API 函数。你将掌握如何在 Windows 上以编程方式创建、配置、监控和销毁一个容器会话并深入理解WslcSessionSettings不透明结构的内部布局与wslcsdk实现层的默认值行为。文章末尾还给出可编译运行的完整生命周期示例帮你把每个 API 串成一条可落地的调用链。适用前提本 API 属于 Windows Subsystem for LinuxWSL的容器 SDK当前处于Preview 阶段见 C API 参考入口函数签名与行为可能在后续版本中无通知变更请勿在正式生产负载中依赖其稳定性。编译时需要wslcsdk.h头文件与wslcsdk.lib/wslcsdk.dll库头文件声明见 wslcsdk.h导出符号见 wslcsdk.def。一、Session APIs 全貌14 个函数的职责分组会话Session是 WSL 容器 API 中最顶层的资源抽象一个会话对应一台面向 Linux 容器负载的虚拟机运行环境容器Container创建在会话之内进程Process又运行在容器之内。Session APIs 负责回答如何把这样一台虚拟机拉起来、配好资源、监视其存亡、最后干净地关掉。Session APIs 索引 将全部 14 个函数分为五类类别函数职责会话设置初始化WslcInitSessionSettings创建并填充WslcSessionSettings结构必调第一步会话设置微调WslcSetSessionSettingsCpuCount设置 CPU 核数WslcSetSessionSettingsMemory设置内存上限MBWslcSetSessionSettingsTimeout设置引导超时毫秒WslcSetSessionSettingsVhd设置 VHD 存储需求WslcSetSessionSettingsFeatureFlags设置会话特性开关如 GPU会话生命周期WslcCreateSession基于设置创建会话返回WslcSession句柄WslcTerminateSession终止会话WslcReleaseSession释放会话句柄会话状态监控WslcGetSessionTerminationEvent获取会话终止事件句柄HANDLEWslcGetSessionTerminationReason查询终止原因崩溃转储订阅WslcRegisterSessionCrashDumpCallback注册崩溃转储回调WslcReleaseCrashDumpSubscription取消崩溃转储订阅会话内认证WslcSessionAuthenticate向会话内服务完成身份认证获取身份令牌典型调用顺序WslcInitSessionSettings→可选各WslcSetSessionSettings*→WslcCreateSession→ 使用会话创建容器/拉取镜像 → 监控终止事件 →WslcTerminateSession→WslcReleaseSession。二、会话设置初始化WslcInitSessionSettingsSTDAPI WslcInitSessionSettings(_In_ PCWSTR name, _In_ PCWSTR storagePath, _Out_ WslcSessionSettings* sessionSettings);参数类型方向说明namePCWSTRin待创建会话的名称storagePathPCWSTRin会话存储写入路径路径不存在时会自动创建sessionSettingsWslcSessionSettings*out接收设置的指针返回值HRESULT。该函数是会话编程的强制入口必须先调用它拿到一个合法的WslcSessionSettings之后才能调用任何WslcSetSessionSettings*系列函数或WslcCreateSession。若直接传入未初始化的栈结构底层实现会因内部类型指针无效而失败。2.1 会话名称的机器级可见性与安全约束文档特别强调了两点约束见 WslcInitSessionSettings会话名是机器级键会话名既是显示名也是全机器范围内标识会话的键。若同名会话已存在创建将失败并返回ERROR_ALREADY_EXISTS。全机器可见的信息以下信息对机器上所有用户可见——会话名称、创建会话的用户的 SID、创建会话的进程的 PID。安全警告不要在会话名中放置凭据或其他敏感信息。WslcSessionSettings sessionSettings; HRESULT hr WslcInitSessionSettings( Ldemo-session, LC:\\WSLC\\demo-session, sessionSettings);2.2 实现层做了什么不透明结构与默认值WslcSessionSettings在公开头文件中被定义为不透明opaque结构见 structures/wslcsessionsettings.md 与 wslcsdk.h#define WSLC_SESSION_OPTIONS_SIZE 72 #define WSLC_SESSION_OPTIONS_ALIGNMENT 8 typedef struct WslcSessionSettings { __declspec(align(WSLC_SESSION_OPTIONS_ALIGNMENT)) BYTE _opaque[WSLC_SESSION_OPTIONS_SIZE]; } WslcSessionSettings;从 wslcsdk.cpp 的实现可见WslcInitSessionSettings在内部将displayName与storagePath写入不透明缓冲区并一次性灌入四个默认值内部字段默认值来源cpuCount2Defaults.hmemoryMb2000约 2 GBDefaults.htimeoutMS3000005 分钟受HVSOCKET_CONNECT_TIMEOUT_MAX约束Defaults.hvhdRequirements.sizeBytes32ULL * 1024 * 1024 * 102432 GBDefaults.h这意味着即使你只调用WslcInitSessionSettings不做任何微调会话也已具备 2 核 CPU、2 GB 内存、5 分钟引导超时与 32 GB 存储的默认配额无需关心底层细节。三、会话资源配置五个 Set 系列函数所有WslcSetSessionSettings*函数都遵循同一约定第一个参数是被修改的WslcSessionSettings*返回HRESULT且必须在WslcInitSessionSettings之后、WslcCreateSession之前调用。3.1 CPU 核数WslcSetSessionSettingsCpuCountSTDAPI WslcSetSessionSettingsCpuCount(_In_ WslcSessionSettings* sessionSettings, _In_ uint32_t cpuCount);参数类型方向sessionSettingsWslcSessionSettings*incpuCountuint32_tinHRESULT hr WslcSetSessionSettingsCpuCount(sessionSettings, (uint32_t)4);实现细节wslcsdk.cpp当传入cpuCount非 0 时写入选定值传入 0 则回落为默认值s_DefaultCPUCount2。内存与超时函数遵循同样的0 值回落默认语义见下文因此 0 在这里不是一个合法的零核配置而是使用默认值的约定。3.2 内存上限WslcSetSessionSettingsMemorySTDAPI WslcSetSessionSettingsMemory(_In_ WslcSessionSettings* sessionSettings, _In_ uint32_t memoryMB);单位是MB。示例将内存设置为 4 GBHRESULT hr WslcSetSessionSettingsMemory(sessionSettings, (uint32_t)4096);实现wslcsdk.cppmemoryMB非 0 则写入为 0 则回落s_DefaultMemoryMB2000 MB。3.3 引导超时WslcSetSessionSettingsTimeoutSTDAPI WslcSetSessionSettingsTimeout(_In_ WslcSessionSettings* sessionSettings, _In_ uint32_t timeoutMS);单位是毫秒。示例将引导超时设为 2 分钟HRESULT hr WslcSetSessionSettingsTimeout(sessionSettings, (uint32_t)120000);实现wslcsdk.cpptimeoutMS非 0 则写入为 0 则回落s_DefaultBootTimeout300000 ms 5 分钟。该超时最终作用于底层 hvsocket 引导连接阶段Defaults.h注释表明其上限受HVSOCKET_CONNECT_TIMEOUT_MAX约束超时对慢速磁盘上的首次启动尤为重要。3.4 VHD 存储需求WslcSetSessionSettingsVhdSTDAPI WslcSetSessionSettingsVhd(_In_ WslcSessionSettings* sessionSettings, _In_opt_ const WslcVhdRequirements* vhdRequirements);参数类型方向sessionSettingsWslcSessionSettings*invhdRequirementsconst WslcVhdRequirements*in可选传入NULL表示不使用自定义 VHD 需求。WslcVhdRequirements结构定义见 structures/wslcvhdrequirements.md 与 wslcsdk.htypedef struct WslcVhdRequirements { _In_z_ PCSTR name; // 被 WslcSetSessionSettingsVhd 忽略 _In_ uint64_t sizeBytes; // 期望大小用于创建/扩容 _In_ WslcVhdType type; // WSLC_VHD_TYPE_DYNAMIC 或 WSLC_VHD_TYPE_FIXED _In_ WslcVhdRequirementsFlags flags; // WSLC_VHD_REQ_FLAG_NONE / WSLC_VHD_REQ_FLAG_OWNER _In_ uint32_t uid; // 仅当 (flags WSLC_VHD_REQ_FLAG_OWNER) 时生效 _In_ uint32_t gid; // 仅当 (flags WSLC_VHD_REQ_FLAG_OWNER) 时生效 } WslcVhdRequirements;头文件注释明确了两条关键语义wslcsdk.hname字段被WslcSetSessionSettingsVhd忽略type之后的字段flags/uid/gid只被WslcCreateSessionVhdVolume采纳WslcSetSessionSettingsVhd遇到非NONE的 flags 会返回E_INVALIDARG对应实现见 wslcsdk.cpp 之后的校验分支WSLC_VHD_TYPE_FIXED只被WslcCreateSessionVhdVolume尊重——在会话设置阶段请使用默认的WSLC_VHD_TYPE_DYNAMIC。也就是说在设置阶段WslcSetSessionSettingsVhd只关心sizeBytes用于声明会话磁盘的默认大小默认 32 GB见 Defaults.h完整的 VHD 创建语义固定/动态、属主 uid/gid在 Storage APIs 的WslcCreateSessionVhdVolume中体现。示例将默认存储扩容到 64 GBWslcVhdRequirements vhdRequirements { 0 }; vhdRequirements.name ignored-by-WslcSetSessionSettingsVhd; vhdRequirements.sizeBytes (uint64_t)64 * 1024 * 1024 * 1024; vhdRequirements.type WSLC_VHD_TYPE_DYNAMIC; vhdRequirements.flags WSLC_VHD_REQ_FLAG_NONE; vhdRequirements.uid (uint32_t)0; vhdRequirements.gid (uint32_t)0; HRESULT hr WslcSetSessionSettingsVhd(sessionSettings, vhdRequirements);3.5 特性开关WslcSetSessionSettingsFeatureFlagsSTDAPI WslcSetSessionSettingsFeatureFlags(_In_ WslcSessionSettings* sessionSettings, _In_ WslcSessionFeatureFlags flags);WslcSessionFeatureFlags枚举见 enumerations/wslcsessionfeatureflags.md 与 wslcsdk.h枚举值值含义WSLC_SESSION_FEATURE_FLAG_NONE0x00000000无特性WSLC_SESSION_FEATURE_FLAG_ENABLE_GPU0x00000004启用 GPU 加速启用 GPU 加速的示例HRESULT hr WslcSetSessionSettingsFeatureFlags( sessionSettings, WSLC_SESSION_FEATURE_FLAG_ENABLE_GPU);需要说明的是会话创建时SDK 实现还会无条件叠加两个内部特性——WslcFeatureFlagsVirtioFsvirtio-fs 文件系统与WslcFeatureFlagsDnsTunnelingDNS 隧道见 wslcsdk.cpp。因此该 API 暴露的是用户可控制的特性位与实现内部固定启用的特性是叠加关系。四、创建会话WslcCreateSessionSTDAPI WslcCreateSession(_In_ WslcSessionSettings* sessionSettings, _Out_ WslcSession* session, _Outptr_opt_result_z_ PWSTR* errorMessage);参数类型方向说明sessionSettingsWslcSessionSettings*in已初始化并配置好的设置sessionWslcSession*out接收新会话句柄errorMessagePWSTR*out可选失败时返回人类可读错误信息返回值HRESULT。WslcSession session NULL; HRESULT hr WslcCreateSession(sessionSettings, session, NULL);4.1 实现层的调用链从 wslcsdk.cpp 可以看到WslcCreateSession的完整内部流程通过CheckAndGetInternalType取出WslcSessionSettings内部字段创建兼容会话管理器IWSLCCompatSessionManager将公开字段映射为WSLCCompatSessionSettings运行时设置——MaximumStorageSizeMb由vhdRequirements.sizeBytes / 1MB计算得出、CpuCount、MemoryMb、BootTimeoutMs、NetworkingMode WSLCNetworkingModeConsommeConsomme 网络栈、FeatureFlags经ConvertFlags转换叠加 VirtioFs 与 DNS Tunneling 两个内部特性位调用sessionManager-CreateSession(...)真正拉起会话成功后通过ConfigureForCOMImpersonation配置 COM 模拟身份服务端进程管控的一部分并将句柄返回给调用者。会话句柄本身由DECLARE_HANDLE(WslcSession)声明wslcsdk.h对调用方是不透明句柄只能传给其他 Wslc API 使用。若CreateSession失败错误信息会写入可选的errorMessage参数调用方需用CoTaskMemFree释放。4.2 先决条件检查在调用WslcCreateSession之前官方端到端示例end-to-end-example.md还建议先通过WslcGetMissingComponents检查平台组件是否就绪缺失时提示运行wsl --installWslcComponentFlags missing WSLC_COMPONENT_FLAG_NONE; hr WslcGetMissingComponents(missing); if (FAILED(hr) || missing ! WSLC_COMPONENT_FLAG_NONE) { printf(WSL components are missing. Run: wsl --install\n); CoUninitialize(); return 1; }五、监控会话终止事件 原因查询5.1 获取终止事件WslcGetSessionTerminationEventSTDAPI WslcGetSessionTerminationEvent(_In_ WslcSession session, _Out_ HANDLE* terminationEvent);参数类型方向sessionWslcSessioninterminationEventHANDLE*out返回的HANDLE是标准 Windows 事件内核对象可直接用于WaitForSingleObject/WaitForMultipleObjects/SetThreadpoolWait等任意等待机制HANDLE terminationEvent NULL; HRESULT hr WslcGetSessionTerminationEvent(session, terminationEvent); if (SUCCEEDED(hr)) { WaitForSingleObject(terminationEvent, 1000); }5.2 查询终止原因WslcGetSessionTerminationReasonSTDAPI WslcGetSessionTerminationReason(_In_ WslcSession session, _Out_ WslcSessionTerminationReason* reason);参数类型方向sessionWslcSessioninreasonWslcSessionTerminationReason*outWslcSessionTerminationReason枚举见 enumerations/wslcsessionterminationreason.md 与 wslcsdk.h枚举值值含义WSLC_SESSION_TERMINATION_REASON_UNKNOWN0未知原因WSLC_SESSION_TERMINATION_REASON_SHUTDOWN1正常关闭WSLC_SESSION_TERMINATION_REASON_CRASHED2崩溃终止WslcSessionTerminationReason reason WSLC_SESSION_TERMINATION_REASON_UNKNOWN; HRESULT hr WslcGetSessionTerminationReason(session, reason);5.3 源码证据WinRT 层如何组合使用这两个 API在 SDK 的 WinRT 投影实现 winrt/Session.cpp 中Start()展示了标准的监控接线方式WslcCreateSession创建会话WslcGetSessionTerminationEvent取出终止事件CreateThreadpoolWaitSetThreadpoolWait把终止事件挂到线程池等待上当线程池回调OnTerminated触发时Session.cpp回调内部调用WslcGetSessionTerminationReason查询终止原因并向外抛出Terminated事件。可见事件句柄 终止原因查询这一对 API 正是上层封装事件模型的底层基石事件解决什么时候终止的同步问题原因枚举解决为什么终止的诊断问题。六、崩溃转储订阅回调注册与释放6.1 回调类型与信息结构回调类型定义见 callback-types/wslcsessioncrashdumpcallback.mdtypedef __callback void(CALLBACK* WslcSessionCrashDumpCallback)(_In_ const WslcSessionCrashDumpInfo* info, _In_opt_ PVOID context);回调携带的WslcSessionCrashDumpInfo结构见 structures/wslcsessioncrashdumpinfo.md 与 wslcsdk.h字段类型含义dumpPathPCWSTR转储文件路径宽字符processNamePCSTR崩溃进程名窄字符piduint32_t崩溃进程 PIDsignaluint32_t触发崩溃的信号timestampuint64_t时间戳6.2 注册回调WslcRegisterSessionCrashDumpCallbackSTDAPI WslcRegisterSessionCrashDumpCallback( _In_ WslcSession session, _In_ WslcSessionCrashDumpCallback crashDumpCallback, _In_opt_ PVOID crashDumpContext, _Out_ WslcCrashDumpSubscription* subscription, _Outptr_opt_result_z_ PWSTR* errorMessage);参数类型方向sessionWslcSessionincrashDumpCallbackWslcSessionCrashDumpCallbackincrashDumpContextPVOIDin可选subscriptionWslcCrashDumpSubscription*outerrorMessagePWSTR*out可选WslcCrashDumpSubscription是不透明句柄持有它就等于持有注册的存活期见 wslcsdk.h同一会话可注册多个订阅。头文件注释还强调该回调对任何持有活动会话的调用者都可用即不限于创建者便于独立监控进程挂接。void CALLBACK OnCrashDump(const WslcSessionCrashDumpInfo* info, PVOID context) { UNREFERENCED_PARAMETER(context); wprintf(Ldump%ls\n, info-dumpPath); } WslcCrashDumpSubscription subscription NULL; HRESULT hr WslcRegisterSessionCrashDumpCallback( session, OnCrashDump, NULL, subscription, NULL);6.3 释放订阅WslcReleaseCrashDumpSubscriptionSTDAPI WslcReleaseCrashDumpSubscription(_In_ WslcCrashDumpSubscription subscription);HRESULT hr WslcReleaseCrashDumpSubscription(subscription); subscription NULL;6.4 源码证据WinRT 层回调适配WinRT 投影 Session.cpp 中的OnCrashDump展示了回调的典型消费方式把 C 回调收到的WslcSessionCrashDumpInfo包装成ProcessCrashInformation托管对象再以事件形式抛给上层应用而Session::Close对应的析构流程会释放m_crashDumpSubscription。这印证了注册回调 → 收到信息 → 释放订阅的完整闭环。七、会话清理与收尾Terminate 与 Release7.1 终止会话WslcTerminateSessionSTDAPI WslcTerminateSession(_In_ WslcSession session);HRESULT hr WslcTerminateSession(session);实现wslcsdk.cpp若句柄对应的内部会话不存在返回HRESULT_FROM_WIN32(ERROR_INVALID_STATE)否则调用session-Terminate()。这是会话的主动关闭路径会触发终止事件置位使等待在WslcGetSessionTerminationEvent句柄上的代码得以唤醒。7.2 释放句柄WslcReleaseSessionSTDAPI WslcReleaseSession(_In_ WslcSession session);HRESULT hr WslcReleaseSession(session); session NULL;Terminate与Release的分工WslcTerminateSession负责让虚拟机停止运行WslcReleaseSession负责释放本地句柄引用。官方示例的收尾总是成对出现先WslcTerminateSession(session)再WslcReleaseSession(session)见 end-to-end-example.md。八、会话内认证WslcSessionAuthenticateSTDAPI WslcSessionAuthenticate( _In_ WslcSession session, _In_z_ PCSTR serverAddress, _In_z_ PCSTR username, _In_z_ PCSTR password, _Outptr_result_z_ PSTR* identityToken, _Outptr_opt_result_z_ PWSTR* errorMessage);参数类型方向说明sessionWslcSessionin目标会话serverAddressPCSTRin服务器地址如127.0.0.1:5000usernamePCSTRin用户名passwordPCSTRin密码identityTokenPSTR*out返回的身份令牌errorMessagePWSTR*out可选错误信息内存约定头文件注释明确identityToken由CoTaskMemAlloc分配必须用CoTaskMemFree释放。PSTR identityToken NULL; HRESULT hr WslcSessionAuthenticate( session, 127.0.0.1:5000, user, password, identityToken, NULL); if (SUCCEEDED(hr)) { printf(token%s\n, identityToken); CoTaskMemFree(identityToken); }该 API 用于在创建会话后与会话内暴露的服务例如镜像注册表服务建立身份获取后续操作所需的令牌。注意其地址、用户名、密码均为窄字符PCSTR而错误信息为宽字符PWSTR与WslcCreateSession的错误信息类型保持一致。九、端到端实战从初始化到清理的完整生命周期把上面的 API 串起来就是一个可编译运行的完整生命周期程序改编自官方 end-to-end-example.md下面对其做逐步注解。前置条件CoInitializeEx(nullptr, COINIT_MULTITHREADED)初始化 COM链接ole32.lib与wslcsdk.lib。#include winsock2.h #include windows.h #include stdio.h #include objbase.h #include filesystem #include wslcsdk.h #pragma comment(lib, ole32.lib) #pragma comment(lib, wslcsdk.lib) int main() { // Initialize COM CoInitializeEx(nullptr, COINIT_MULTITHREADED); HRESULT hr; PWSTR error nullptr; // 0. Check prerequisites先决条件检查组件缺失时提示 wsl --install WslcComponentFlags missing WSLC_COMPONENT_FLAG_NONE; hr WslcGetMissingComponents(missing); if (FAILED(hr) || missing ! WSLC_COMPONENT_FLAG_NONE) { printf(WSL components are missing. Run: wsl --install\n); CoUninitialize(); return 1; } WslcVersion ver {}; WslcGetVersion(ver); printf(WSL version: %u.%u.%u\n, ver.major, ver.minor, ver.revision); // 1. 初始化并创建会话本指南核心Session APIs std::filesystem::path storagePath std::filesystem::current_path(); WslcSessionSettings sessionSettings; hr WslcInitSessionSettings(LMyApp, storagePath.c_str(), sessionSettings); if (FAILED(hr)) return 1; // 可选自定义资源配额 WslcSetSessionSettingsCpuCount(sessionSettings, 4); WslcSetSessionSettingsMemory(sessionSettings, 4096); WslcSetSessionSettingsTimeout(sessionSettings, 120000); WslcSession session nullptr; hr WslcCreateSession(sessionSettings, session, error); if (FAILED(hr)) { wprintf(LSession creation failed: %s\n, error ? error : Lunknown); CoTaskMemFree(error); CoUninitialize(); return 1; } // 2. 拉取镜像Image APIs WslcPullImageOptions pullOpts {}; pullOpts.uri docker.io/library/alpine:latest; hr WslcPullSessionImage(session, pullOpts, error); if (FAILED(hr)) { wprintf(LPull failed: %s\n, error ? error : Lunknown); CoTaskMemFree(error); WslcTerminateSession(session); WslcReleaseSession(session); CoUninitialize(); return 1; } // 3. 配置 init 进程Process APIs WslcProcessSettings initProcSettings; WslcInitProcessSettings(initProcSettings); PCSTR argv[] { /bin/echo, Hello from WSL Container! }; WslcSetProcessSettingsCmdLine(initProcSettings, argv, 2); // 4. 配置并创建容器Container APIs WslcContainerSettings containerSettings; WslcInitContainerSettings(alpine:latest, containerSettings); WslcSetContainerSettingsName(containerSettings, hello-container); WslcSetContainerSettingsInitProcess(containerSettings, initProcSettings); WslcContainer container nullptr; hr WslcCreateContainer(session, containerSettings, container, error); if (FAILED(hr)) { wprintf(LContainer creation failed: %s\n, error ? error : Lunknown); CoTaskMemFree(error); WslcTerminateSession(session); WslcReleaseSession(session); CoUninitialize(); return 1; } // 5. 启动容器 hr WslcStartContainer(container, WSLC_CONTAINER_START_FLAG_NONE, error); if (FAILED(hr)) { wprintf(LStart failed: %s\n, error ? error : Lunknown); CoTaskMemFree(error); WslcDeleteContainer(container, WSLC_DELETE_CONTAINER_FLAG_FORCE, nullptr); WslcReleaseContainer(container); WslcTerminateSession(session); WslcReleaseSession(session); CoUninitialize(); return 1; } // 6. 等待 init 进程退出 WslcProcess initProc nullptr; hr WslcGetContainerInitProcess(container, initProc); if (SUCCEEDED(hr)) { HANDLE exitEvent nullptr; if (SUCCEEDED(WslcGetProcessExitEvent(initProc, exitEvent))) { WaitForSingleObject(exitEvent, 30000); // 30 秒超时 } INT32 exitCode 0; if (SUCCEEDED(WslcGetProcessExitCode(initProc, exitCode))) { printf(Process exited with code: %d\n, exitCode); } WslcReleaseProcess(initProc); } // 7. 清理停容器、删容器、终止并释放会话 WslcContainerState containerState WSLC_CONTAINER_STATE_INVALID; if (SUCCEEDED(WslcGetContainerState(container, containerState)) containerState WSLC_CONTAINER_STATE_RUNNING) { WslcStopContainer(container, WSLC_SIGNAL_SIGTERM, 10, nullptr); } WslcDeleteContainer(container, WSLC_DELETE_CONTAINER_FLAG_NONE, nullptr); WslcReleaseContainer(container); WslcTerminateSession(session); WslcReleaseSession(session); CoUninitialize(); return 0; }生命周期要点回顾初始化WslcInitSessionSettings是唯一合法起点同时写入默认配额配置各WslcSetSessionSettings*按需覆盖默认值传 0 回落默认创建WslcCreateSession拉起虚拟机并返回句柄失败时检查errorMessage使用在会话内进行镜像、容器、进程操作分属 Image/Container/Process APIs监控可选WslcGetSessionTerminationEventWslcGetSessionTerminationReason感知退出WslcRegisterSessionCrashDumpCallback收集崩溃转储清理先WslcTerminateSession再WslcReleaseSession顺序不可颠倒否则句柄泄漏或出现无效状态。十、常见错误与排查提示Session APIs 的所有函数均返回HRESULT通用的 Windows HRESULT如E_POINTER、E_INVALIDARG、ERROR_ALREADY_EXISTS、ERROR_INVALID_STATE之外还可能返回 WSL 容器专属错误码完整列表见 error-codes.md其中与会话场景最相关的是错误码十六进制值场景WSLC_E_SESSION_RESERVED0x80040607会话名被系统保留WSLC_E_INVALID_SESSION_NAME0x80040608会话名不合法WSLC_E_SESSION_NOT_FOUND0x8004060F会话不存在WSLC_E_VM_NOT_RUNNING0x80040610虚拟机未运行如尝试在已终止会话上操作WSLC_E_SDK_UPDATE_NEEDED0x8004060B主机 WSL 组件与 SDK 版本不匹配排查建议创建失败优先检查WslcGetMissingComponents返回值与errorMessage确认会话名在机器上唯一且不含敏感信息配额未生效确认传入值非 00 会回落默认值且所有WslcSetSessionSettings*都在WslcCreateSession之前调用终止监听失效确认先WslcGetSessionTerminationEvent再开始等待且WslcTerminateSession或崩溃路径确实触发内存泄漏errorMessage与identityToken均需CoTaskMemFree会话句柄必须WslcReleaseSession崩溃订阅必须WslcReleaseCrashDumpSubscription。延伸阅读C API 参考总入口结构、枚举、回调类型与全部 API 分组Structures 参考WslcSessionSettings、WslcVhdRequirements、WslcSessionCrashDumpInfo等Enumerations 参考特性标志、终止原因、VHD 类型等枚举全集Error Codes全部 WSL 容器专属错误码End-to-End Example官方完整生命周期示例SDK 头文件所有公开 API 声明与头文件注释SDK 实现WslcInitSessionSettings/WslcCreateSession/WslcTerminateSession等核心实现默认值定义CPU、内存、超时、存储的默认配额WinRT 投影示例终止事件与崩溃回调在高层 API 中的消费方式【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考