需求:打包安装包;协议在**安装时**注册(不依赖先启动软件一次);卸载能清掉注册。
实现(desktop/installer/):
- Product.wxs(WiX 5):
- Scope=perUser(免管理员、无 UAC),安装到 %LOCALAPPDATA%\Programs\YuncangTrace;
- Component 里写 HKCU\Software\Classes\yuncang(默认值 / URL Protocol / shell\open\command),
注册表项属于 MSI 组件 → **卸载时自动删除**,即「取消注册」;
- 开始菜单快捷方式(RemoveFolder On=uninstall);
- MajorUpgrade(升级替换、拒绝降级);用户数据 settings/session.json 不在安装目录,卸载保留。
- 版本号用 $(var.Version) 由构建命令注入,避免和 csproj 两处维护。
- build.ps1:读取 csproj 的 <Version> → dotnet publish(自包含单文件)→ wix build
→ out\YuncangTraceSetup-<版本>.msi。
⚠️ 脚本保存为 UTF-8 with BOM:PowerShell 5.1 读无 BOM 脚本会按 GBK 解析,中文注释会让语法报错。
- 工具链:`dotnet tool install --global wix --version 5.0.2`
(WiX v7 会要求接受 OSMF 付费维护费协议,改用 v5)。
实测(perUser 静默安装 → 协议 → 唤起 → 卸载):
- 安装:文件落到 %LOCALAPPDATA%\Programs\YuncangTrace,HKCU 协议立即指向安装目录
(安装前指向 desktop\publish,安装后被正确覆盖),开始菜单快捷方式已创建;
- **不启动软件**,直接 Start-Process "yuncang://open?code=INSTALLTEST":
进程路径 = 安装目录 exe,日志显示 "已恢复登录:管理员 → 收到启动协议 → 查询:INSTALLTEST";
- 卸载:安装目录删除、HKCU 协议删除、开始菜单删除,均无残留;
- build.ps1 完整跑通,产物 54.1 MB(cab 压缩)。
.gitignore:忽略 desktop/installer/out/ 与 *.wixpdb。
desktop/README.md:新增「打安装包(MSI)」章节(构建命令、安装范围、协议注册/卸载行为、
perMachine 改法、BOM 提醒)。
18 KiB
云仓视频溯源软件(本机服务 / WPF)
Windows 桌面端,用前端 /local 公共页和 Chrome 插件做对接:
- 登录页:账号密码登录后端(
POST /api/web/auth/login)拿 user JWT,令牌存本机; 下次启动先用/api/web/me验证,还有效就直接进主界面; - 在
127.0.0.1:17300起一个本机 HTTP 服务,浏览器里的页面直接查询本机数据; - 注册
yuncang://启动协议,网页可以「叫醒」本软件(前提是已安装); - 托盘图标:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口, 右键菜单有「打开主界面 / 服务地址 / 退出」;
- 防多开:全局互斥体 + 命名管道 —— 第二个实例不会抢 17300 端口,而是把
yuncang://open?code=xxx转给已运行的实例(在托盘里也会被叫出来并直接查询),然后自己退出。
desktop/
├── YuncangTrace.LocalService.csproj # net8.0-windows + UseWPF + UseWindowsForms(托盘)
├── app.manifest # 高 DPI / 兼容性声明
├── Assets/app.ico # 程序/托盘图标(tools/make-icon.ps1 生成)
├── App.xaml / App.xaml.cs # 防多开 + 托盘 + 登录流程 + 本机服务生命周期
├── LoginWindow.xaml / .xaml.cs # 服务器地址 / 账号 / 密码 / 记住账号 / 自动恢复登录
├── MainWindow.xaml / .xaml.cs # 服务状态、地址、协议注册、测试查询、日志、退出登录
└── Services/
├── LocalHttpServer.cs # HttpListener + CORS + PNA
├── OrderQueryService.cs # ★ 按运单号查数据(接真实数据源的地方)
├── ApiClient.cs # 登录 / 校验令牌(用到的全部后端接口)
├── SessionStore.cs # 登录态(%LOCALAPPDATA%\YuncangTrace\session.json)
├── AppSettings.cs # 服务器地址 / 记住账号(%LOCALAPPDATA%\YuncangTrace\settings.json)
├── ProtocolHelper.cs # yuncang:// 注册/反注册、解析 code
├── SingleInstance.cs # 互斥体 + 命名管道转发参数(防多开)
├── TrayIconService.cs # 托盘图标与菜单
├── AppLog.cs # 全局日志缓冲(窗口没开时的日志也不丢)
└── JsonUtil.cs # JSON 序列化(中文不转义)
登录 / 托盘 / 防多开的行为
| 场景 | 行为 |
|---|---|
| 首次启动 | 先起本机服务(17300)与托盘,再弹登录页 → 登录成功才出主窗口 |
| 已有令牌 | 登录窗一闪而过:/api/web/me 通过就直接进主窗口;失效则清掉令牌留在登录页 |
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 yuncang://open?code=… 通过命名管道转给已运行实例 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
网页请求唤起登录(POST /api/activate-login) |
未登录:登录窗弹到最前;已登录:主界面弹到最前(不影响本机服务) |
| 托盘右键「退出」 | 真正退出(dispose 托盘与本机服务) |
环境配置(开发 / 生产)
和前端 VITE_BACKEND 一个思路:由构建决定,不靠用户手填。
| 构建 | env |
默认后端 |
|---|---|---|
dotnet build(Debug) |
Development |
http://127.0.0.1:7300(= 前端 dev 代理的后端) |
dotnet build -c Release |
Production |
https://packs.example.com(占位,打包时必须覆盖) |
打包正式版时指定真实域名:
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com -o publish
优先级(从高到低):
- 启动参数
--server=http://192.168.1.10:7300(临时,不落盘); - 环境变量
YUNCANG_SERVER; -p:ServerBaseUrl=注入的构建默认值;- 用户在登录页手改并保存的地址(
settings.json)。
几个细节:
- 地址等于内置默认值时,
settings.json里存空串 —— 所以换 Debug/Release 构建能自动跟随, 不会被上一次构建的默认值钉死;只有用户手改过的地址才会持久化。 - 换地址后不会复用旧令牌(
session.json里的ServerBaseUrl对不上就要求重新登录)。 GET /api/health会回env和server,排查环境是否装错时先看这两个字段。
环境要求
- 编译:.NET 8 SDK(
dotnet --list-sdks能看到8.x) - 只运行已发布的 exe:.NET 8 Desktop Runtime(不需要 SDK)
本机 SDK 装在用户目录(免管理员):
%LOCALAPPDATA%\Microsoft\dotnet, 已加入用户PATH和DOTNET_ROOT。新开的终端才能直接用dotnet; 老终端里临时用:$env:DOTNET_ROOT="$env:LOCALAPPDATA\Microsoft\dotnet"; $env:Path="$env:DOTNET_ROOT;$env:Path"。 直接双击bin\...\*.exe也需要DOTNET_ROOT已生效(否则报 “You must install .NET”)。 官方安装包:winget install --id Microsoft.DotNet.SDK.8 -e(要 UAC)。
构建 / 运行 / 发布
cd desktop
dotnet build # 编译(Debug = 开发环境,连本地 7300)
dotnet build -c Release # 编译(Release = 生产环境,默认地址见上一节)
dotnet run # 直接跑(调试)
# ★ 发给用户、以及要用「网页叫醒」的话,必须用自包含发布
dotnet publish -c Release -r win-x64 --self-contained true `
-p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true `
-p:ServerBaseUrl=https://正式域名 -o publish
为什么要自包含:dotnet build 出来的 exe 是 framework-dependent 的,
它自己会去找 C:\Program Files\dotnet 或 DOTNET_ROOT。从浏览器/资源管理器/协议拉起的进程
拿不到我们临时设的环境变量,于是弹「You must install .NET Desktop Runtime」——
网页上表现就是「唤起没反应 / 弹安装提示」。
自包含单文件(约 154 MB)把运行时打进去了,双击和协议唤起都能直接跑,用户什么都不用装。
desktop/nuget.config指向华为云 NuGet 镜像(本机访问不了 api.nuget.org)—— 自包含发布要下载Microsoft.*.App.Runtime.win-x64运行时包,没有镜像会 restore 失败。
开发阶段想让 bin\Debug 的 exe 也能直接双击,两个办法:装官方 SDK/Desktop Runtime 到标准位置,
或者每次用发布产物验证唤起。
打安装包(MSI)
desktop/installer/ 下是安装包定义(WiX 5,免费;WiX v6+ 需要 OSMF 付费协议,别装最新版)。
# 工具只需装一次
dotnet tool install --global wix --version 5.0.2
cd desktop\installer
.\build.ps1 -ServerBaseUrl https://正式域名
# → out\YuncangTraceSetup-<版本>.msi(约 54 MB,cab 压缩)
build.ps1 做两件事:先 dotnet publish(自包含单文件,不依赖运行时)→ 再 wix build。
版本号取自 csproj 的 <Version>,改版本只改那一处。
安装包行为:
| 项 | 说明 |
|---|---|
| 安装范围 | perUser(免管理员、无 UAC),装到 %LOCALAPPDATA%\Programs\YuncangTrace |
| 启动协议 | 安装即注册 yuncang://(HKCU),不需要先启动软件 |
| 卸载 | MSI 自动删除 exe、协议注册、开始菜单 —— 即「取消注册」 |
| 升级 | MajorUpgrade:装新版会替换旧版;降级被拦 |
| 用户数据 | %LOCALAPPDATA%\YuncangTrace\{settings,session}.json 卸载不删(重装后仍保持设置/登录) |
msiexec /i out\YuncangTraceSetup-1.0.0.msi # 安装
msiexec /x out\YuncangTraceSetup-1.0.0.msi # 卸载
需要「本机所有用户都能用」时:
Product.wxs里Scope改perMachine、注册表根改HKLM, 安装时会要管理员权限(UAC)。默认的 perUser 更省事,也够用(软件数据本来就是按用户存的)。
⚠️
build.ps1必须保存为 UTF-8 with BOM:PowerShell 5.1 读无 BOM 的脚本会按 GBK 解析, 中文注释直接把语法搞崩。
本机接口(前端 /local 页用的就是这两个)
服务固定监听 http://localhost:17300(端口写在前端页面与插件里)。
代码里同时注册了 http://127.0.0.1:17300/ 前缀 —— HttpListener 只接受「注册过的 host」,
不注册的话用 127.0.0.1 访问会直接被回 400(前端改 VITE_LOCAL_SERVICE 时就会碰到)。
浏览器直接打开 http://localhost:17300/ 会看到一个说明页(列了接口,方便排查)。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/query/{code} |
查信息,同时把服务/登录状态一起返回(见下)。没登录 → 401 state:need-login |
| POST | /api/activate-login |
把本机软件的登录窗叫到前台(已登录时把主界面叫到前台)。网页收到 need-login 时自动调它 |
为什么没有单独的「探活 / health」接口
探活通过 ≠ 真正查询时软件还在(用户可能中途退出了),两次请求之间状态会变。 把状态合进查询接口后,页面只发一次请求就能决定「展示结果」还是「提示可以唤起」:
| HTTP | state |
含义 |
|---|---|---|
| 200 | ok |
查到了,data 是数据 |
| 401 | need-login |
软件在跑但未登录,页面去调 activate-login 并轮询本接口等登录 |
| 400 | bad-request |
参数不对(例:码为空) |
| 404 | not-found |
没这条记录 |
| 500 | error |
内部错误 |
只有网络层失败(连不上 / 超时 / 被 CORS 拦)才代表「软件没启动」, 这时页面提示「服务暂不可用 + 下载安装 / 启动本机软件」。
无论成败都带这些字段:loggedIn、user、env(Development/Production)、server(当前后端地址):
// 200
{ "ok": true, "state": "ok", "code": "ABC123", "loggedIn": true, "user": "管理员",
"env": "Development", "server": "http://127.0.0.1:7300",
"data": { "code": "ABC123", "orderNo": "SO-20261017-001", "videoPath": "D:\\video\\demo.mp4" } }
// 401
{ "ok": false, "state": "need-login", "code": "ABC123", "loggedIn": false, "user": null,
"env": "Development", "server": "http://127.0.0.1:7300", "message": "本机软件未登录,请先在软件里登录" }
示例:
curl http://localhost:17300/api/query/321408064481776
curl http://localhost:17300/api/query/ # 400 bad-request,但带着登录状态
curl -X POST http://localhost:17300/api/activate-login
为什么唤起登录用 POST:GET 会被浏览器/聊天工具的链接预取误触发,POST 不会。
浏览器跨域(页面在站点域名上,请求的是 localhost)必须回这些响应头,代码里已经处理:
Access-Control-Allow-Origin(回显 Origin)、Allow-Methods(GET, POST, OPTIONS)、Allow-Headers、Max-AgeAccess-Control-Allow-Private-Network: true—— 公网 https 页面访问 localhost 时 Chrome 会发 私有网络预检(PNA),不回这个头预检就失败
⚠️ 千万别只回
200不带 CORS 头:浏览器会直接拦掉,前端看起来和「软件没启动」一模一样。
启动协议(网页叫醒本软件)
yuncang://open?code=xxx。注册写在 HKCU(免管理员):
HKEY_CURRENT_USER\Software\Classes\yuncang
(默认) = "URL:云仓视频溯源软件"
"URL Protocol" = ""
\shell\open\command
(默认) = "C:\...\YuncangTrace.LocalService.exe" "%1"
- 每次启动都会自动把注册项校正到「当前这个 exe」(幂等)。这一点很关键:
换目录安装、从
bin\Debug换成发布版、重新装一遍之后,注册表里残留的旧路径会让网页 唤起一个不存在 / 缺运行时的 exe(典型现象就是弹「You must install .NET」或干脆没反应)。 界面上仍可手动「取消启动协议」; - 手工注册/排查:
reg add "HKCU\Software\Classes\yuncang" /ve /d "URL:云仓视频溯源软件" /f
reg add "HKCU\Software\Classes\yuncang" /v "URL Protocol" /d "" /f
reg add "HKCU\Software\Classes\yuncang\shell\open\command" /ve /d '"C:\Path\YuncangTrace.LocalService.exe" "%1"' /f
reg query "HKCU\Software\Classes\yuncang\shell\open\command"
- 打包工具里对应:Inno Setup 的
[Registry]段、NSIS 的WriteRegStr HKCU ...、Electron 的app.setAsDefaultProtocolClient('yuncang'); - 协议名改了要同步前端
VITE_APP_PROTOCOL(默认yuncang)。
和前端 / 插件怎么配合
- WMS 页面上点运单号旁的按钮 → 插件按「打开方式」处理:默认直接用
yuncang://open?code=<运单号>唤起本机软件并定位到该单号 (浏览器会先问一次「要打开吗」);把打开方式改成「独立小窗 / 新标签页」则改为打开网页; /local页只发一个请求GET /api/query/{code}:- 连不上 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走
yuncang://open?code=...,然后每秒重试同一个查询接口; need-login(软件没登录)→ 页面自动POST /api/activate-login把本机登录窗叫到前台,然后每秒重试同一个查询接口等登录完成(最长 30s),登录好自动拿到结果;ok→ 直接展示(页面顶部会显示「本机软件已登录:xxx」)。
- 连不上 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走
- 本软件被协议拉起时,会拿到
yuncang://open?code=xxx参数:已经开着就转给原窗口(单实例), 没开就启动 → 先登录 → 登录完自动查询这个码(登录前收到的 code 会先存着)。 单实例的命名管道监听在登录之前就起来了,所以用户卡在登录窗时被网页唤起也不会丢参数。
插件「直接唤起」与唤不起时的提示(重要)
浏览器不会告诉网页协议到底有没有打开成功 —— 没安装、协议没注册、用户在 Chrome 的 「要打开吗」上点了取消,这三种情况在页面侧完全一样。所以必须做超时兜底:
- 点击 → 隐藏 iframe 触发
yuncang://open?code=xxx(不能导航当前页,否则协议没注册会变成错误页); - 判断到底成没成,不看页面焦点,看本机服务在不在:协议触发后每 0.7s 探测一次
http://localhost:17300/api/query/(任何 HTTP 响应都算成功,扩展带 host 权限,不受页面 CSP 影响);- 探测到 → 什么也不做(软件本来就在跑时也能正确判定,不会误报);
- 8 秒都探测不到 → 认为没起来,右下角弹出兜底卡片:
- 在网页中查看 → 打开插件设置里的「唤不起时的兜底页」(默认
http://localhost:7301/local?code={code}, 该页面里有完整的下载安装引导); - 下载安装 → 打开插件设置里的「软件下载地址」(留空则不显示这个按钮)。
- 插件设置页的相关配置:
- 打开方式:
直接唤起本机软件(协议)(默认)/独立小窗(网页)/新标签页(网页); - 协议模板(仅「直接唤起」时生效):默认
yuncang://open?code={code}; - 网页地址模板(仅小窗/标签页时生效):默认
http://localhost:7301/local?code={code}; - 唤不起时的兜底页、软件下载地址(留空则不显示「下载安装」按钮)。 老配置升级时会自动迁移(v3 把协议写在网页模板里的,会改成「打开方式 = 直接唤起 + 网页模板还原」),行为不变。
- 打开方式:
判定依据是「本机服务在不在」,所以软件已经在跑时不会误报(这是最常见的场景: 协议只是把参数转给已有实例,窗口不一定抢焦点)。真正的误报只剩一种:软件在跑但用户手动 「停止服务」了 —— 那种情况提示一下也算合理。页面失焦只作为「快速判定成功」的辅助信号。
★ 接真实数据
只改一处:Services/OrderQueryService.cs 的 Query(string? code)。
public QueryResult Query(string? code)
{
var value = (code ?? "").Trim();
if (value.Length == 0) return QueryResult.BadRequest("缺少运单号");
// 例:查本地 SQLite / 扫本地打包视频目录 / 调内部接口
var row = _db.FindByCode(value);
if (row is null) return QueryResult.NotFound($"没有找到 {value} 的记录");
return QueryResult.Success(new Dictionary<string, object?>
{
["code"] = row.Code,
["orderNo"] = row.OrderNo,
["printStatus"] = row.PrintStatus,
["videoPath"] = row.VideoPath,
});
}
返回对象平铺即可,前端页面会把顶层字段渲染成「项目 / 值」两列(字段随便加)。
常见问题
| 现象 | 处理 |
|---|---|
启动报「没有绑定端口的权限」/ Access is denied (5) |
管理员执行 netsh http add urlacl url=http://localhost:17300/ user=%USERNAME%,或改成以当前用户身份运行 |
| 报端口被占用(错误 32) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 http://localhost:17300/api/health:打不开→防火墙/端口;打得开→多半是 CORS 头没回 |
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
| 唤起时弹「You must install .NET Desktop Runtime」 | 唤起的是 bin\Debug 这类 framework-dependent 的 exe(拿不到 DOTNET_ROOT)。用自包含发布产物,并让它启动一次以校正注册表 |
| 改了协议名 | 注册表重注册 + 前端 VITE_APP_PROTOCOL 同步 + 插件目标地址同步 |