桌面端接入 .NET 8 SDK 并首编译通过;服务地址改为构建期环境配置(开发/生产)

一、工具链
- 本机没有 .NET,微软域名又被网络阻断,改用 curl 从 builds.dotnet.microsoft.com 拉
  dotnet-sdk-8.0.426-win-x64.zip,解压到 %LOCALAPPDATA%\Microsoft\dotnet(免管理员),
  并写入用户 PATH / DOTNET_ROOT / DOTNET_CLI_TELEMETRY_OPTOUT。

二、首次编译暴露的两个真实缺陷(都已修复)
- ProtocolHelper.cs 缺 using System.Collections.Generic(ImplicitUsings=disable 后
  IEnumerable<string> 找不到)。
- App.xaml 少了 BgBrush,LoginWindow/MainWindow 用 StaticResource 引用它 → 编译期查不出,
  运行期一弹登录窗就 XamlParseException 直接退出(事件日志里能看到)。
  已补 BgBrush=#F5F7FA 并注明「缺一个就会运行时炸」。
- 顺带把 WFAC010(WinForms 建议 DPI 改走 ApplicationHighDpiMode)压掉并写明原因:
  本程序宿主是 WPF,走不到 WinForms 的 ApplicationConfiguration,DPI 只能由 manifest 决定。

三、服务地址 = 构建期环境(对齐前端 VITE_BACKEND 的思路)
- csproj:Debug → AppEnvironment=Development、ServerBaseUrl=http://127.0.0.1:7300;
  Release → Production、占位 https://packs.example.com;用 -p:ServerBaseUrl= 覆盖;
  两者通过 AssemblyMetadataAttribute 写进程序集,exe 自带「我是哪个环境」。
- 新增 Services/BuildInfo.cs 读元数据(带兜底,绝不抛)。
- AppSettings:默认值改为 BuildInfo.DefaultServer;等于内置默认值时不落盘(换构建能自动跟随),
  老版本已把默认值写进 settings.json 的也识别为"没改过";新增 UseServer() 支持运行时临时覆盖。
- App:解析 --server=xxx / -s xxx,其次 YUNCANG_SERVER 环境变量,写在构建默认值之前。
- 登录窗:「服务器地址」改叫「服务地址」,右侧显示"开发环境/生产环境"(只展示,由构建决定),
  输入框 ToolTip 说明留空即用当前环境默认地址。
- /api/health 增加 env(Development/Production)与 server(当前后端地址),排障一眼看出装错没有。

四、验证
- Debug / Release / Release+域名覆盖 三种构建均 0 警告 0 错误;
- Debug:health 返回 env=Development、server=http://127.0.0.1:7300;
- Release:env=Production、server=https://packs.example.com;
  Release 加 -p:ServerBaseUrl=https://trace.yuncang.cn 后 server 随之变化;
- 带 --server=http://10.0.0.9:7300 启动:server 被覆盖,settings.json 未被污染;
- health / 未登录 query(401) / activate-login(200,登录窗弹出) / OPTIONS 预检(204+CORS) 全部正常。
- 注意:改 -p: 属性必须 -t:Rebuild,否则 MSBuild 不会重新生成 AssemblyInfo。

五、README
- 新增「环境配置(开发 / 生产)」:构建矩阵、发布时覆盖域名、优先级、默认值不落盘的原因、
  settings.json/session.json 的行为;补了本机 SDK 装在用户目录、需要 DOTNET_ROOT 的说明;
  行为表新增「网页请求唤起登录」一行;health 返回字段更新。
This commit is contained in:
liufumingren 2026-10-17 10:48:11 +08:00
parent 700394b56f
commit fb896272f4
10 changed files with 239 additions and 15 deletions

View File

@ -10,5 +10,7 @@
<SolidColorBrush x:Key="LineBrush" Color="#E5E7EB" />
<SolidColorBrush x:Key="OkBrush" Color="#16A34A" />
<SolidColorBrush x:Key="BadBrush" Color="#DC2626" />
<!-- 窗口底色(代码里所有资源都用 StaticResource 引用,缺一个就会在运行时炸 XamlParseException) -->
<SolidColorBrush x:Key="BgBrush" Color="#F5F7FA" />
</Application.Resources>
</Application>

View File

@ -45,6 +45,7 @@ public partial class App : Application
}
_settings = AppSettings.Load();
ApplyServerOverride(e.Args);
_pendingLaunchUrl = ProtocolHelper.FirstLaunchUrl(e.Args);
// ② 本机服务先起来(和登录状态无关)
@ -53,6 +54,7 @@ public partial class App : Application
// 网页靠 /api/health 里的 loggedIn 判断要不要唤起登录,靠 /api/activate-login 把登录窗叫到前台
_server.IsLoggedInProvider = () => _session is not null;
_server.UserNameProvider = () => _session?.DisplayName;
_server.ServerBaseUrlProvider = () => _settings.ServerBaseUrl;
_server.LoginRequested += OnLoginRequested;
StartLocalServer();
@ -64,6 +66,7 @@ public partial class App : Application
UpdateTrayStatus();
AppLog.Write($"本机服务:{_server.BaseUrl}({(_server.IsRunning ? "运行中" : "未启动")})");
AppLog.Write($"环境:{BuildInfo.EnvironmentLabel},后端:{_settings.ServerBaseUrl}");
// ④ 登录 → 主窗口
if (!ShowLogin())
@ -78,6 +81,38 @@ public partial class App : Application
// ---------------- 登录 ----------------
/// <summary>
/// 后端地址的运行时覆盖(优先级:<c>--server=xxx</c> 参数 &gt; <c>YUNCANG_SERVER</c> 环境变量 &gt; 构建默认值)
///
/// 打包/联调时用:<c>YuncangTrace.LocalService.exe --server=http://192.168.1.10:7300</c>
/// </summary>
private void ApplyServerOverride(string[] args)
{
string? url = null;
for (var i = 0; i < args.Length; i++)
{
var arg = args[i];
const string prefix = "--server=";
if (arg.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
{
url = arg[prefix.Length..];
}
else if ((arg == "--server" || arg == "-s") && i + 1 < args.Length)
{
url = args[i + 1];
}
}
if (string.IsNullOrWhiteSpace(url))
{
url = Environment.GetEnvironmentVariable("YUNCANG_SERVER");
}
_settings.UseServer(url);
}
/// <summary>显示登录窗;返回 false = 用户取消(应退出程序)</summary>
private bool ShowLogin()
{

View File

@ -16,8 +16,13 @@
FontSize="12" Foreground="{StaticResource MutedBrush}"
HorizontalAlignment="Center" Margin="0,6,0,18" />
<TextBlock Text="服务器地址" FontSize="12" Foreground="{StaticResource MutedBrush}" Margin="0,0,0,4" />
<TextBox x:Name="ServerBox" Padding="6,5" ToolTip="后端地址,例如 http://127.0.0.1:7300" />
<Grid Margin="0,0,0,4">
<TextBlock Text="服务地址" FontSize="12" Foreground="{StaticResource MutedBrush}" />
<!-- 开发 / 生产由构建决定(csproj 注入),这里只展示,不让用户选 -->
<TextBlock x:Name="EnvText" FontSize="12" Foreground="{StaticResource MutedBrush}"
HorizontalAlignment="Right" />
</Grid>
<TextBox x:Name="ServerBox" Padding="6,5" />
<TextBlock Text="账号(用户名 / 手机号 / 邮箱)" FontSize="12" Foreground="{StaticResource MutedBrush}" Margin="0,12,0,4" />
<TextBox x:Name="AccountBox" Padding="6,5" />

View File

@ -36,6 +36,10 @@ public partial class LoginWindow : Window
AccountBox.Text = settings.LastAccount;
RememberBox.IsChecked = settings.RememberAccount;
// 环境由构建决定(Debug = 开发环境,Release = 生产环境),默认地址也来自构建
EnvText.Text = BuildInfo.EnvironmentLabel;
ServerBox.ToolTip = $"留空即使用{BuildInfo.EnvironmentLabel}默认地址:{BuildInfo.DefaultServer}\n启动时可用 --server=http://x.x.x.x:7300 临时指定";
Loaded += OnLoaded;
}

View File

@ -42,32 +42,63 @@ desktop/
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 `yuncang://open?code=…` 通过命名管道转给已运行实例 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
| 网页请求唤起登录(`POST /api/activate-login`) | 未登录:登录窗弹到最前;已登录:主界面弹到最前(不影响本机服务) |
| 托盘右键「退出」 | 真正退出(dispose 托盘与本机服务) |
服务器地址默认 `http://127.0.0.1:7300`(后端 dev 默认端口),登录页上可以改,改完会存进 `settings.json`。
换服务器后不会复用旧令牌(会要求重新登录)。
## 环境配置(开发 / 生产)
和前端 `VITE_BACKEND` 一个思路:**由构建决定,不靠用户手填**。
| 构建 | `env` | 默认后端 |
| --- | --- | --- |
| `dotnet build`(Debug) | `Development` | `http://127.0.0.1:7300`(= 前端 dev 代理的后端) |
| `dotnet build -c Release` | `Production` | `https://packs.example.com`(占位,打包时必须覆盖) |
打包正式版时指定真实域名:
```powershell
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com -o publish
```
优先级(从高到低):
1. 启动参数 `--server=http://192.168.1.10:7300`(临时,不落盘);
2. 环境变量 `YUNCANG_SERVER`;
3. `-p:ServerBaseUrl=` 注入的构建默认值;
4. 用户在登录页手改并保存的地址(`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)
> 本仓库当前环境**没有装 .NET**,所以这份代码没在 CI 里编译过;第一次请自己跑一遍
> `dotnet build`,有报错直接贴出来。
> 本机 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)。
## 构建 / 运行 / 发布
```powershell
cd desktop
dotnet build -c Release # 编译
dotnet run # 直接跑(调试)
dotnet build # 编译(Debug = 开发环境,连本地 7300)
dotnet build -c Release # 编译(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 -p:ServerBaseUrl=https://trace.example.com --self-contained false -o publish
# 或者自带运行时(体积大,但用户什么都不用装)
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com --self-contained true -p:PublishSingleFile=true -o publish
```
## 本机接口(前端 `/local` 页用的就是这三个)
@ -80,7 +111,7 @@ dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 验活 + 登录状态:**2xx 即认为软件已启动**。返回 `{ ok, name, version, port, loggedIn, user, serverTime }` |
| GET | `/api/health` | 验活 + 登录状态:**2xx 即认为软件已启动**。返回 `{ ok, name, version, port, env, server, loggedIn, user, serverTime }`(`env` = `Development`/`Production`) |
| GET | `/api/query/{code}` | 按运单号查信息(**需已登录**,否则 401 `{ ok:false, loggedIn:false, message }`)。成功时字段**平铺**在顶层(`{ code, orderNo, ... }`) |
| POST | `/api/activate-login` | 把本机软件的**登录窗叫到前台**(已登录时把主界面叫到前台)。网页发现 `loggedIn:false` 时自动调它 |

View File

@ -9,15 +9,21 @@ namespace YuncangTrace.LocalService.Services;
/// 本机设置:`%LOCALAPPDATA%\YuncangTrace\settings.json`
///
/// 目前只有「服务器地址」(登录用的后端)和「记住账号」。
/// 服务器地址的**默认值**来自构建环境(<see cref="BuildInfo"/>),用户没改过就不落盘,
/// 这样 Debug / Release 两个构建各自连自己的后端,不会互相污染。
/// </summary>
public sealed class AppSettings
{
/// <summary>默认后端地址(本地开发)</summary>
public const string DefaultServer = "http://127.0.0.1:7300";
/// <summary>当前构建的默认后端地址(Debug = 本地 7300,Release = 正式站点)</summary>
public static string DefaultServer => BuildInfo.DefaultServer;
/// <summary>后端 API 根地址(登录、校验令牌都走它)</summary>
public string ServerBaseUrl { get; set; } = DefaultServer;
/// <summary>地址来自命令行/环境变量的临时覆盖(不落盘)</summary>
[System.Text.Json.Serialization.JsonIgnore]
public bool ServerIsVolatile { get; private set; }
/// <summary>上次登录的账号(只在「记住账号」勾选时保存)</summary>
public string LastAccount { get; set; } = string.Empty;
@ -45,7 +51,10 @@ public sealed class AppSettings
var settings = JsonSerializer.Deserialize<AppSettings>(File.ReadAllText(FilePath));
if (settings is null) return new AppSettings();
settings.ServerBaseUrl = Normalize(settings.ServerBaseUrl);
// 文件里存的是空串 = 用户没改过,用当前构建的默认值;
// 老版本会把默认地址直接落盘,所以「等于任何已知默认值」也当作没改过,跟随当前构建。
var stored = Normalize(settings.ServerBaseUrl);
settings.ServerBaseUrl = IsKnownDefault(stored) ? DefaultServer : stored;
return settings;
}
catch (Exception ex)
@ -55,6 +64,17 @@ public sealed class AppSettings
}
}
/// <summary>运行时指定后端地址(<c>--server=</c> / <c>YUNCANG_SERVER</c>),只影响本次运行</summary>
public void UseServer(string? url)
{
var value = (url ?? string.Empty).Trim();
if (value.Length == 0) return;
ServerBaseUrl = Normalize(value);
ServerIsVolatile = true;
AppLog.Write($"后端地址已被临时覆盖:{ServerBaseUrl}(不保存)");
}
/// <summary>存设置(失败只记日志)</summary>
public void Save()
{
@ -64,7 +84,17 @@ public sealed class AppSettings
if (!RememberAccount) LastAccount = string.Empty;
Directory.CreateDirectory(Dir);
File.WriteAllText(FilePath, JsonSerializer.Serialize(this, Options));
// 等于构建默认值(或只是临时覆盖)就写空串:换环境构建时能自动跟随,只有用户手改的地址才落盘
var stored = ServerIsVolatile || ServerBaseUrl == DefaultServer ? string.Empty : ServerBaseUrl;
var payload = new StoredSettings
{
ServerBaseUrl = stored,
LastAccount = LastAccount,
RememberAccount = RememberAccount,
};
File.WriteAllText(FilePath, JsonSerializer.Serialize(payload, Options));
}
catch (Exception ex)
{
@ -81,4 +111,22 @@ public sealed class AppSettings
if (!value.Contains("://", StringComparison.Ordinal)) value = "http://" + value;
return value.TrimEnd('/');
}
/// <summary>是不是"内置默认地址"之一(老版本落盘过这些值,不该当成用户自定义)</summary>
private static bool IsKnownDefault(string url)
{
return url.Equals(DefaultServer, StringComparison.OrdinalIgnoreCase)
|| url.Equals(Normalize(BuildInfo.DevServer), StringComparison.OrdinalIgnoreCase)
|| url.Equals(Normalize(BuildInfo.ProdServerPlaceholder), StringComparison.OrdinalIgnoreCase);
}
/// <summary>落盘用的结构(和本类的可读属性一一对应)</summary>
private sealed class StoredSettings
{
public string ServerBaseUrl { get; set; } = string.Empty;
public string LastAccount { get; set; } = string.Empty;
public bool RememberAccount { get; set; } = true;
}
}

View File

@ -0,0 +1,63 @@
using System;
using System.Linq;
using System.Reflection;
namespace YuncangTrace.LocalService.Services;
/// <summary>
/// 构建期注入的环境信息 —— 和前端 <c>VITE_BACKEND</c> 一个思路:
/// 开发 / 生产由**构建**决定,不靠用户手填。
///
/// - Debug 构建 :环境 = <c>Development</c>,默认后端 <c>http://127.0.0.1:7300</c>(与前端 dev 代理一致);
/// - Release 构建 :环境 = <c>Production</c>,默认后端 <c>https://packs.example.com</c>(占位,打包时覆盖);
/// - 打包时覆盖 :<c>dotnet build -c Release -p:ServerBaseUrl=https://你的域名</c>。
///
/// 值由 <c>YuncangTrace.LocalService.csproj</c> 通过 <see cref="AssemblyMetadataAttribute"/> 写进程序集,
/// 因此 exe 自己就带着"它是哪个环境"的信息,不需要额外的配置文件。
/// </summary>
public static class BuildInfo
{
/// <summary>Debug 构建的默认后端(= 前端 dev 代理的后端 127.0.0.1:7300)</summary>
public const string DevServer = "http://127.0.0.1:7300";
/// <summary>Release 构建的默认后端(占位,打包时用 -p:ServerBaseUrl= 覆盖)</summary>
public const string ProdServerPlaceholder = "https://packs.example.com";
/// <summary>环境名:<c>Development</c> / <c>Production</c></summary>
public static string Environment { get; } = ReadMetadata("AppEnvironment", "Development");
/// <summary>当前构建的默认后端地址</summary>
public static string DefaultServer { get; } = Normalize(ReadMetadata("ServerBaseUrl", DevServer));
/// <summary>是不是开发(Debug)构建</summary>
public static bool IsDevelopment =>
Environment.Equals("Development", StringComparison.OrdinalIgnoreCase);
/// <summary>给人看的环境名(登录窗里显示)</summary>
public static string EnvironmentLabel => IsDevelopment ? "开发环境" : "生产环境";
/// <summary><c>--server=...</c> / <c>YUNCANG_SERVER</c> 的运行时覆盖(排在构建默认值之前)</summary>
private static string ReadMetadata(string key, string fallback)
{
try
{
var value = Assembly.GetEntryAssembly()
?.GetCustomAttributes<AssemblyMetadataAttribute>()
.FirstOrDefault(a => string.Equals(a.Key, key, StringComparison.OrdinalIgnoreCase))
?.Value;
return string.IsNullOrWhiteSpace(value) ? fallback : value.Trim();
}
catch
{
return fallback;
}
}
private static string Normalize(string url)
{
var value = url.Trim();
if (!value.Contains("://", StringComparison.Ordinal)) value = "http://" + value;
return value.TrimEnd('/');
}
}

View File

@ -46,6 +46,9 @@ public sealed class LocalHttpServer : IDisposable
/// <summary>当前登录用户显示名(由 App 提供,供 `/api/health` 用)</summary>
public Func<string?>? UserNameProvider { get; set; }
/// <summary>当前后端地址(由 App 提供,供 `/api/health` 排障用)</summary>
public Func<string?>? ServerBaseUrlProvider { get; set; }
public LocalHttpServer(OrderQueryService queryService)
{
_queryService = queryService;
@ -173,6 +176,8 @@ public sealed class LocalHttpServer : IDisposable
name = "云仓视频溯源打印服务",
version = typeof(LocalHttpServer).Assembly.GetName().Version?.ToString() ?? "1.0.0",
port = Port,
env = BuildInfo.Environment,
server = ServerBaseUrlProvider?.Invoke(),
loggedIn = IsLoggedIn,
user = UserNameProvider?.Invoke(),
serverTime = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),

View File

@ -1,4 +1,5 @@
using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Win32;

View File

@ -24,6 +24,24 @@
<RootNamespace>YuncangTrace.LocalService</RootNamespace>
<ApplicationManifest>app.manifest</ApplicationManifest>
<!--
WFAC010:WinForms 分析器建议把高 DPI 从 manifest 挪到 ApplicationHighDpiMode。
但本程序是 WPF 宿主(走的是 WPF 的 App.Run,不会调 WinForms 的 ApplicationConfiguration),
WinForms 只用来放托盘图标 —— 那条建议在这里不生效,DPI 只能由 manifest 的 PerMonitorV2 决定。
-->
<NoWarn>$(NoWarn);WFAC010</NoWarn>
<!--
环境配置(和前端 VITE_BACKEND 一个思路:由构建决定,不靠用户手填)
Debug :AppEnvironment=Development,默认后端 http://127.0.0.1:7300(= 前端 dev 代理的地址)
Release :AppEnvironment=Production ,默认后端由 -p:ServerBaseUrl=https://正式域名 覆盖
运行时覆盖优先级:命令行 server 参数 &gt; YUNCANG_SERVER 环境变量 &gt; 这里注入的默认值。
-->
<AppEnvironment Condition="'$(Configuration)' == 'Debug'">Development</AppEnvironment>
<AppEnvironment Condition="'$(Configuration)' == 'Release'">Production</AppEnvironment>
<ServerBaseUrl Condition="'$(Configuration)' == 'Debug' and '$(ServerBaseUrl)' == ''">http://127.0.0.1:7300</ServerBaseUrl>
<ServerBaseUrl Condition="'$(Configuration)' == 'Release' and '$(ServerBaseUrl)' == ''">https://packs.example.com</ServerBaseUrl>
<Version>1.0.0</Version>
<Product>云仓视频溯源软件</Product>
<Company>云仓</Company>
@ -31,4 +49,16 @@
<NeutralLanguage>zh-CN</NeutralLanguage>
</PropertyGroup>
<!-- 把环境写进程序集(Services/BuildInfo.cs 运行时读出来) -->
<ItemGroup>
<AssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute">
<_Parameter1>AppEnvironment</_Parameter1>
<_Parameter2>$(AppEnvironment)</_Parameter2>
</AssemblyAttribute>
<AssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute">
<_Parameter1>ServerBaseUrl</_Parameter1>
<_Parameter2>$(ServerBaseUrl)</_Parameter2>
</AssemblyAttribute>
</ItemGroup>
</Project>