ContextMenuForWindows11 安装实战：VC++ 运行库、Developer Mode 与 PowerShell 注册 MSIX 全流程

• 桌面应用

本文基于仓库安装文档 install.md 展开，面向 Windows 11 用户完整讲解 ContextMenuForWindows11 的离线安装流程：为什么需要 VC++ 2015-2022 运行库、为什么要开启 Developer Mode、Set-ExecutionPolicy与Install.ps1每一步在做什么，以及如何用仓库中的包清单、CLSID 和示例菜单 JSON 验证安装结果。读完后你可以独立完成从环境准备到右键菜单生效的全部操作，并能理解每一步背后的工程原因。

一、安装前准备：为什么需要 VC++ 运行库

安装文档的第一个前置条件（仅标注适用于 1.2.9 之前的版本，新版包若未自带对应运行库组件时同样建议确认已安装）：

winget install Microsoft.VC++2015-2019Redist-x64

或者从微软官方 "Visual C++ Redistributable" 文档页手动下载安装。

这条要求来自项目的宿主组件。从源码结构看，ContextMenuCustomHost是一个 C++ 动态库工程，ContextMenuCustomHost.vcxproj 中可以看到：

• ConfigurationType为DynamicLibrary，即产物是ContextMenuCustomHost.dll；
• 使用Microsoft.Windows.CppWinRT与Microsoft.Windows.ImplementationLibrary两个 NuGet 包，依赖 C++ 运行时（项目通过RuntimeLibrary指定/MT静态链接，但 CppWinRT/WIL 生态及系统组件加载仍要求系统具备完整的 VC++ 运行库环境）；
• 链接器配置了ModuleDefinitionFile指向 Source.def，按 COM 组件方式导出类工厂。

这个 DLL 正是 Windows 11 新版右键菜单（IExplorerCommand）的宿主：包清单里以Path="ContextMenuCustomHost.dll"的形式声明 COM 代理类，资源管理器在右键时会加载它。因此系统缺少 VC++ 运行库时，菜单项无法正常工作，安装文档才会把运行库列为第一步。

二、开启 Developer Mode（开发者模式）

安装文档给出的路径（Windows 11 实际界面中该开关已归入 “隐私和安全 → 对于开发人员” 或 “系统 → 开发者选项”，以系统版本为准）：

Win Start > Settings > Privacy > For Developers > Developer Mode

为什么必须开启它？从包工程可以确认三个关键点：

1. 包使用自签名证书，而非 Microsoft 商店证书。ContextMenuCustomDevPackage.wapproj 中AppxPackageSigningEnabled为True、AppxBundlePlatforms为x64，发布者为CN=ikas-mc-dev（见 Package.appxmanifest 的Identity节点）。自签名的 MSIX 只有在开启 Developer Mode 后才能注册到系统；
2. 包依赖runFullTrust受限能力。Package.appxmanifest 的Capabilities节点声明了rescap:Capability Name="runFullTrust"。这是 UWP/Windows 运行时桌面桥接（Desktop Bridge）包的特有权限，允许宿主 DLL 以完整信任方式运行，而该权限的本地注册同样受开发者模式约束；
3. 应用入口是AppContainerExe。ContextMenuCustomApp.csproj 中OutputType为AppContainerExe、TargetPlatformIdentifier为UAP，即应用本体是 Windows 运行时（WinRT/UWP）应用，必须通过 MSIX 注册机制安装，而不是“双击 exe”的传统安装方式。

三、PowerShell 安装步骤逐行解析

安装文档的核心操作：

1. 解压发布包 zip；
2. 打开 PowerShell；
3. 执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ./Install.ps1 Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope CurrentUser

逐行说明：

注意事项：

• 三条命令建议按顺序在同一 PowerShell 窗口中执行，且 PowerShell 位于解压后的目录下，否则./Install.ps1会找不到文件；
• 若系统策略拦截脚本，可改用powershell -ExecutionPolicy Bypass -File .\Install.ps1一次性放行（Bypass仅作用于该次调用，不改变策略）；
• 注册过程不需要管理员 PowerShell，但部分受管系统（域控机器）可能限制 MSIX 注册，此时需要确认本地策略允许安装应用包。

四、仓库里的包结构：三种包与三个 CLSID

README.md 的 Download 表格说明项目有三种发布渠道：商店包（...m9vp3t2f55f5t.Msixbundle）、GitHub 包（ContextMenuCustomGithubPackage）、开发包（ContextMenuCustomDevPackage），并明确“从 v3.8 起，三种包可以共存”。这一点从源码可以得到精确印证——每个包使用不同的 COM CLSID注册同一个宿主 DLL，因此互不冲突：

对应清单文件分别为 ContextMenuCustomPackage/Package.appxmanifest、ContextMenuCustomGithubPackage/Package.appxmanifest、ContextMenuCustomDevPackage/Package.appxmanifest 与 ContextMenuCustomAnyPackage/Package.appxmanifest。四个清单的注册结构完全一致，都以windows.fileExplorerContextMenus扩展把同一个 CLSID 挂到四类上下文：Directory（目录）、*（文件）、Directory\Background（空白处）、Drive（驱动器根），再通过com:Extension把 CLSID 映射到ContextMenuCustomHost.dll（线程模型STA）。

以 GitHub 包清单为例（ContextMenuCustomGithubPackage/Package.appxmanifest）：

<desktop4:Extension Category="windows.fileExplorerContextMenus"> <desktop4:FileExplorerContextMenus> <desktop5:ItemType Type="Directory" > <desktop5:Verb Id="CustomMenu" Clsid="EB9DD180-53C8-4E8E-B61F-36FDD0D0CD13" /> </desktop5:ItemType> <desktop5:ItemType Type="*" > <desktop5:Verb Id="CustomMenu" Clsid="EB9DD180-53C8-4E8E-B61F-36FDD0D0CD13" /> </desktop5:ItemType> <desktop5:ItemType Type="Directory\Background"> <desktop5:Verb Id="CustomMenu" Clsid="EB9DD180-53C8-4E8E-B61F-36FDD0D0CD13" /> </desktop5:ItemType> <desktop10:ItemType Type="Drive"> <desktop10:Verb Id="CustomMenu" Clsid="EB9DD180-53C8-4E8E-B61F-36FDD0D0CD13" /> </desktop10:ItemType> </desktop4:FileExplorerContextMenus> </desktop4:Extension> <com:Extension Category="windows.comServer"> <com:ComServer> <com:SurrogateServer DisplayName="Custome Context Menu (Github)"> <com:Class Id="EB9DD180-53C8-4E8E-B61F-36FDD0D0CD13" Path="ContextMenuCustomHost.dll" ThreadingModel="STA"/> </com:SurrogateServer> </com:ComServer> </com:Extension>

清单中还可以看到：

• 最低系统要求Windows.Desktop为10.0.17763.0，即 Windows 10 1809 及以上，Windows 11 完全满足；
• 开发包与 GitHub 包额外声明了windows.appExecutionAlias扩展，暴露customeContextMenuDebug.exe调试别名（ContextMenuCustomDevPackage/Package.appxmanifest），方便开发调试，Any 包没有该别名；
• 版本以四段式Version="5.8.1.0"形式声明，update-version.ps1 脚本会批量修改四个包的构建号，可用来了解包的版本管理方式。

如果Install.ps1不可用，也可以在 PowerShell 中手动完成注册（以某个包目录为例）：

Add-AppxPackage -Path .\ContextMenuCustomGithubPackage.msix

前提是 Developer Mode 已开启，且.msix证书被接受（自签名包在开发者模式下会提示信任，或证书已导入）。

五、安装后验证：注册状态、菜单目录与生效机制

5.1 验证包注册状态

在 PowerShell 中确认应用包已注册：

Get-AppxPackage *ContextMenu*

正常情况下应看到Custom Context Menu (Github)/Custom Context Menu (Dev)等条目。再打开资源管理器，在文件、目录、空白处或驱动器根目录上右键，应出现应用声明的菜单项（标题默认读取Custom_Menu_Name配置，缺省为 “Open With”，逻辑见 CustomExplorerCommand.cpp）。

5.2 菜单 JSON 存放在哪里

菜单配置文件保存在当前用户的本地数据目录%LocalAppData%\<包身份>\LocalState\custom_commands\下，这一点在三处源码中得到交叉印证：

• C++ 侧宿主直接读取该目录：CustomExplorerCommand.cpp 中AppDataPaths::GetDefault().LocalAppData()拼接custom_commands子目录，仅加载.json文件；
• C# 侧管理界面同样以custom_commands为目录名：MenuService.cs 的CreateDefualtMenusFolderAsync()在ApplicationData.Current.LocalFolder下创建该目录；
• 启用/停用菜单仅靠文件后缀区分：.json为启用，.json.disabled为停用（IsEnabled/IsDisabled方法）。

5.3 缓存如何加速右键菜单

从源码结构看，宿主在GetState阶段优先读取ApplicationData的menus容器缓存（CustomExplorerCommand.cpp），只有缓存为空时才回退到扫描custom_commands目录读文件。缓存由应用主程序在保存菜单时写入——MenuService的BuildToCacheAsync()（MenuService.cs）把每个启用的 JSON 内容按索引写入同一menus容器，C# 与 C++ 两侧因此共享同一份ApplicationData本地设置。这解释了为什么新导入菜单后，建议打开一次应用主界面（菜单管理页）让缓存刷新，右键菜单才会立即生效。

5.4 用一个示例菜单完成端到端验证

仓库自带 menuSample/ 示例目录，配置文件结构可用 menu.schema.json 校验。以计算 MD5 的示例 Calculate Md5 By PowerShell.json 为例：

{ "title": "Calculate MD5", "index": 3, "exe": "powershell", "param": "-noexit -Command Get-FileHash -LiteralPath \"\\\"{path}\\\"\" -Algorithm MD5 | format-list", "icon": "\"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe\",0", "acceptDirectoryFlag": 0, "acceptFileFlag": 4, "acceptExts": "*", "acceptFileRegex": "", "acceptMultipleFilesFlag": 2, "pathDelimiter": "\"\\\"", "paramForMultipleFiles": "-noexit -Command Get-FileHash -LiteralPath \"\\\"{path}\\\"\" -Algorithm MD5 | format-list", "showWindowFlag": 0 }

字段含义与 menu.schema.json 一一对应：exe支持环境变量与shell:AppsFolder\...形式；param中{path}为所选文件绝对路径、{parent}为父目录、{name}/{extension}为文件名与扩展名，多文件合并模式（acceptMultipleFilesFlag: 2，Join）下用{path0}/{name0}取第一个文件；acceptDirectoryFlag是位掩码（1=Directory、2=Background、4=Desktop、8=Drive）；acceptFileFlag中 4 表示接受所有文件；showWindowFlag控制窗口显示方式（-1 隐藏、0 正常、1 最小化、2 最大化）。

另一个值得对照的示例是 Compress By 7z.json，它展示了目录/空白处场景与多文件打包参数：

{ "title": "Compress By 7z", "index": 10, "exe": "\"C:\\Program Files\\7-Zip\\7zG.exe\"", "param": "a -ad \"{parent}\\{name}.7z\" \"{path}\"", "acceptDirectoryFlag": 7, "acceptFileFlag": 4, "acceptMultipleFilesFlag": 2, "paramForMultipleFiles": "a -ad \"{parent}\\{name0}.7z\" {path}" }

其中acceptDirectoryFlag: 7（= 1+2+4）表示目录、目录空白处、桌面三类场景都显示该菜单；paramForMultipleFiles中使用{name0}说明压缩包名取自第一个文件名——这些变量在宿主 CustomSubExplorerCommand.cpp 的参数替换逻辑中完成渲染。

把示例文件放入custom_commands目录（或通过应用管理界面导入）、打开一次应用主界面后，在任意文件上右键即可验证整条链路：MSIX 注册 → 宿主 DLL 加载 → JSON 解析 → 菜单渲染与命令执行。

六、常见问题与限制说明

• 右键菜单不出现：先确认Get-AppxPackage能查到包，再确认 Developer Mode 未被关闭（关闭后自签名包会被系统移除，菜单随之消失）；接着打开一次应用管理界面，触发menus缓存重建（对应BuildToCacheAsync逻辑）。
• ./Install.ps1报“无法加载，因为在此系统上禁止运行脚本”：说明当前执行策略未放行，按第三节先执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，或使用-ExecutionPolicy Bypass -File方式单次运行。
• 安装位置与版本：本文以当前仓库源码为准，四个包清单中Version均为5.8.1.0，最低Windows.Desktop为10.0.17763.0；包只支持 x64（AppxBundlePlatforms为x64）。若你安装的是更早版本，请特别注意 1.2.9 之前版本对 VC++ 运行库的强制依赖。
• 卸载：通过 “设置 → 应用 → 已安装的应用” 找到 Custom Context Menu 对应条目卸载即可；custom_commands菜单配置随包身份目录保留于用户本地数据区，重新安装后仍可继续使用（此行为从ApplicationData存储结构推断，卸载后目录残留情况以系统实现为准）。

按 install.md 的顺序完成“运行库 → Developer Mode → PowerShell 安装”三步，再对照第四、五节的包身份、CLSID 与custom_commands目录做验证，即可完整掌握 ContextMenuForWindows11 从部署到菜单生效的全过程。

• 桌面应用