Skip to content

Commit 81a4126

Browse files
CopilotJusterZhu
Copilot
and
JusterZhu
authored
docs: update ClientCore and Core docs with new API changes from recent PRs
- Add AddListenerUpdateInfo() method documentation (PR #166) - Add AddListenerUpdatePrecheck() replacing SetCustomSkipOption (PR #172) - Remove deprecated SetCustomSkipOption from ClientCore docs - Add UpdateOption.EnableSilentUpdate for silent update mode (PR #164) - Add ConfiginfoBuilder zero-configuration builder section (PR #157) - Add DriverDirectory field to Configinfo documentation (PR #145) - Remove SetFieldMappings from Core docs (PR #148) - Update driver upgrade example to use new DriverDirectory approach - Add new examples for precheck, silent update, and ConfiginfoBuilder - Add 2026-04-10 release log entries in English and Chinese - All changes applied to docs/, i18n/zh-Hans/, and i18n/en/" Agent-Logs-Url: https://github.com/GeneralLibrary/GeneralUpdate-Samples/sessions/1116c9d1-3933-4783-83a9-842784e0e6bd Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com>
1 parent 8808fc4 commit 81a4126

9 files changed

Lines changed: 669 additions & 128 deletions

File tree

‎website/docs/doc/GeneralUpdate.ClientCore.md‎

Lines changed: 180 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,20 @@ public class GeneralClientBootstrap : AbstractBootstrap<GeneralClientBootstrap,
2828
- 黑名单机制(文件、格式、目录)
2929
- 自定义更新策略和操作
3030
- 支持二进制差异更新和全量更新
31+
- `ConfiginfoBuilder` 零配置构建器,只需三个参数即可完成配置
3132

3233
### 3. 完整的事件通知
3334
- 下载进度、完成、错误事件
34-
- 支持用户自定义跳过更新选项
35+
- 更新版本信息通知（`AddListenerUpdateInfo`）
36+
- 统一更新预检回调（`AddListenerUpdatePrecheck`）
3537
- 异常和错误全程监控
3638

37-
### 4. 多平台支持
39+
### 4. 静默更新模式
40+
- 后台轮询检测新版本（默认每 20 分钟一次）
41+
- 静默下载并准备更新包
42+
- 在主程序退出后自动启动升级流程
43+
44+
### 5. 多平台支持
3845
- Windows、Linux、macOS 平台支持
3946
- 自动平台检测和策略选择
4047

@@ -245,12 +252,46 @@ public GeneralClientBootstrap AddListenerException(
245252
public GeneralClientBootstrap AddCustomOption(Func<Task> customFunc)
246253
```
247254

248-
#### SetCustomSkipOption 方法
255+
#### AddListenerUpdateInfo 方法
256+
257+
注册更新版本信息回调。版本验证完成后立即触发,可用于展示更新日志或版本列表。
258+
259+
```csharp
260+
public GeneralClientBootstrap AddListenerUpdateInfo(
261+
Action<object, UpdateInfoEventArgs> callbackAction)
262+
```
263+
264+
**UpdateInfoEventArgs 属性:**
265+
- `Info`: `VersionRespDTO` — 服务端返回的版本响应数据,包含可用版本列表及每个版本的 `UpdateLog` 字段
266+
267+
**示例:**
268+
```csharp
269+
.AddListenerUpdateInfo((sender, e) =>
270+
{
271+
foreach (var v in e.Info.Body ?? [])
272+
Console.WriteLine($"{v.Version}: {v.UpdateLog}");
273+
})
274+
```
275+
276+
#### AddListenerUpdatePrecheck 方法
249277

250-
设置自定义跳过选项,允许用户决定是否继续更新。
278+
注册更新预检回调,将更新信息通知和跳过更新决策合并为单一入口。回调接收完整的 `UpdateInfoEventArgs`（版本列表、强制更新标志等），返回 `true` 跳过更新，返回 `false` 继续更新。
251279

280+
> **注意：** 此方法替代了旧的 `AddListenerUpdateInfo` + `SetCustomSkipOption` 组合写法。`IsForcibly` 为强制更新时，回调返回值将被忽略，更新始终执行。
281+
282+
```csharp
283+
public GeneralClientBootstrap AddListenerUpdatePrecheck(
284+
Func<UpdateInfoEventArgs, bool> precheckFunc)
285+
```
286+
287+
**示例:**
252288
```csharp
253-
public GeneralClientBootstrap SetCustomSkipOption(Func<bool> customSkipFunc)
289+
.AddListenerUpdatePrecheck(updateInfo =>
290+
{
291+
// 在此可访问完整版本信息
292+
bool userChoseSkip = ShowUpdateDialog(updateInfo.Info);
293+
return userChoseSkip; // true = 跳过, false = 继续更新
294+
})
254295
```
255296

256297
---
@@ -346,6 +387,11 @@ public class Configinfo
346387
/// Linux 平台下的脚本,用于在更新完成后为文件分配权限
347388
/// </summary>
348389
public string Script { get; set; }
390+
391+
/// <summary>
392+
/// 驱动程序目录路径,指定包含需要更新的驱动文件的目录
393+
/// </summary>
394+
public string DriverDirectory { get; set; }
349395
}
350396
```
351397

@@ -377,12 +423,76 @@ public enum UpdateOption
377423
/// <summary>
378424
/// 是否在更新前启用备份功能,默认启用;设置为 false 则不进行备份
379425
/// </summary>
380-
BackUp
426+
BackUp,
427+
428+
/// <summary>
429+
/// 是否启用静默更新模式。启用后将在后台轮询检测新版本、静默下载更新包,
430+
/// 并在主程序退出后自动启动升级流程,不影响用户的正常使用。
431+
/// </summary>
432+
EnableSilentUpdate
381433
}
382434
```
383435

384436
---
385437

438+
## ConfiginfoBuilder 构建器
439+
440+
`ConfiginfoBuilder` 是零配置模式的 `Configinfo` 构建器,灵感来自 [Velopack](https://github.com/velopack/velopack) 的设计。只需提供三个必填参数即可自动生成完整的平台适配配置。
441+
442+
**命名空间:** `GeneralUpdate.Common.Shared.Object`
443+
444+
### 特性
445+
446+
- 仅需三个参数：`UpdateUrl`、`Token`、`Scheme`
447+
- 自动从 `.csproj` 文件提取应用名称、版本号和发布者信息
448+
- 自动适配 Windows / Linux / macOS 平台差异（路径、权限脚本等）
449+
- 安装路径默认使用宿主程序所在目录（`AppDomain.CurrentDomain.BaseDirectory`）
450+
451+
### 快速使用
452+
453+
```csharp
454+
using GeneralUpdate.Common.Shared.Object;
455+
456+
// 零配置:从 .csproj 自动提取名称、版本、发布者
457+
var config = ConfiginfoBuilder
458+
.Create("https://api.example.com/updates", "your-token", "Bearer")
459+
.Build();
460+
461+
await new GeneralClientBootstrap()
462+
.SetConfig(config)
463+
.LaunchAsync();
464+
```
465+
466+
### 自定义覆盖
467+
468+
```csharp
469+
var config = ConfiginfoBuilder
470+
.Create("https://api.example.com/updates", "your-token", "Bearer")
471+
.SetAppName("CustomApp.exe") // 覆盖自动检测的名称
472+
.SetClientVersion("2.0.0") // 覆盖自动检测的版本
473+
.SetInstallPath("/custom/path") // 覆盖安装路径
474+
.Build();
475+
```
476+
477+
### 自动提取规则
478+
479+
| 配置项 | 提取来源 | csproj 字段 | 映射目标 |
480+
|--------|----------|-------------|----------|
481+
| 应用名称 | 项目文件 | `<AssemblyName>` 或文件名 | `AppName`、`MainAppName` |
482+
| 版本号 | 项目文件 | `<Version>` | `ClientVersion`、`UpgradeClientVersion` |
483+
| 发布者 | 项目文件 | `<Company>` 或 `<Authors>` | `ProductId` |
484+
| 安装路径 | 宿主程序运行时目录 | — | `InstallPath` |
485+
486+
### 平台支持
487+
488+
| 平台 | 应用名称后缀 | 默认脚本 |
489+
|------|------------|---------|
490+
| Windows | `.exe` | 无 |
491+
| Linux | 无后缀 | chmod 权限脚本 |
492+
| macOS | 无后缀 | chmod 权限脚本 |
493+
494+
---
495+
386496
## 实际使用示例
387497

388498
### 示例 1:基本更新流程
@@ -518,7 +628,7 @@ await new GeneralClientBootstrap()
518628
.LaunchAsync();
519629
```
520630

521-
### 示例 5:自定义操作和跳过选项
631+
### 示例 5：更新预检与跳过（AddListenerUpdatePrecheck）
522632

523633
```csharp
524634
using GeneralUpdate.ClientCore;
@@ -533,20 +643,62 @@ var config = new Configinfo
533643

534644
await new GeneralClientBootstrap()
535645
.SetConfig(config)
536-
// 添加自定义操作(更新前检查环境)
537-
.AddCustomOption(async () =>
646+
// 统一的更新预检回调：可获取版本信息并决定是否跳过
647+
.AddListenerUpdatePrecheck(updateInfo =>
538648
{
539-
Console.WriteLine("正在检查运行环境...");
540-
await Task.Delay(1000);
541-
// 检查磁盘空间、依赖项等
542-
Console.WriteLine("环境检查完成");
649+
Console.WriteLine($"发现 {updateInfo.Info.Body?.Count ?? 0} 个新版本");
650+
Console.WriteLine("是否现在更新？(y/n)");
651+
var input = Console.ReadLine();
652+
return input?.ToLower() != "y"; // true = 跳过, false = 继续更新
543653
})
544-
// 设置用户跳过选项
545-
.SetCustomSkipOption(() =>
654+
.AddListenerException((sender, args) =>
546655
{
547-
Console.WriteLine("发现新版本,是否更新?(y/n)");
548-
var input = Console.ReadLine();
549-
return input?.ToLower() == "y";
656+
Console.WriteLine($"更新异常：{args.Exception.Message}");
657+
})
658+
.LaunchAsync();
659+
```
660+
661+
### 示例 6：静默更新模式（EnableSilentUpdate）
662+
663+
```csharp
664+
using GeneralUpdate.ClientCore;
665+
using GeneralUpdate.Common.Internal;
666+
using GeneralUpdate.Common.Internal.Bootstrap;
667+
668+
var config = new Configinfo
669+
{
670+
UpdateUrl = "http://your-server.com/api/update/check",
671+
ClientVersion = "1.0.0.0",
672+
InstallPath = AppDomain.CurrentDomain.BaseDirectory
673+
};
674+
675+
// 启用静默更新：后台每 20 分钟轮询，主程序退出后自动启动升级
676+
await new GeneralClientBootstrap()
677+
.SetConfig(config)
678+
.Option(UpdateOption.EnableSilentUpdate, true)
679+
.AddListenerException((sender, args) =>
680+
{
681+
Console.WriteLine($"静默更新异常：{args.Exception.Message}");
682+
})
683+
.LaunchAsync();
684+
```
685+
686+
### 示例 7：使用 ConfiginfoBuilder 零配置构建
687+
688+
```csharp
689+
using GeneralUpdate.ClientCore;
690+
using GeneralUpdate.Common.Shared.Object;
691+
692+
// 从 .csproj 自动提取应用名称、版本和发布者
693+
var config = ConfiginfoBuilder
694+
.Create("http://your-server.com/api/update/check", "your-token", "Bearer")
695+
.Build();
696+
697+
await new GeneralClientBootstrap()
698+
.SetConfig(config)
699+
.AddListenerException((sender, args) =>
700+
{
701+
Console.WriteLine($"更新异常：{args.Exception.Message}");
550702
})
551703
.LaunchAsync();
552704
```
@@ -577,12 +729,21 @@ await new GeneralClientBootstrap()
577729
- 黑名单中的文件和目录不会被更新
578730
- 常用于保护配置文件、用户数据等
579731

732+
6. **更新预检回调**
733+
- `AddListenerUpdatePrecheck` 已替代旧的 `SetCustomSkipOption` + `AddListenerUpdateInfo` 组合
734+
- 强制更新（`IsForcibly = true`）时，回调返回值被忽略，更新始终执行
735+
736+
7. **静默更新**
737+
- `EnableSilentUpdate` 不改变默认更新行为，需显式启用
738+
- 静默模式下，升级助手将在主程序退出事件触发后才启动
739+
580740
### 💡 最佳实践
581741

742+
- **零配置构建**：优先使用 `ConfiginfoBuilder.Create()` 减少手动配置错误
582743
- **备份策略**:始终启用 BackUp 选项,以便更新失败时可以回滚
583744
- **差异更新**:启用 Patch 选项以减少下载量和更新时间
584745
- **错误处理**:实现完整的异常监听和错误处理逻辑
585-
- **用户体验**:在更新前提示用户并允许选择更新时机
746+
- **用户体验**:使用 `AddListenerUpdatePrecheck` 在更新前提示用户并允许选择更新时机
586747
- **测试验证**:在生产环境部署前充分测试更新流程
587748

588749
---

‎website/docs/doc/GeneralUpdate.Core.md‎

Lines changed: 28 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -204,17 +204,6 @@ public GeneralUpdateBootstrap AddListenerException(
204204
Action<object, ExceptionEventArgs> callbackAction)
205205
```
206206

207-
#### SetFieldMappings 方法
208-
209-
设置字段映射表,用于解析驱动包信息。
210-
211-
```csharp
212-
public GeneralUpdateBootstrap SetFieldMappings(Dictionary<string, string> fieldMappings)
213-
```
214-
215-
**参数:**
216-
- `fieldMappings`: 字段映射字典,键为英文字段名,值为本地化字段名
217-
218207
---
219208

220209
## 配置类详解
@@ -387,26 +376,41 @@ catch (Exception e)
387376
}
388377
```
389378

390-
### 示例 2:启用驱动升级
379+
### 示例 2：启用驱动升级
380+
381+
驱动升级通过 `GeneralUpdate.ClientCore` 中的 `Configinfo.DriverDirectory` 字段传入驱动目录，`GeneralUpdate.Core` 中的 `DrivelutionMiddleware` 会自动处理驱动安装。
382+
383+
在 `ClientCore` 侧配置：
391384

392385
```csharp
393-
using GeneralUpdate.Core;
394-
using GeneralUpdate.Common.Internal.Bootstrap;
386+
using GeneralUpdate.ClientCore;
387+
using GeneralUpdate.Common.Shared.Object;
395388

396-
// 中文字段映射表
397-
var fieldMappingsCN = new Dictionary<string, string>
389+
var config = new Configinfo
398390
{
399-
{ "DriverName", "驱动名称" },
400-
{ "DriverVersion", "驱动版本" },
401-
{ "DriverDescription", "驱动描述" },
402-
{ "InstallPath", "安装路径" }
391+
UpdateUrl = "http://your-server.com/api/update/check",
392+
ClientVersion = "1.0.0.0",
393+
InstallPath = AppDomain.CurrentDomain.BaseDirectory,
394+
// 指定包含驱动文件的目录
395+
DriverDirectory = @"C:\Drivers\Updates"
403396
};
404397

398+
await new GeneralClientBootstrap()
399+
.SetConfig(config)
400+
.AddListenerException((sender, args) =>
401+
{
402+
Console.WriteLine($"更新异常: {args.Exception.Message}");
403+
})
404+
.LaunchAsync();
405+
```
406+
407+
在 `Core`（升级助手）侧，无需额外配置，`DrivelutionMiddleware` 会自动从 `PipelineContext` 获取驱动目录并执行驱动安装：
408+
409+
```csharp
410+
using GeneralUpdate.Core;
411+
405412
await new GeneralUpdateBootstrap()
406-
// 设置字段映射表
407-
.SetFieldMappings(fieldMappingsCN)
408-
// 启用驱动更新
409-
.Option(UpdateOption.Drive, true)
413+
.Option(UpdateOption.Drive, true) // 启用驱动升级
410414
.AddListenerException((sender, args) =>
411415
{
412416
Console.WriteLine($"升级异常: {args.Exception.Message}");

‎website/docs/releaselog/GeneralUpdateReleaselog.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,21 @@ tags: [log]
77

88
# 📒Release log
99

10+
### 📍2026-04-10
11+
12+
- Add `AddListenerUpdatePrecheck(Func<UpdateInfoEventArgs, bool>)` to `GeneralClientBootstrap` — unified entry that receives the full version info and returns `true` to skip or `false` to proceed; replaces the combined use of `AddListenerUpdateInfo` + `SetCustomSkipOption`. Forced-update (`IsForcibly`) versions always proceed regardless of the callback return value.
13+
- Remove deprecated `SetCustomSkipOption` from `GeneralClientBootstrap`.
14+
- Add `AddListenerUpdateInfo(Action<object, UpdateInfoEventArgs>)` to `GeneralClientBootstrap` and `GeneralUpdateBootstrap` — dispatched immediately after version validation; each `VersionInfo` entry now carries a new `UpdateLog` field for release notes.
15+
- Add opt-in silent update mode (`UpdateOption.EnableSilentUpdate`) to `GeneralClientBootstrap` — polls every 20 minutes in the background, prepares the update package silently, and launches the updater only after the host process exits.
16+
- Add `ConfiginfoBuilder` — zero-configuration builder for `Configinfo`; only `UpdateUrl`, `Token`, and `Scheme` are required; all other fields are auto-detected from the `.csproj` file and the runtime platform (Windows / Linux / macOS).
17+
- Add `DriverDirectory` field to `Configinfo` / `BaseConfigInfo` and propagate it through `ConfigurationMapper`, `ProcessInfo`, and `PipelineContext` to `DrivelutionMiddleware` for driver update support.
18+
- Remove `SetFieldMappings` from `GeneralUpdateBootstrap`.
19+
- Add full lifecycle tracing (`GeneralTracer`) across `GeneralUpdate.Bowl`, `GeneralUpdate.Extension`, `GeneralUpdate.Core`, `GeneralUpdate.ClientCore`, and `GeneralUpdate.Drivelution`.
20+
- Fix `DefaultCleanMatcher.Match` incorrectly returning `null` for same-name files in different directories.
21+
- Fix orphaned temp files in `BinaryHandler.Dirty` causing patch failures on repeated update runs.
22+
23+
24+
1025
### 📍2026-01-06 10.0.0
1126

1227
- Adapt to .NET 10 upgrade and update the versions of referenced components.

0 commit comments

Comments
 (0)