给前端 `/local` 公共页与 Chrome 插件对接的本机软件(net8.0-windows + UseWPF):
- Services/LocalHttpServer.cs:HttpListener 监听 localhost:17311(同时注册 127.0.0.1 前缀)
- GET /api/health 探活(2xx 即认为已启动)
- GET /api/query/{code} 按运单号查信息,成功时字段平铺返回
- CORS 全量响应头 + Access-Control-Allow-Private-Network(公网 https 页面访问 localhost 的
PNA 预检),预检 OPTIONS 直接 204
- 根路径给一个说明页,方便浏览器里手工排查
- Services/OrderQueryService.cs:★ 接真实数据源的位置(现为演示数据)
- Services/ProtocolHelper.cs:HKCU\Software\Classes\yuncang 注册/反注册、解析
yuncang://open?code=xxx(免管理员)
- Services/SingleInstance.cs:互斥体 + 命名管道,被协议再次拉起时把参数转给已运行窗口,
不会去抢 17311 端口
- MainWindow:运行状态、服务地址(复制/浏览器打开)、注册启动协议、测试查询、运行日志
- App.xaml.cs:单实例判断 + 协议参数处理;启动即自动起服务
README 里写了编译/发布命令、接口契约、协议注册(含 reg 命令与打包工具做法)、
接真实数据的示例,以及端口权限(netsh http add urlalloc)/端口占用等常见问题。
⚠️ 本机没装 .NET SDK,无法在这里编译验证;XAML/manifest/csproj 已做 XML 良构校验。
145 lines
6.8 KiB
Markdown
145 lines
6.8 KiB
Markdown
# 云仓视频溯源软件(本机服务 / WPF)
|
||
|
||
Windows 桌面端,用**前端 `/local` 公共页**和 **Chrome 插件**做对接:
|
||
|
||
- 在 `127.0.0.1:17311` 起一个本机 HTTP 服务,浏览器里的页面直接查询本机数据;
|
||
- 注册 `yuncang://` 启动协议,网页可以「叫醒」本软件(前提是已安装);
|
||
- 单实例:被协议再次拉起时,只把 `code` 转给已运行的窗口,不会抢端口。
|
||
|
||
```
|
||
desktop/
|
||
├── YuncangTrace.LocalService.csproj # net8.0-windows + UseWPF
|
||
├── app.manifest # 高 DPI / 兼容性声明
|
||
├── App.xaml / App.xaml.cs # 单实例 + 协议参数处理
|
||
├── MainWindow.xaml / .xaml.cs # 状态、地址、协议注册、测试查询、日志
|
||
└── Services/
|
||
├── LocalHttpServer.cs # HttpListener + CORS + PNA
|
||
├── OrderQueryService.cs # ★ 按运单号查数据(接真实数据源的地方)
|
||
├── ProtocolHelper.cs # yuncang:// 注册/反注册、解析 code
|
||
├── SingleInstance.cs # 互斥体 + 命名管道转发参数
|
||
└── JsonUtil.cs # JSON 序列化(中文不转义)
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- 编译:**.NET 8 SDK**(`dotnet --list-sdks` 能看到 `8.x`)
|
||
- 只运行已发布的 exe:**.NET 8 Desktop Runtime**(不需要 SDK)
|
||
|
||
> 本仓库当前环境**没有装 .NET**,所以这份代码没在 CI 里编译过;第一次请自己跑一遍
|
||
> `dotnet build`,有报错直接贴出来。
|
||
|
||
## 构建 / 运行 / 发布
|
||
|
||
```powershell
|
||
cd desktop
|
||
|
||
dotnet build -c Release # 编译
|
||
dotnet run # 直接跑(调试)
|
||
|
||
# 发布给用户装(framework-dependent,体积小、需要装 Desktop Runtime)
|
||
dotnet publish -c Release -r win-x64 --self-contained false -o publish
|
||
|
||
# 或者自带运行时(体积大,但用户什么都不用装)
|
||
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish
|
||
```
|
||
|
||
## 本机接口(前端 `/local` 页用的就是这两个)
|
||
|
||
服务固定监听 `http://localhost:17311`(端口写在前端页面与插件里)。
|
||
代码里**同时注册了 `http://127.0.0.1:17311/`** 前缀 —— `HttpListener` 只接受「注册过的 host」,
|
||
不注册的话用 127.0.0.1 访问会直接被回 400(前端改 `VITE_LOCAL_SERVICE` 时就会碰到)。
|
||
|
||
浏览器直接打开 <http://localhost:17311/> 会看到一个说明页(列了下面两个接口,方便排查)。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/health` | 探活:**只要能返回 2xx 就认为软件已启动**。返回 `{ ok, name, version, port, serverTime }` |
|
||
| GET | `/api/query/{code}` | 按运单号查信息。**成功时把字段平铺在顶层**(`{ code, orderNo, ... }`),失败返回 `{ ok:false, message }` + 4xx |
|
||
|
||
示例:
|
||
|
||
```powershell
|
||
curl http://localhost:17311/api/health
|
||
curl http://localhost:17311/api/query/321408064481776
|
||
```
|
||
|
||
浏览器跨域(页面在站点域名上,请求的是 localhost)必须回这些响应头,代码里已经处理:
|
||
|
||
- `Access-Control-Allow-Origin`(回显 Origin)、`Allow-Methods`、`Allow-Headers`、`Max-Age`
|
||
- `Access-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);卸载时点「取消启动协议」或调用 `ProtocolHelper.Unregister()`;
|
||
- 手工注册/排查:
|
||
|
||
```powershell
|
||
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`)。
|
||
|
||
## 和前端 / 插件怎么配合
|
||
|
||
1. WMS 页面上点运单号旁的按钮 → 插件打开 `http://<站点>/local?code=<运单号>`;
|
||
2. `/local` 页先探活 `http://localhost:17311/api/health`:
|
||
- 通 → 直接调 `/api/query/{code}` 展示;
|
||
- 不通 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
|
||
点「已安装,启动本机软件」会走 `yuncang://open?code=...`,然后每 1s 轮询探活,起来后自动查询。
|
||
3. 本软件被协议拉起时,会拿到 `yuncang://open?code=xxx` 参数:已经开着就转给原窗口(单实例),
|
||
没开就启动并直接查询这个码。
|
||
|
||
## ★ 接真实数据
|
||
|
||
只改一处:`Services/OrderQueryService.cs` 的 `Query(string? code)`。
|
||
|
||
```csharp
|
||
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:17311/ user=%USERNAME%`,或改成以当前用户身份运行 |
|
||
| 报端口被占用(错误 32) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
|
||
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 `http://localhost:17311/api/health`:打不开→防火墙/端口;打得开→多半是 CORS 头没回 |
|
||
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
|
||
| 改了协议名 | 注册表重注册 + 前端 `VITE_APP_PROTOCOL` 同步 + 插件目标地址同步 |
|