SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场winapp-frameworks

winapp-frameworks

编程与开发

查看项目

更新于 10-16 10:35

技能介绍

本技能用于在特定应用框架下使用 winapp 时，提供对应的工作流、安装方式和命令。适合需要了解某个框架应如何安装、构建、打包和调试 Windows 应用的场景。

一、何时使用 当处理特定应用框架并需要了解正确的 winapp 工作流时使用；当需要选择正确的安装方式（npm 包还是独立 CLI）时使用；当需要按框架查找逐步的设置、构建与打包指南时使用。每个框架都有详细指南，应参考对应链接而不是自行猜测命令。

二、各框架安装方式 Electron：npm install --save-dev @microsoft/winappcli .NET（WPF、WinForms、Console）：winget install Microsoft.winappcli .NET MAUI：winget install Microsoft.winappcli C++（CMake、MSBuild）：winget install Microsoft.winappcli Rust：winget install Microsoft.winappcli Flutter：winget install Microsoft.winappcli Tauri：winget install Microsoft.winappcli

三、各框架关键差异

  1. Electron 使用 npm 包（@microsoft/winappcli），而不是独立 CLI。该 npm 包包含：捆绑在 node_modules 内的原生 winapp CLI 二进制；一个用于创建原生 C#/C++ 插件的 Node.js SDK；npx winapp node 下的 Electron 专用命令；生成的 JS 绑定（.winapp/bindings/），用于从 JavaScript 直接访问 Windows App SDK API。 快速开始： npm install --save-dev @microsoft/winappcli npx winapp init . --use-defaults --add-js-bindings npx winapp node create-addon --template cs npx winapp node add-electron-debug-identity Windows 集成指引：可使用 JS 绑定从 JavaScript 直接调用 Windows App SDK API，而无需原生插件（例如 AI API、通知、文件选择器）；带 .winmd 元数据的自定义 WinRT 组件也可通过 package.json 中的 winapp.jsBindings.additionalWinmds 添加。当需要 Win32/COM API、第三方 C++ 库或 .NET 程序集时使用原生插件：--template cpp 用于 C++（node-gyp），--template cs 用于 C#。在一个 Electron 应用中混用 JS 绑定和原生插件没有问题。修改 package.json 中的 winapp.jsBindings 后，用 npx winapp node generate-bindings 重新生成；修改 winapp.yaml 后，先运行 npx winapp restore。
  2. .NET（WPF、WinForms、Console）：.NET 项目可直接访问 Windows API。关键差异：引用了 Microsoft.Windows.SDK.BuildTools 或 Microsoft.WindowsAppSDK NuGet 包的项目不需要 winapp.yaml，winapp 会从 .csproj 自动检测 SDK 版本；关键前置条件是 Package.appxmanifest，而不是 winapp.yaml；无需原生插件步骤。winapp init 会自动添加 Microsoft.Windows.SDK.BuildTools.WinApp NuGet 包，从而实现带自动身份注册的 dotnet run。dotnet run 后写入的参数会传给启动的应用，与未安装该包时一致；启动器本身通过 WinAppRun* MSBuild 属性配置。示例：dotnet run -p:WinAppRunDetach=true --app-arg。当应用的标志同时也是 dotnet run 选项（--configuration、--framework、--project、-c、-f、-r 等）时使用 --，例如 dotnet run -- --configuration Release。如果已有 Package.appxmanifest，可能不需要 winapp init。 快速开始： winapp init . --use-defaults dotnet build <path-to-project.csproj> -c Debug -p:Platform=x64 winapp run bin\x64\Debug<tfm>\win-x64\
  3. .NET MAUI：一个重要特性是已签入的 Platforms/Windows/Package.appxmanifest 充满 $placeholder$ 标记，winapp package 不会解析它们。MAUI 的 resizetizer 在构建/发布时将其填充到生成的清单中（resizetizer 清单位于 obj<Config><TFM><RID>\resizetizer\m\Package.appxmanifest，完全解析的输出清单位于 bin<Config><TFM><RID>\AppxManifest.xml）。应先发布 Windows 头，再用 winapp package --manifest 指向生成的清单，绝不能指向源清单。
  4. C++（CMake、MSBuild）：C++ 项目主要用 winapp 处理 SDK 投影（CppWinRT 头文件）和打包。winapp init --setup-sdks stable 会下载 Windows SDK + App SDK 并生成 CppWinRT 头文件；头文件在 .winapp/generated/include；响应文件在 .cppwinrt.rsp；需将 .winapp/packages 加入构建系统的 include/lib 路径。Visual Studio 项目使用 winapp run .\MyApp.vcxproj；CMake 项目则运行其构建输出文件夹。
  5. Rust：使用 windows crate 获取 Windows API 绑定；winapp 处理清单、身份、打包和证书管理；典型构建输出为 target/release/myapp.exe。
  6. Flutter：Flutter 负责构建（flutter build windows）；winapp 负责清单、身份、打包；构建输出为 build\windows\x64\runner\Release\。
  7. Tauri：Tauri 有自己的 .msi 打包器；winapp 专门用于 MSIX 分发和包身份功能；winapp 提供了超出 Tauri 内置打包器的能力（身份、稀疏包、Windows API 访问）。

四、按框架调试 .NET：winapp run .\bin\x64\Debug<tfm>\win-x64\，先用 dotnet build -c Debug -p:Platform=x64 构建；GUI 应用通过 AUMID 启动，控制台应用自动通过执行别名启动。 C++：winapp run .\MyApp.vcxproj 或 winapp run .\build\Debug，.vcxproj 先由 MSBuild 构建；控制台应用会被检测并自动通过执行别名启动。 Rust：winapp run .\target\debug，控制台应用自动通过执行别名启动。 Flutter：winapp run .\build\windows\x64\runner\Debug，GUI 应用，直接 winapp run 即可。 Tauri：winapp run .\dist，先将 exe 暂存到 dist/；GUI 应用。 Electron：npx winapp node add-electron-debug-identity，使用 Electron 专用身份注册，不推荐对 Electron 使用 winapp run。 关键规则：GUI 应用（Flutter、Tauri、WPF）使用 winapp run <build-output>，通过 AUMID 激活启动；控制台应用（C++、Rust、.NET console）直接 winapp run <build-output>，winapp 从二进制 PE 子系统检测到控制台应用并通过执行别名启动，stdin/stdout 可到达终端，它会将所需的 uap5:ExecutionAlias 直接写入 AppX 布局，无需编辑清单；传 --without-alias 可强制改用 AUMID 激活，--with-alias 只为窗口化应用强制使用别名。Electron 使用不同机制。启动调试可用 winapp create-debug-identity <exe>。

五、相关技能 包括 winapp-setup、winapp-manifest、winapp-signing、winapp-package、winapp-identity、winapp-maui、winapp-troubleshoot。运行 winapp <command> --help 查看当前命令选项，或 winapp --cli-schema 获取完整机器可读命令架构。