diff --git a/website/docs/doc/GeneralClient.OSS.md b/website/docs/doc/GeneralClient.OSS.md index 9d8b79e..9eab92c 100644 --- a/website/docs/doc/GeneralClient.OSS.md +++ b/website/docs/doc/GeneralClient.OSS.md @@ -4,15 +4,15 @@ sidebar_position: 9 ### Definition -Namespace: GeneralUpdate.ClientCore +Namespace: GeneralUpdate.Core -Assembly: GeneralUpdate.ClientCore.dll +Assembly: GeneralUpdate.Core.dll **OSS** -OSS stands for Object Storage Service. For those developing server-side technology stacks, this term is likely familiar, as major cloud service providers offer similar services. Simply put, it's a file server. Examples include Alibaba Cloud OSS, Tencent Cloud COS, and Huawei Cloud OBS. While they have different names, their functionalities are quite similar. The new feature of this update component is implemented in a very similar manner, so we chose OSS to name this feature, making it easy for developers to quickly understand its purpose (requires the use of components GeneralUpdate.ClientCore, GeneralUpdate.Core). +OSS stands for Object Storage Service. For those developing server-side technology stacks, this term is likely familiar, as major cloud service providers offer similar services. Simply put, it's a file server. Examples include Alibaba Cloud OSS, Tencent Cloud COS, and Huawei Cloud OBS. While they have different names, their functionalities are quite similar. The new feature of this update component is implemented in a very similar manner, so we chose OSS to name this feature, making it easy for developers to quickly understand its purpose (requires the use of the GeneralUpdate.Core component). @@ -84,8 +84,8 @@ GeneralClientOSS : ```c# using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + var paramsOSS = new GlobalConfigInfoOSS { diff --git a/website/docs/doc/GeneralTracer.md b/website/docs/doc/GeneralTracer.md index ed28e79..6e73a31 100644 --- a/website/docs/doc/GeneralTracer.md +++ b/website/docs/doc/GeneralTracer.md @@ -4,13 +4,13 @@ sidebar_position: 8 ### GeneralTracer -Namespace: GeneralUpdate.Common.Shared +> **合并说明**：`GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`。`GeneralTracer` 现在位于 `GeneralUpdate.Core` 命名空间内，引用 `GeneralUpdate.Core` 包即可自动获得，无需单独引用。 -Assembly: GeneralUpdate.Common.dll +命名空间: `GeneralUpdate.Core` +程序集: `GeneralUpdate.Core.dll` - -**GeneralUpdate.Common** is a common component that provides core underlying code. It generally does not need to be referenced manually and will be imported automatically when you reference **GeneralUpdate.ClientCore** or **GeneralUpdate.Core**. +`GeneralTracer` 提供组件内部异常信息和执行流程的追踪输出。它默认启用，引用 `GeneralUpdate.Core` 时会自动包含。 ```c# public static class GeneralTracer diff --git a/website/docs/doc/GeneralUpdate.ClientCore.md b/website/docs/doc/GeneralUpdate.ClientCore.md deleted file mode 100644 index 9f914e4..0000000 --- a/website/docs/doc/GeneralUpdate.ClientCore.md +++ /dev/null @@ -1,765 +0,0 @@ ---- -sidebar_position: 4 ---- - -# GeneralUpdate.ClientCore - -## 组件概览 - -**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一,提供了丰富的客户端更新功能。该组件运行在主应用程序中,负责检查更新、下载更新包、验证完整性,并在完成后启动升级助手(GeneralUpdate.Core)来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新,而不影响当前运行状态。 - -**命名空间:** `GeneralUpdate.ClientCore` -**程序集:** `GeneralUpdate.ClientCore.dll` - -```csharp -public class GeneralClientBootstrap : AbstractBootstrap -``` - ---- - -## 核心特性 - -### 1. 多版本下载管理 -- 支持同时下载多个版本的更新包 -- 断点续传和下载速度限制 -- 实时下载进度和统计信息 - -### 2. 灵活的配置选项 -- 黑名单机制(文件、格式、目录) -- 自定义更新策略和操作 -- 支持二进制差异更新和全量更新 -- `ConfiginfoBuilder` 零配置构建器,只需三个参数即可完成配置 - -### 3. 完整的事件通知 -- 下载进度、完成、错误事件 -- 更新版本信息通知（`AddListenerUpdateInfo`） -- 统一更新预检回调（`AddListenerUpdatePrecheck`） -- 异常和错误全程监控 - -### 4. 静默更新模式 -- 后台轮询检测新版本（默认每 20 分钟一次） -- 静默下载并准备更新包 -- 在主程序退出后自动启动升级流程 - -### 5. 多平台支持 -- Windows、Linux、macOS 平台支持 -- 自动平台检测和策略选择 - -![Multi Download](imgs/muti_donwload.png) - ---- - -## 快速开始 - -### 安装 - -通过 NuGet 安装 GeneralUpdate.ClientCore: - -```bash -dotnet add package GeneralUpdate.ClientCore -``` - -### 初始化与使用 - -以下示例展示了如何在主程序中配置和启动更新检查: - -```csharp -using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; -using GeneralUpdate.Common.Shared.Object; - -try -{ - Console.WriteLine($"主程序初始化,{DateTime.Now}!"); - - // 配置更新参数 - var configinfo = new Configinfo - { - // 更新验证 API 地址 - UpdateUrl = "http://127.0.0.1:5000/Upgrade/Verification", - // 更新报告 API 地址 - ReportUrl = "http://127.0.0.1:5000/Upgrade/Report", - // 主应用程序名称 - MainAppName = "ClientSample.exe", - // 升级程序名称 - AppName = "UpgradeSample.exe", - // 当前客户端版本 - ClientVersion = "1.0.0.0", - // 升级端版本 - UpgradeClientVersion = "1.0.0.0", - // 安装路径 - InstallPath = Thread.GetDomain().BaseDirectory, - // 产品 ID(用于多产品分支管理) - ProductId = "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - // 应用密钥(用于服务器验证) - AppSecretKey = "dfeb5833-975e-4afb-88f1-6278ee9aeff6" - }; - - // 启动更新流程 - await new GeneralClientBootstrap() - // 监听下载统计信息 - .AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics) - // 监听单个下载完成 - .AddListenerMultiDownloadCompleted(OnMultiDownloadCompleted) - // 监听所有下载完成 - .AddListenerMultiAllDownloadCompleted(OnMultiAllDownloadCompleted) - // 监听下载错误 - .AddListenerMultiDownloadError(OnMultiDownloadError) - // 监听异常 - .AddListenerException(OnException) - // 设置配置 - .SetConfig(configinfo) - // 设置选项 - .Option(UpdateOption.DownloadTimeOut, 60) - .Option(UpdateOption.Encoding, Encoding.Default) - // 启动异步更新 - .LaunchAsync(); - - Console.WriteLine($"主程序已启动,{DateTime.Now}!"); -} -catch (Exception e) -{ - Console.WriteLine(e.Message + "\n" + e.StackTrace); -} - -// 事件处理方法 -void OnMultiDownloadStatistics(object arg1, MultiDownloadStatisticsEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine($"下载版本:{version.Version},速度:{arg2.Speed}," + - $"剩余时间:{arg2.Remaining},进度:{arg2.ProgressPercentage}%"); -} - -void OnMultiDownloadCompleted(object arg1, MultiDownloadCompletedEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine(arg2.IsComplated ? - $"版本 {version.Version} 下载完成!" : - $"版本 {version.Version} 下载失败!"); -} - -void OnMultiAllDownloadCompleted(object arg1, MultiAllDownloadCompletedEventArgs arg2) -{ - Console.WriteLine(arg2.IsAllDownloadCompleted ? - "所有下载任务已完成!" : - $"下载任务失败!失败数量:{arg2.FailedVersions.Count}"); -} - -void OnMultiDownloadError(object arg1, MultiDownloadErrorEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine($"版本 {version.Version} 下载错误:{arg2.Exception}"); -} - -void OnException(object arg1, ExceptionEventArgs arg2) -{ - Console.WriteLine($"更新异常:{arg2.Exception}"); -} -``` - ---- - -## 核心 API 参考 - -### GeneralClientBootstrap 类方法 - -#### LaunchAsync 方法 - -异步启动更新流程。 - -```csharp -public async Task LaunchAsync() -``` - -#### SetConfig 方法 - -设置更新配置信息。 - -```csharp -public GeneralClientBootstrap SetConfig(Configinfo configinfo) -``` - -#### Option 方法 - -设置更新选项。 - -```csharp -public GeneralClientBootstrap Option(UpdateOption option, object value) -``` - -#### SetBlacklist 方法 - -设置更新黑名单,指定不需要更新的文件。 - -```csharp -public GeneralClientBootstrap SetBlacklist(List blackFiles = null, - List blackFormats = null) -``` - -#### AddListenerMultiDownloadStatistics 方法 - -监听下载统计信息(速度、进度、剩余时间等)。 - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadStatistics( - Action callbackAction) -``` - -#### AddListenerMultiDownloadCompleted 方法 - -监听单个更新包下载完成事件。 - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiAllDownloadCompleted 方法 - -监听所有下载任务完成事件。 - -```csharp -public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiDownloadError 方法 - -监听下载错误事件。 - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadError( - Action callbackAction) -``` - -#### AddListenerException 方法 - -监听更新过程中的所有异常。 - -```csharp -public GeneralClientBootstrap AddListenerException( - Action callbackAction) -``` - -#### AddCustomOption 方法 - -添加自定义异步操作,可在更新前后执行自定义逻辑。 - -```csharp -public GeneralClientBootstrap AddCustomOption(Func customFunc) -``` - -#### AddListenerUpdateInfo 方法 - -注册更新版本信息回调。版本验证完成后立即触发,可用于展示更新日志或版本列表。 - -```csharp -public GeneralClientBootstrap AddListenerUpdateInfo( - Action callbackAction) -``` - -**UpdateInfoEventArgs 属性:** -- `Info`: `VersionRespDTO` — 服务端返回的版本响应数据,包含可用版本列表及每个版本的 `UpdateLog` 字段 - -**示例:** -```csharp -.AddListenerUpdateInfo((sender, e) => -{ - foreach (var v in e.Info.Body ?? []) - Console.WriteLine($"{v.Version}: {v.UpdateLog}"); -}) -``` - -#### AddListenerUpdatePrecheck 方法 - -注册更新预检回调,将更新信息通知和跳过更新决策合并为单一入口。回调接收完整的 `UpdateInfoEventArgs`（版本列表、强制更新标志等），返回 `true` 跳过更新，返回 `false` 继续更新。 - -> **注意：** 此方法替代了旧的 `AddListenerUpdateInfo` + `SetCustomSkipOption` 组合写法。`IsForcibly` 为强制更新时，回调返回值将被忽略，更新始终执行。 - -```csharp -public GeneralClientBootstrap AddListenerUpdatePrecheck( - Func precheckFunc) -``` - -**示例:** -```csharp -.AddListenerUpdatePrecheck(updateInfo => -{ - // 在此可访问完整版本信息 - bool userChoseSkip = ShowUpdateDialog(updateInfo.Info); - return userChoseSkip; // true = 跳过, false = 继续更新 -}) -``` - ---- - -## 配置类详解 - -### Configinfo 类 - -```csharp -public class Configinfo -{ - /// - /// 更新检查 API 地址 - /// - public string UpdateUrl { get; set; } - - /// - /// 更新状态报告 API 地址 - /// - public string ReportUrl { get; set; } - - /// - /// 需要启动的应用程序名称(升级程序) - /// - public string AppName { get; set; } - - /// - /// 需要启动的主应用程序名称 - /// - public string MainAppName { get; set; } - - /// - /// 更新日志网页地址 - /// - public string UpdateLogUrl { get; set; } - - /// - /// 应用密钥,与服务器约定用于身份验证和产品分支 - /// - public string AppSecretKey { get; set; } - - /// - /// 当前客户端版本号 - /// - public string ClientVersion { get; set; } - - /// - /// 当前升级客户端版本号 - /// - public string UpgradeClientVersion { get; set; } - - /// - /// 安装路径(用于更新文件逻辑) - /// - public string InstallPath { get; set; } - - /// - /// 黑名单文件列表,这些文件在更新时会被跳过 - /// - public List BlackFiles { get; set; } - - /// - /// 黑名单文件格式列表,这些格式的文件在更新时会被跳过 - /// - public List BlackFormats { get; set; } - - /// - /// 需要跳过的目录路径列表,这些目录不需要更新 - /// - public List SkipDirectorys { get; set; } - - /// - /// 当前产品分支的唯一 ID - /// - public string ProductId { get; set; } - - /// - /// Bowl 监控进程路径,更新完成后启动 Bowl 检查客户端是否正常启动 - /// - public string Bowl { get; set; } - - /// - /// HTTP 请求中用于传递 token 的 Scheme(如 Bearer) - /// - public string Scheme { get; set; } - - /// - /// HTTP 请求中用于身份验证的 Token - /// - public string Token { get; set; } - - /// - /// Linux 平台下的脚本,用于在更新完成后为文件分配权限 - /// - public string Script { get; set; } - - /// - /// 驱动程序目录路径,指定包含需要更新的驱动文件的目录 - /// - public string DriverDirectory { get; set; } -} -``` - -### UpdateOption 枚举 - -```csharp -public enum UpdateOption -{ - /// - /// 更新包文件格式(默认为 Zip) - /// - Format, - - /// - /// 压缩编码格式 - /// - Encoding, - - /// - /// 下载超时时间(秒)。如果不指定,默认超时时间为 30 秒 - /// - DownloadTimeOut, - - /// - /// 是否启用二进制差异更新功能,默认启用;设置为 false 则执行全量覆盖安装 - /// - Patch, - - /// - /// 是否在更新前启用备份功能,默认启用;设置为 false 则不进行备份 - /// - BackUp, - - /// - /// 是否启用静默更新模式。启用后将在后台轮询检测新版本、静默下载更新包, - /// 并在主程序退出后自动启动升级流程,不影响用户的正常使用。 - /// - EnableSilentUpdate -} -``` - ---- - -## ConfiginfoBuilder 构建器 - -`ConfiginfoBuilder` 是零配置模式的 `Configinfo` 构建器,灵感来自 [Velopack](https://github.com/velopack/velopack) 的设计。只需提供三个必填参数即可自动生成完整的平台适配配置。 - -**命名空间:** `GeneralUpdate.Common.Shared.Object` - -### 特性 - -- 仅需三个参数：`UpdateUrl`、`Token`、`Scheme` -- 自动从 `.csproj` 文件提取应用名称、版本号和发布者信息 -- 自动适配 Windows / Linux / macOS 平台差异（路径、权限脚本等） -- 安装路径默认使用宿主程序所在目录（`AppDomain.CurrentDomain.BaseDirectory`） - -### 快速使用 - -```csharp -using GeneralUpdate.Common.Shared.Object; - -// 零配置:从 .csproj 自动提取名称、版本、发布者 -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .Build(); - -await new GeneralClientBootstrap() - .SetConfig(config) - .LaunchAsync(); -``` - -### 自定义覆盖 - -```csharp -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .SetAppName("CustomApp.exe") // 覆盖自动检测的名称 - .SetClientVersion("2.0.0") // 覆盖自动检测的版本 - .SetInstallPath("/custom/path") // 覆盖安装路径 - .Build(); -``` - -### 自动提取规则 - -| 配置项 | 提取来源 | csproj 字段 | 映射目标 | -|--------|----------|-------------|----------| -| 应用名称 | 项目文件 | `` 或文件名 | `AppName`、`MainAppName` | -| 版本号 | 项目文件 | `` | `ClientVersion`、`UpgradeClientVersion` | -| 发布者 | 项目文件 | `` 或 `` | `ProductId` | -| 安装路径 | 宿主程序运行时目录 | — | `InstallPath` | - -### 平台支持 - -| 平台 | 应用名称后缀 | 默认脚本 | -|------|------------|---------| -| Windows | `.exe` | 无 | -| Linux | 无后缀 | chmod 权限脚本 | -| macOS | 无后缀 | chmod 权限脚本 | - ---- - -## 实际使用示例 - -### 示例 1:基本更新流程 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ReportUrl = "http://your-server.com/api/update/report", - MainAppName = "MyApp.exe", - AppName = "Updater.exe", - ClientVersion = "1.0.0.0", - UpgradeClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory, - ProductId = "your-product-id", - AppSecretKey = "your-secret-key" -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - .AddListenerException((sender, args) => - { - Console.WriteLine($"更新异常: {args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### 示例 2:带黑名单的更新 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory, - // 黑名单配置 - BlackFiles = new List { "config.json", "userdata.db" }, - BlackFormats = new List { ".log", ".cache" }, - SkipDirectorys = new List { "logs", "temp" } -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - .LaunchAsync(); -``` - -### 示例 3:自定义更新选项 - -```csharp -using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // 设置下载超时 - .Option(UpdateOption.DownloadTimeOut, 120) - // 设置编码格式 - .Option(UpdateOption.Encoding, Encoding.UTF8) - // 启用二进制差异更新 - .Option(UpdateOption.Patch, true) - // 启用备份 - .Option(UpdateOption.BackUp, true) - .LaunchAsync(); -``` - -### 示例 4:完整的事件监听 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // 下载统计 - .AddListenerMultiDownloadStatistics((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"[{version.Version}] 进度: {args.ProgressPercentage}% | " + - $"速度: {args.Speed} | 剩余: {args.Remaining}"); - }) - // 单个下载完成 - .AddListenerMultiDownloadCompleted((sender, args) => - { - var version = args.Version as VersionInfo; - if (args.IsComplated) - Console.WriteLine($"✓ 版本 {version.Version} 下载成功"); - else - Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); - }) - // 所有下载完成 - .AddListenerMultiAllDownloadCompleted((sender, args) => - { - if (args.IsAllDownloadCompleted) - Console.WriteLine("✓ 所有更新包下载完成,准备安装..."); - else - Console.WriteLine($"✗ 下载失败,共 {args.FailedVersions.Count} 个版本失败"); - }) - // 下载错误 - .AddListenerMultiDownloadError((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); - }) - // 异常处理 - .AddListenerException((sender, args) => - { - Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); - }) - .LaunchAsync(); -``` - -### 示例 5：更新预检与跳过（AddListenerUpdatePrecheck） - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // 统一的更新预检回调：可获取版本信息并决定是否跳过 - .AddListenerUpdatePrecheck(updateInfo => - { - Console.WriteLine($"发现 {updateInfo.Info.Body?.Count ?? 0} 个新版本"); - Console.WriteLine("是否现在更新？(y/n)"); - var input = Console.ReadLine(); - return input?.ToLower() != "y"; // true = 跳过, false = 继续更新 - }) - .AddListenerException((sender, args) => - { - Console.WriteLine($"更新异常：{args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### 示例 6：静默更新模式（EnableSilentUpdate） - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -// 启用静默更新：后台每 20 分钟轮询，主程序退出后自动启动升级 -await new GeneralClientBootstrap() - .SetConfig(config) - .Option(UpdateOption.EnableSilentUpdate, true) - .AddListenerException((sender, args) => - { - Console.WriteLine($"静默更新异常：{args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### 示例 7：使用 ConfiginfoBuilder 零配置构建 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; - -// 从 .csproj 自动提取应用名称、版本和发布者 -var config = ConfiginfoBuilder - .Create("http://your-server.com/api/update/check", "your-token", "Bearer") - .Build(); - -await new GeneralClientBootstrap() - .SetConfig(config) - .AddListenerException((sender, args) => - { - Console.WriteLine($"更新异常：{args.Exception.Message}"); - }) - .LaunchAsync(); -``` - ---- - -## 注意事项与警告 - -### ⚠️ 重要提示 - -1. **版本号格式** - - 版本号必须遵循语义化版本规范(如 1.0.0.0) - - 确保客户端和服务器端版本号格式一致 - -2. **网络连接** - - 确保更新服务器地址可访问 - - 建议实现重试机制处理网络波动 - -3. **进程管理** - - 更新过程会关闭主程序并启动升级助手 - - 确保保存所有用户数据后再执行更新 - -4. **权限要求** - - 在 Windows 上可能需要管理员权限来替换文件 - - 在 Linux/macOS 上需要适当的文件系统权限 - -5. **黑名单使用** - - 黑名单中的文件和目录不会被更新 - - 常用于保护配置文件、用户数据等 - -6. **更新预检回调** - - `AddListenerUpdatePrecheck` 已替代旧的 `SetCustomSkipOption` + `AddListenerUpdateInfo` 组合 - - 强制更新（`IsForcibly = true`）时，回调返回值被忽略，更新始终执行 - -7. **静默更新** - - `EnableSilentUpdate` 不改变默认更新行为，需显式启用 - - 静默模式下，升级助手将在主程序退出事件触发后才启动 - -### 💡 最佳实践 - -- **零配置构建**：优先使用 `ConfiginfoBuilder.Create()` 减少手动配置错误 -- **备份策略**:始终启用 BackUp 选项,以便更新失败时可以回滚 -- **差异更新**:启用 Patch 选项以减少下载量和更新时间 -- **错误处理**:实现完整的异常监听和错误处理逻辑 -- **用户体验**:使用 `AddListenerUpdatePrecheck` 在更新前提示用户并允许选择更新时机 -- **测试验证**:在生产环境部署前充分测试更新流程 - ---- - -## 适用平台 - -| 产品 | 版本 | -| ------------------ | -------------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - ---- - -## 相关资源 - -- **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) -- **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) diff --git a/website/docs/doc/GeneralUpdate.Core.md b/website/docs/doc/GeneralUpdate.Core.md index 563acfb..4b717e3 100644 --- a/website/docs/doc/GeneralUpdate.Core.md +++ b/website/docs/doc/GeneralUpdate.Core.md @@ -6,7 +6,11 @@ sidebar_position: 5 ## 组件概览 -**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一,提供了完整的升级执行能力。与 ClientCore 不同,Core 组件作为独立的升级助手程序运行,负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式,Core 接收来自 ClientCore 的更新指令,并安全地完成主程序的升级任务。 +**GeneralUpdate.Core** 是 GeneralUpdate 框架的统一核心组件。自最新版本起，原先独立的 `GeneralUpdate.ClientCore`（客户端更新管理）和 `GeneralUpdate.Common`（公共基础代码）已合并到 `GeneralUpdate.Core` 中。现在只需引用一个 `GeneralUpdate.Core` 包即可同时获得： + +- **客户端更新管理**（原 ClientCore）：版本检查、更新包下载、完整性验证、拉起升级程序 +- **升级执行引擎**（原 Core）：独立进程升级、文件替换、差分包应用、驱动安装 +- **公共基础设施**（原 Common）：生命周期追踪、下载引擎、序列化等底层能力 **命名空间:** `GeneralUpdate.Core` **程序集:** `GeneralUpdate.Core.dll` @@ -57,9 +61,6 @@ dotnet add package GeneralUpdate.Core 以下示例展示了如何在升级助手程序中配置和启动升级流程: ```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; using GeneralUpdate.Core; try @@ -222,7 +223,7 @@ public enum UpdateOption ### Packet 类 -升级包信息类,由 ClientCore 通过参数传递给 Core: +升级包信息类，由客户端（原 ClientCore，现已合并到 Core）通过参数传递给升级程序： ```csharp public class Packet @@ -351,9 +352,6 @@ public class Packet ### 示例 1:基本升级流程 ```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; using GeneralUpdate.Core; try @@ -383,13 +381,12 @@ catch (Exception e) ### 示例 2：启用驱动升级 -驱动升级通过 `GeneralUpdate.ClientCore` 中的 `Configinfo.DriverDirectory` 字段传入驱动目录，`GeneralUpdate.Core` 中的 `DrivelutionMiddleware` 会自动处理驱动安装。 +驱动升级通过 `Configinfo.DriverDirectory` 字段传入驱动目录（`Configinfo` 现在位于 `GeneralUpdate.Core` 中），`DrivelutionMiddleware` 会自动处理驱动安装。 -在 `ClientCore` 侧配置： +在客户端侧配置： ```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; var config = new Configinfo { @@ -427,8 +424,6 @@ await new GeneralUpdateBootstrap() ```csharp using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; await new GeneralUpdateBootstrap() // 下载统计 @@ -485,8 +480,6 @@ await new GeneralUpdateBootstrap() ```csharp using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; // 记录升级开始时间 var startTime = DateTime.Now; @@ -531,7 +524,7 @@ await new GeneralUpdateBootstrap() - 升级时主程序必须完全关闭,否则文件替换会失败 2. **参数传递** - - ClientCore 通过 Base64 编码的参数传递配置给 Core + - 客户端通过 Base64 编码的参数传递配置给 Core（原 ClientCore 现已合并到 Core） - 确保参数传递过程中不会被截断或损坏 3. **文件权限** @@ -544,7 +537,7 @@ await new GeneralUpdateBootstrap() 5. **回滚机制** - Core 不直接提供回滚功能,但保留了备份文件 - - 如需回滚,可使用 ClientCore 的备份功能 + - Core 提供内置的备份与回滚机制，无需额外组件 ### 💡 最佳实践 @@ -571,4 +564,5 @@ await new GeneralUpdateBootstrap() - **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) - **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) -- **相关组件**:[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) +- **相关组件**:[GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) | [GeneralUpdate.Drivelution](./GeneralUpdate.Drivelution.md) +- **迁移说明**：`GeneralUpdate.ClientCore` 和 `GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`。迁移时只需将 `using GeneralUpdate.ClientCore` / `using GeneralUpdate.Common.*` 替换为 `using GeneralUpdate.Core`，并移除旧的 NuGet 包引用。 diff --git a/website/docs/doc/GeneralUpdate.Differential.md b/website/docs/doc/GeneralUpdate.Differential.md index 18c1262..71cd3b0 100644 --- a/website/docs/doc/GeneralUpdate.Differential.md +++ b/website/docs/doc/GeneralUpdate.Differential.md @@ -402,7 +402,7 @@ await manager.GeneratePatchWithProgressAsync( 5. **备份建议** - 在应用补丁前建议备份原始文件 - - 可以使用 ClientCore 的 BackUp 选项自动备份 + - 可以使用 Core 的 BackUp 选项自动备份 ### 💡 最佳实践 diff --git a/website/docs/doc/GeneralUpdate.Extension.md b/website/docs/doc/GeneralUpdate.Extension.md index ad1e7ee..e5f6cd8 100644 --- a/website/docs/doc/GeneralUpdate.Extension.md +++ b/website/docs/doc/GeneralUpdate.Extension.md @@ -872,7 +872,7 @@ if (!Directory.Exists(backupDir)) ### 另请参阅 -- [GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) - 主客户端更新组件 +- [GeneralUpdate.Core](./GeneralUpdate.Core.md) - 主客户端更新组件 - [GeneralUpdate.Core](./GeneralUpdate.Core.md) - 核心更新逻辑 - [GitHub 源代码](https://github.com/GeneralLibrary/GeneralUpdate/tree/master/src/c%23/GeneralUpdate.Extension) - 完整源代码和更多示例 - [快速入门指南](../quickstart/Quik%20start.md) - GeneralUpdate 入门 diff --git a/website/docs/doc/UpgradeHub.md b/website/docs/doc/UpgradeHub.md index b5ac4c5..feb255a 100644 --- a/website/docs/doc/UpgradeHub.md +++ b/website/docs/doc/UpgradeHub.md @@ -6,10 +6,10 @@ sidebar_position: 7 ## 组件概览 -**UpgradeHubService** 是基于 SignalR 的实时版本推送服务，集成在 `GeneralUpdate.ClientCore` 中。服务端通过 `UpgradeHub` 向已连接的客户端主动推送版本更新通知，客户端通过 `UpgradeHubService` 订阅并接收消息，支持点对点（一对一）和广播（一对多）两种推送模式。 +**UpgradeHubService** 是基于 SignalR 的实时版本推送服务，集成在 `GeneralUpdate.Core` 中。服务端通过 `UpgradeHub` 向已连接的客户端主动推送版本更新通知，客户端通过 `UpgradeHubService` 订阅并接收消息，支持点对点（一对一）和广播（一对多）两种推送模式。 -**命名空间：** `GeneralUpdate.ClientCore.Hubs` -**程序集：** `GeneralUpdate.ClientCore.dll` +**命名空间：** `GeneralUpdate.Core.Hubs` +**程序集：** `GeneralUpdate.Core.dll` ```csharp public class UpgradeHubService : IUpgradeHubService @@ -45,10 +45,10 @@ public class UpgradeHubService : IUpgradeHubService ### 安装 -`UpgradeHubService` 包含在 `GeneralUpdate.ClientCore` 中，无需单独安装： +`UpgradeHubService` 包含在 `GeneralUpdate.Core` 中，无需单独安装： ```bash -dotnet add package GeneralUpdate.ClientCore +dotnet add package GeneralUpdate.Core ``` ### 初始化与使用 @@ -56,7 +56,7 @@ dotnet add package GeneralUpdate.ClientCore 以下示例展示了如何在客户端应用中接收服务端推送的版本更新消息： ```csharp -using GeneralUpdate.ClientCore.Hubs; +using GeneralUpdate.Core.Hubs; // 创建 UpgradeHubService 实例 // url — SignalR Hub 订阅地址 @@ -239,7 +239,7 @@ public Task DisposeAsync() ### 示例 1：基本推送订阅 ```csharp -using GeneralUpdate.ClientCore.Hubs; +using GeneralUpdate.Core.Hubs; var hub = new UpgradeHubService("http://localhost:5000/UpgradeHub", appkey: Guid.NewGuid().ToString()); @@ -255,7 +255,7 @@ await hub.StartAsync(); ### 示例 2：完整生命周期管理 ```csharp -using GeneralUpdate.ClientCore.Hubs; +using GeneralUpdate.Core.Hubs; var hub = new UpgradeHubService( "http://localhost:5000/UpgradeHub", @@ -285,12 +285,12 @@ finally ```csharp using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.ClientCore.Hubs; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; -using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; +using GeneralUpdate.Core.Hubs; + + + + // 1. 启动 SignalR 推送监听 var hub = new UpgradeHubService("http://localhost:5000/UpgradeHub", @@ -363,4 +363,4 @@ await new GeneralClientBootstrap() - **示例代码：** [查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Push/Program.cs) - **主仓库：** [GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) -- **相关组件：** [GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Core](./GeneralUpdate.Core.md) +- **相关组件：** [GeneralUpdate.Core](./GeneralUpdate.Core.md) | [GeneralUpdate.Core](./GeneralUpdate.Core.md) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md index 69dbe8f..7441252 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md @@ -4,15 +4,15 @@ sidebar_position: 9 ### Definition -Namespace: GeneralUpdate.ClientCore +Namespace: GeneralUpdate.Core -Assembly: GeneralUpdate.ClientCore.dll +Assembly: GeneralUpdate.Core.dll **OSS** -OSS stands for Object Storage Service. For those developing server-side technology stacks, this term is likely familiar, as major cloud service providers offer similar services. Simply put, it's a file server. Examples include Alibaba Cloud OSS, Tencent Cloud COS, and Huawei Cloud OBS. While they have different names, their functionalities are quite similar. The new feature of this update component is implemented in a very similar manner, so we chose OSS to name this feature, making it easy for developers to quickly understand its purpose (requires the use of components GeneralUpdate.ClientCore, GeneralUpdate.Core). +OSS stands for Object Storage Service. For those developing server-side technology stacks, this term is likely familiar, as major cloud service providers offer similar services. Simply put, it's a file server. Examples include Alibaba Cloud OSS, Tencent Cloud COS, and Huawei Cloud OBS. While they have different names, their functionalities are quite similar. The new feature of this update component is implemented in a very similar manner, so we chose OSS to name this feature, making it easy for developers to quickly understand its purpose (requires the use of the GeneralUpdate.Core component). @@ -83,8 +83,8 @@ GeneralClientOSS : ```c# using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + var paramsOSS = new GlobalConfigInfoOSS { diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md index ed28e79..8f07cce 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md @@ -4,13 +4,13 @@ sidebar_position: 8 ### GeneralTracer -Namespace: GeneralUpdate.Common.Shared +> **Merge notice**: `GeneralUpdate.Common` has been merged into `GeneralUpdate.Core`. `GeneralTracer` now lives in the `GeneralUpdate.Core` namespace and is automatically included when you reference the `GeneralUpdate.Core` package — no separate reference needed. -Assembly: GeneralUpdate.Common.dll +Namespace: `GeneralUpdate.Core` +Assembly: `GeneralUpdate.Core.dll` - -**GeneralUpdate.Common** is a common component that provides core underlying code. It generally does not need to be referenced manually and will be imported automatically when you reference **GeneralUpdate.ClientCore** or **GeneralUpdate.Core**. +`GeneralTracer` provides trace output of internal exception information and execution flow. It is enabled by default and is included automatically when you reference `GeneralUpdate.Core`. ```c# public static class GeneralTracer diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.ClientCore.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.ClientCore.md deleted file mode 100644 index c4a7549..0000000 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.ClientCore.md +++ /dev/null @@ -1,768 +0,0 @@ ---- -sidebar_position: 4 ---- - -# GeneralUpdate.ClientCore - -## Component Overview - -**GeneralUpdate.ClientCore** is one of the core components of the GeneralUpdate framework, providing rich client-side update functionalities. This component runs in the main application and is responsible for checking updates, downloading update packages, validating integrity, and then launching the upgrade assistant (GeneralUpdate.Core) to perform actual file replacement operations upon completion. The design philosophy of ClientCore is to enable the main program to safely check and prepare updates without affecting the current running state. - -**Namespace:** `GeneralUpdate.ClientCore` -**Assembly:** `GeneralUpdate.ClientCore.dll` - -```csharp -public class GeneralClientBootstrap : AbstractBootstrap -``` - ---- - -## Core Features - -### 1. Multi-Version Download Management -- Support downloading multiple version update packages simultaneously -- Resume download and download speed limiting -- Real-time download progress and statistics - -### 2. Flexible Configuration Options -- Blacklist mechanism (files, formats, directories) -- Custom update strategies and operations -- Support binary differential updates and full updates -- `ConfiginfoBuilder` zero-configuration builder requiring only three parameters - -### 3. Comprehensive Event Notifications -- Download progress, completion, and error events -- Update version info notification (`AddListenerUpdateInfo`) -- Unified update precheck callback (`AddListenerUpdatePrecheck`) -- Exception and error monitoring throughout the process - -### 4. Silent Update Mode -- Background polling for new versions (default every 20 minutes) -- Silent download and update package preparation -- Automatically launches the updater after the host process exits - -### 5. Multi-Platform Support -- Windows, Linux, macOS platform support -- Automatic platform detection and strategy selection - -![Multi Download](imgs/muti_donwload.png) - ---- - -## Quick Start - -### Installation - -Install GeneralUpdate.ClientCore via NuGet: - -```bash -dotnet add package GeneralUpdate.ClientCore -``` - -### Initialization and Usage - -The following example demonstrates how to configure and launch update checking in the main program: - -```csharp -using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; -using GeneralUpdate.Common.Shared.Object; - -try -{ - Console.WriteLine($"Main program initialization, {DateTime.Now}!"); - - // Configure update parameters - var configinfo = new Configinfo - { - // Update verification API address - UpdateUrl = "http://127.0.0.1:5000/Upgrade/Verification", - // Update report API address - ReportUrl = "http://127.0.0.1:5000/Upgrade/Report", - // Main application name - MainAppName = "ClientSample.exe", - // Upgrade program name - AppName = "UpgradeSample.exe", - // Current client version - ClientVersion = "1.0.0.0", - // Upgrade client version - UpgradeClientVersion = "1.0.0.0", - // Installation path - InstallPath = Thread.GetDomain().BaseDirectory, - // Product ID (for multi-product branch management) - ProductId = "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - // App secret key (for server verification) - AppSecretKey = "dfeb5833-975e-4afb-88f1-6278ee9aeff6" - }; - - // Launch update process - await new GeneralClientBootstrap() - // Listen for download statistics - .AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics) - // Listen for single download completion - .AddListenerMultiDownloadCompleted(OnMultiDownloadCompleted) - // Listen for all downloads completion - .AddListenerMultiAllDownloadCompleted(OnMultiAllDownloadCompleted) - // Listen for download errors - .AddListenerMultiDownloadError(OnMultiDownloadError) - // Listen for exceptions - .AddListenerException(OnException) - // Set configuration - .SetConfig(configinfo) - // Set options - .Option(UpdateOption.DownloadTimeOut, 60) - .Option(UpdateOption.Encoding, Encoding.Default) - // Launch async update - .LaunchAsync(); - - Console.WriteLine($"Main program started, {DateTime.Now}!"); -} -catch (Exception e) -{ - Console.WriteLine(e.Message + "\n" + e.StackTrace); -} - -// Event handler methods -void OnMultiDownloadStatistics(object arg1, MultiDownloadStatisticsEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine($"Download version: {version.Version}, Speed: {arg2.Speed}, " + - $"Remaining time: {arg2.Remaining}, Progress: {arg2.ProgressPercentage}%"); -} - -void OnMultiDownloadCompleted(object arg1, MultiDownloadCompletedEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine(arg2.IsComplated ? - $"Version {version.Version} download complete!" : - $"Version {version.Version} download failed!"); -} - -void OnMultiAllDownloadCompleted(object arg1, MultiAllDownloadCompletedEventArgs arg2) -{ - Console.WriteLine(arg2.IsAllDownloadCompleted ? - "All download tasks completed!" : - $"Download tasks failed! Failed count: {arg2.FailedVersions.Count}"); -} - -void OnMultiDownloadError(object arg1, MultiDownloadErrorEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine($"Version {version.Version} download error: {arg2.Exception}"); -} - -void OnException(object arg1, ExceptionEventArgs arg2) -{ - Console.WriteLine($"Update exception: {arg2.Exception}"); -} -``` - ---- - -## Core API Reference - -### GeneralClientBootstrap Class Methods - -#### LaunchAsync Method - -Launch the update process asynchronously. - -```csharp -public async Task LaunchAsync() -``` - -#### SetConfig Method - -Set update configuration information. - -```csharp -public GeneralClientBootstrap SetConfig(Configinfo configinfo) -``` - -#### Option Method - -Set update options. - -```csharp -public GeneralClientBootstrap Option(UpdateOption option, object value) -``` - -#### SetBlacklist Method - -Set update blacklist to specify files that should not be updated. - -```csharp -public GeneralClientBootstrap SetBlacklist(List blackFiles = null, - List blackFormats = null) -``` - -#### AddListenerMultiDownloadStatistics Method - -Listen for download statistics (speed, progress, remaining time, etc.). - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadStatistics( - Action callbackAction) -``` - -#### AddListenerMultiDownloadCompleted Method - -Listen for single update package download completion event. - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiAllDownloadCompleted Method - -Listen for all download tasks completion event. - -```csharp -public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiDownloadError Method - -Listen for download error events. - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadError( - Action callbackAction) -``` - -#### AddListenerException Method - -Listen for all exceptions during the update process. - -```csharp -public GeneralClientBootstrap AddListenerException( - Action callbackAction) -``` - -#### AddCustomOption Method - -Add custom asynchronous operations that can execute custom logic before or after updates. - -```csharp -public GeneralClientBootstrap AddCustomOption(Func customFunc) -``` - -#### AddListenerUpdateInfo Method - -Register an update version info callback. Triggered immediately after version validation and can be used to display changelogs or version lists. - -```csharp -public GeneralClientBootstrap AddListenerUpdateInfo( - Action callbackAction) -``` - -**UpdateInfoEventArgs Properties:** -- `Info`: `VersionRespDTO` — version response data from the server, containing the list of available versions and a `UpdateLog` field per version - -**Example:** -```csharp -.AddListenerUpdateInfo((sender, e) => -{ - foreach (var v in e.Info.Body ?? []) - Console.WriteLine($"{v.Version}: {v.UpdateLog}"); -}) -``` - -#### AddListenerUpdatePrecheck Method - -Register an update precheck callback that merges version-info notification and skip-update decision into a single entry point. The callback receives the full `UpdateInfoEventArgs` (version list, forced-update flag, etc.) and returns `true` to skip or `false` to proceed. - -> **Note:** This method replaces the old `AddListenerUpdateInfo` + `SetCustomSkipOption` combination. When `IsForcibly` is set to true for a version, the callback return value is ignored and the update always proceeds. - -```csharp -public GeneralClientBootstrap AddListenerUpdatePrecheck( - Func precheckFunc) -``` - -**Example:** -```csharp -.AddListenerUpdatePrecheck(updateInfo => -{ - // Full version details available here - bool userChoseSkip = ShowUpdateDialog(updateInfo.Info); - return userChoseSkip; // true = skip, false = proceed -}) -``` - ---- - -## Configuration Class Details - -### Configinfo Class - -```csharp -public class Configinfo -{ - /// - /// Update check API address - /// - public string UpdateUrl { get; set; } - - /// - /// Update status report API address - /// - public string ReportUrl { get; set; } - - /// - /// Application name to be launched (upgrade program) - /// - public string AppName { get; set; } - - /// - /// Main application name to be launched - /// - public string MainAppName { get; set; } - - /// - /// Update log webpage address - /// - public string UpdateLogUrl { get; set; } - - /// - /// Application secret key, agreed upon with server for authentication and product branching - /// - public string AppSecretKey { get; set; } - - /// - /// Current client version number - /// - public string ClientVersion { get; set; } - - /// - /// Current upgrade client version number - /// - public string UpgradeClientVersion { get; set; } - - /// - /// Installation path (used for update file logic) - /// - public string InstallPath { get; set; } - - /// - /// Blacklist file list, these files will be skipped during updates - /// - public List BlackFiles { get; set; } - - /// - /// Blacklist file format list, files with these formats will be skipped during updates - /// - public List BlackFormats { get; set; } - - /// - /// Directory path list to be skipped that do not require updates - /// - public List SkipDirectorys { get; set; } - - /// - /// Unique ID of the current product branch - /// - public string ProductId { get; set; } - - /// - /// Bowl monitoring process path, starts after updates to check if the client starts normally - /// - public string Bowl { get; set; } - - /// - /// Scheme used for passing token in HTTP requests (e.g., Bearer) - /// - public string Scheme { get; set; } - - /// - /// Token used for authentication in HTTP requests - /// - public string Token { get; set; } - - /// - /// Script for Linux platform to assign permissions to files after update completion - /// - public string Script { get; set; } - - /// - /// Driver directory path specifying the directory containing driver files to be updated - /// - public string DriverDirectory { get; set; } -} -``` - -### UpdateOption Enum - -```csharp -public enum UpdateOption -{ - /// - /// Update package file format (default is Zip) - /// - Format, - - /// - /// Compression encoding format - /// - Encoding, - - /// - /// Download timeout duration (seconds). Default is 30 seconds if not specified - /// - DownloadTimeOut, - - /// - /// Whether to enable binary differential update function, enabled by default; - /// if set to false, full overwrite installation will be performed - /// - Patch, - - /// - /// Whether to enable backup function before update, enabled by default; - /// if set to false, no backup will be performed - /// - BackUp, - - /// - /// Whether to enable silent update mode. When enabled, the client polls for new versions - /// in the background, silently prepares the update package, and launches the updater - /// only after the host application exits — without interrupting normal user operation. - /// - EnableSilentUpdate -} -``` - ---- - -## ConfiginfoBuilder - -`ConfiginfoBuilder` is a zero-configuration builder for `Configinfo`, inspired by [Velopack](https://github.com/velopack/velopack)'s design philosophy. Only three required parameters are needed; all other fields are auto-detected from the `.csproj` file and the runtime platform. - -**Namespace:** `GeneralUpdate.Common.Shared.Object` - -### Features - -- Only three parameters required: `UpdateUrl`, `Token`, `Scheme` -- Auto-extracts app name, version, and publisher from `.csproj` file -- Automatically adapts to Windows / Linux / macOS platform differences (paths, permission scripts, etc.) -- Install path defaults to the host program's base directory (`AppDomain.CurrentDomain.BaseDirectory`) - -### Quick Usage - -```csharp -using GeneralUpdate.Common.Shared.Object; - -// Zero-configuration: name, version, and publisher auto-extracted from .csproj -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .Build(); - -await new GeneralClientBootstrap() - .SetConfig(config) - .LaunchAsync(); -``` - -### Custom Overrides - -```csharp -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .SetAppName("CustomApp.exe") // Override auto-detected name - .SetClientVersion("2.0.0") // Override auto-detected version - .SetInstallPath("/custom/path") // Override install path - .Build(); -``` - -### Auto-Extraction Rules - -| Config Item | Extraction Source | csproj Field | Maps To | -|-------------|------------------|--------------|---------| -| App Name | Project file | `` or filename | `AppName`, `MainAppName` | -| Version | Project file | `` | `ClientVersion`, `UpgradeClientVersion` | -| Publisher | Project file | `` or `` | `ProductId` | -| Install Path | Host program runtime directory | — | `InstallPath` | - -### Platform Support - -| Platform | App Name Suffix | Default Script | -|----------|----------------|----------------| -| Windows | `.exe` | None | -| Linux | No suffix | chmod permission script | -| macOS | No suffix | chmod permission script | - ---- - -## Practical Usage Examples - -### Example 1: Basic Update Process - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ReportUrl = "http://your-server.com/api/update/report", - MainAppName = "MyApp.exe", - AppName = "Updater.exe", - ClientVersion = "1.0.0.0", - UpgradeClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory, - ProductId = "your-product-id", - AppSecretKey = "your-secret-key" -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - .AddListenerException((sender, args) => - { - Console.WriteLine($"Update exception: {args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### Example 2: Update with Blacklist - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory, - // Blacklist configuration - BlackFiles = new List { "config.json", "userdata.db" }, - BlackFormats = new List { ".log", ".cache" }, - SkipDirectorys = new List { "logs", "temp" } -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - .LaunchAsync(); -``` - -### Example 3: Custom Update Options - -```csharp -using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // Set download timeout - .Option(UpdateOption.DownloadTimeOut, 120) - // Set encoding format - .Option(UpdateOption.Encoding, Encoding.UTF8) - // Enable binary differential update - .Option(UpdateOption.Patch, true) - // Enable backup - .Option(UpdateOption.BackUp, true) - .LaunchAsync(); -``` - -### Example 4: Complete Event Listening - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // Download statistics - .AddListenerMultiDownloadStatistics((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"[{version.Version}] Progress: {args.ProgressPercentage}% | " + - $"Speed: {args.Speed} | Remaining: {args.Remaining}"); - }) - // Single download completed - .AddListenerMultiDownloadCompleted((sender, args) => - { - var version = args.Version as VersionInfo; - if (args.IsComplated) - Console.WriteLine($"✓ Version {version.Version} download succeeded"); - else - Console.WriteLine($"✗ Version {version.Version} download failed"); - }) - // All downloads completed - .AddListenerMultiAllDownloadCompleted((sender, args) => - { - if (args.IsAllDownloadCompleted) - Console.WriteLine("✓ All update packages downloaded, preparing installation..."); - else - Console.WriteLine($"✗ Download failed, {args.FailedVersions.Count} versions failed"); - }) - // Download error - .AddListenerMultiDownloadError((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"✗ Version {version.Version} download error: {args.Exception.Message}"); - }) - // Exception handling - .AddListenerException((sender, args) => - { - Console.WriteLine($"⚠ Update exception: {args.Exception.Message}\n{args.Exception.StackTrace}"); - }) - .LaunchAsync(); -``` - -### Example 5: Update Precheck and Skip (AddListenerUpdatePrecheck) - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // Unified precheck callback: access version info and decide whether to skip - .AddListenerUpdatePrecheck(updateInfo => - { - Console.WriteLine($"Found {updateInfo.Info.Body?.Count ?? 0} new version(s)"); - Console.WriteLine("Update now? (y/n)"); - var input = Console.ReadLine(); - return input?.ToLower() != "y"; // true = skip, false = proceed - }) - .AddListenerException((sender, args) => - { - Console.WriteLine($"Update exception: {args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### Example 6: Silent Update Mode (EnableSilentUpdate) - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -// Enable silent update: polls in background every 20 min, launches updater after process exit -await new GeneralClientBootstrap() - .SetConfig(config) - .Option(UpdateOption.EnableSilentUpdate, true) - .AddListenerException((sender, args) => - { - Console.WriteLine($"Silent update exception: {args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### Example 7: Zero-Configuration with ConfiginfoBuilder - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; - -// Auto-extracts app name, version, and publisher from .csproj -var config = ConfiginfoBuilder - .Create("http://your-server.com/api/update/check", "your-token", "Bearer") - .Build(); - -await new GeneralClientBootstrap() - .SetConfig(config) - .AddListenerException((sender, args) => - { - Console.WriteLine($"Update exception: {args.Exception.Message}"); - }) - .LaunchAsync(); -``` - ---- - -## Notes and Warnings - -### ⚠️ Important Notes - -1. **Version Number Format** - - Version numbers must follow semantic versioning specification (e.g., 1.0.0.0) - - Ensure version number format is consistent between client and server - -2. **Network Connection** - - Ensure update server address is accessible - - Recommend implementing retry mechanism to handle network fluctuations - -3. **Process Management** - - The update process will close the main program and launch the upgrade assistant - - Ensure all user data is saved before executing the update - -4. **Permission Requirements** - - Administrator privileges may be required on Windows to replace files - - Appropriate file system permissions are required on Linux/macOS - -5. **Blacklist Usage** - - Files and directories in the blacklist will not be updated - - Commonly used to protect configuration files, user data, etc. - -6. **Update Precheck Callback** - - `AddListenerUpdatePrecheck` replaces the old `SetCustomSkipOption` + `AddListenerUpdateInfo` combination - - When `IsForcibly` is `true` for a version, the callback return value is ignored and the update always proceeds - -7. **Silent Update** - - `EnableSilentUpdate` does not change default update behavior; it must be explicitly enabled - - In silent mode, the updater is launched only after the host process exit event fires - -### 💡 Best Practices - -- **Zero-Configuration**: Prefer `ConfiginfoBuilder.Create()` to reduce manual configuration errors -- **Backup Strategy**: Always enable the BackUp option to allow rollback in case of update failure -- **Differential Update**: Enable the Patch option to reduce download size and update time -- **Error Handling**: Implement complete exception listening and error handling logic -- **User Experience**: Use `AddListenerUpdatePrecheck` to prompt users before updating and allow them to choose update timing -- **Testing**: Thoroughly test the update process before production deployment - ---- - -## Applicable Platforms - -| Product | Version | -| -------------- | ---------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - ---- - -## Related Resources - -- **Sample Code**: [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) -- **Main Repository**: [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md index bfd8514..3eb8c64 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md @@ -6,7 +6,11 @@ sidebar_position: 5 ## Component Overview -**GeneralUpdate.Core** is one of the most essential components of the GeneralUpdate framework, providing complete upgrade execution capabilities. Unlike ClientCore, the Core component runs as an independent upgrade assistant program and is responsible for performing actual file replacement, version upgrades, and system update operations after the main program closes. Through process startup and parameter passing, Core receives update instructions from ClientCore and safely completes the main program's upgrade tasks. +**GeneralUpdate.Core** is the unified core component of the GeneralUpdate framework. As of the latest version, the previously separate `GeneralUpdate.ClientCore` (client-side update management) and `GeneralUpdate.Common` (shared foundation) have been merged into `GeneralUpdate.Core`. A single `GeneralUpdate.Core` package reference now provides: + +- **Client update management** (formerly ClientCore): version checking, package download, integrity validation, launching the upgrade process +- **Upgrade execution engine** (formerly Core): standalone process upgrade, file replacement, differential patch application, driver installation +- **Shared infrastructure** (formerly Common): lifecycle tracing, download engine, serialization, and other low-level capabilities **Namespace:** `GeneralUpdate.Core` **Assembly:** `GeneralUpdate.Core.dll` @@ -57,9 +61,6 @@ dotnet add package GeneralUpdate.Core The following example demonstrates how to configure and launch the upgrade process in the upgrade assistant program: ```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; using GeneralUpdate.Core; try @@ -222,7 +223,7 @@ public enum UpdateOption ### Packet Class -Upgrade package information class, passed from ClientCore to Core via parameters: +Upgrade package information class, passed from the client (formerly ClientCore, now merged into Core) to the upgrade process via parameters: ```csharp public class Packet @@ -351,9 +352,6 @@ public class Packet ### Example 1: Basic Upgrade Process ```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; using GeneralUpdate.Core; try @@ -383,13 +381,12 @@ catch (Exception e) ### Example 2: Enable Driver Upgrade -Driver upgrades are configured via the `DriverDirectory` field in `Configinfo` on the `GeneralUpdate.ClientCore` side. The `DrivelutionMiddleware` in `GeneralUpdate.Core` automatically processes driver installation. +Driver upgrades are configured via the `DriverDirectory` field in `Configinfo` (now located in `GeneralUpdate.Core`). The `DrivelutionMiddleware` automatically processes driver installation. -On the `ClientCore` side: +On the client side: ```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; var config = new Configinfo { @@ -427,8 +424,6 @@ await new GeneralUpdateBootstrap() ```csharp using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; await new GeneralUpdateBootstrap() // Download statistics @@ -485,8 +480,7 @@ await new GeneralUpdateBootstrap() ```csharp using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; + // Record upgrade start time var startTime = DateTime.Now; @@ -531,7 +525,7 @@ await new GeneralUpdateBootstrap() - The main program must be completely closed during upgrade, otherwise file replacement will fail 2. **Parameter Passing** - - ClientCore passes configuration to Core via Base64 encoded parameters + - Client passes configuration to Core via Base64 encoded parameters (formerly ClientCore, now merged into Core) - Ensure parameters are not truncated or corrupted during passing 3. **File Permissions** @@ -544,7 +538,7 @@ await new GeneralUpdateBootstrap() 5. **Rollback Mechanism** - Core does not directly provide rollback functionality, but backup files are preserved - - For rollback, use ClientCore's backup functionality + - Core provides built-in backup and rollback, no extra components needed ### 💡 Best Practices @@ -571,4 +565,5 @@ await new GeneralUpdateBootstrap() - **Sample Code**: [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) - **Main Repository**: [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) -- **Related Components**: [GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) +- **Related Components**: [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) | [GeneralUpdate.Drivelution](./GeneralUpdate.Drivelution.md) +- **Migration note**: `GeneralUpdate.ClientCore` and `GeneralUpdate.Common` have been merged into `GeneralUpdate.Core`. When migrating, replace `using GeneralUpdate.ClientCore` / `using GeneralUpdate.Common.*` with `using GeneralUpdate.Core` and remove the old NuGet package references. diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md index 48475aa..781c7ec 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md @@ -403,7 +403,7 @@ await manager.GeneratePatchWithProgressAsync( 5. **Backup Recommendations** - Recommended to backup original files before applying patches - - Can use ClientCore's BackUp option for automatic backup + - Can use Core's BackUp option for automatic backup ### 💡 Best Practices diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md index 92c6614..b3dbf8e 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md @@ -872,7 +872,7 @@ if (!Directory.Exists(backupDir)) ### See Also -- [GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) - Main client update component +- [GeneralUpdate.Core](./GeneralUpdate.Core.md) - Main client update component - [GeneralUpdate.Core](./GeneralUpdate.Core.md) - Core update logic - [GitHub Source Code](https://github.com/GeneralLibrary/GeneralUpdate/tree/master/src/c%23/GeneralUpdate.Extension) - Complete source code and more examples - [Quick Start Guide](../quickstart/Quik%20start.md) - Getting started with GeneralUpdate diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md index fb0fb19..a5b1728 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md @@ -4,9 +4,9 @@ sidebar_position: 7 ### Definition -Namespace: GeneralUpdate.ClientCore.Hubs +Namespace: GeneralUpdate.Core.Hubs -Assembly: GeneralUpdate.ClientCore.dll +Assembly: GeneralUpdate.Core.dll diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md index 6242297..89dea99 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralClient.OSS.md @@ -4,15 +4,15 @@ sidebar_position: 9 ### 定义 -命名空间：GeneralUpdate.ClientCore +命名空间：GeneralUpdate.Core -程序集：GeneralUpdate.ClientCore.dll +程序集：GeneralUpdate.Core.dll **OSS** -OSS的全称是对象存储服务（Object Storage Service），做服务端技术栈开发的小伙伴肯定对这个不陌生在 各大云服务器厂商都会提供类似的服务,说简单点就是一个文件服务器。例如：阿里云OSS、腾讯云COS、华为云OBS，其实它们只是名字不一样功能服务都差不多。然后本更新组件新功能的实现思路非常相似那么就 选择了OSS来为该功能命名，而且方便开发者一眼能get到这个功能的作用（需要使用组件 GeneralUpdate.ClientCore、GeneralUpdate.Core）。 +OSS的全称是对象存储服务（Object Storage Service），做服务端技术栈开发的小伙伴肯定对这个不陌生在 各大云服务器厂商都会提供类似的服务,说简单点就是一个文件服务器。例如：阿里云OSS、腾讯云COS、华为云OBS，其实它们只是名字不一样功能服务都差不多。然后本更新组件新功能的实现思路非常相似那么就 选择了OSS来为该功能命名，而且方便开发者一眼能get到这个功能的作用（需要使用组件 GeneralUpdate.Core）。 @@ -83,8 +83,8 @@ GeneralClientOSS： ```c# using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + var paramsOSS = new GlobalConfigInfoOSS { diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md index 150aaa7..20f2117 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralTracer.md @@ -4,13 +4,13 @@ sidebar_position: 8 ### GeneralTracer -命名空间：GeneralUpdate.Common.Shared +> **合并说明**：`GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`。`GeneralTracer` 现在位于 `GeneralUpdate.Core` 命名空间内，引用 `GeneralUpdate.Core` 包即可自动获得，无需单独引用。 -程序集：GeneralUpdate.Common.dll +命名空间：`GeneralUpdate.Core` +程序集：`GeneralUpdate.Core.dll` - -GeneralUpdate.Common是公共组件，提供核心组件基础代码一般不需要手动引用，引用GeneralUpdate.ClientCore或GeneralUpdate.Core时自动引用。 +`GeneralTracer` 提供组件内部异常信息和执行流程的追踪输出。它默认启用，引用 `GeneralUpdate.Core` 时会自动包含。 ```c# public static class GeneralTracer diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.ClientCore.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.ClientCore.md deleted file mode 100644 index 9f914e4..0000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.ClientCore.md +++ /dev/null @@ -1,765 +0,0 @@ ---- -sidebar_position: 4 ---- - -# GeneralUpdate.ClientCore - -## 组件概览 - -**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一,提供了丰富的客户端更新功能。该组件运行在主应用程序中,负责检查更新、下载更新包、验证完整性,并在完成后启动升级助手(GeneralUpdate.Core)来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新,而不影响当前运行状态。 - -**命名空间:** `GeneralUpdate.ClientCore` -**程序集:** `GeneralUpdate.ClientCore.dll` - -```csharp -public class GeneralClientBootstrap : AbstractBootstrap -``` - ---- - -## 核心特性 - -### 1. 多版本下载管理 -- 支持同时下载多个版本的更新包 -- 断点续传和下载速度限制 -- 实时下载进度和统计信息 - -### 2. 灵活的配置选项 -- 黑名单机制(文件、格式、目录) -- 自定义更新策略和操作 -- 支持二进制差异更新和全量更新 -- `ConfiginfoBuilder` 零配置构建器,只需三个参数即可完成配置 - -### 3. 完整的事件通知 -- 下载进度、完成、错误事件 -- 更新版本信息通知（`AddListenerUpdateInfo`） -- 统一更新预检回调（`AddListenerUpdatePrecheck`） -- 异常和错误全程监控 - -### 4. 静默更新模式 -- 后台轮询检测新版本（默认每 20 分钟一次） -- 静默下载并准备更新包 -- 在主程序退出后自动启动升级流程 - -### 5. 多平台支持 -- Windows、Linux、macOS 平台支持 -- 自动平台检测和策略选择 - -![Multi Download](imgs/muti_donwload.png) - ---- - -## 快速开始 - -### 安装 - -通过 NuGet 安装 GeneralUpdate.ClientCore: - -```bash -dotnet add package GeneralUpdate.ClientCore -``` - -### 初始化与使用 - -以下示例展示了如何在主程序中配置和启动更新检查: - -```csharp -using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; -using GeneralUpdate.Common.Shared.Object; - -try -{ - Console.WriteLine($"主程序初始化,{DateTime.Now}!"); - - // 配置更新参数 - var configinfo = new Configinfo - { - // 更新验证 API 地址 - UpdateUrl = "http://127.0.0.1:5000/Upgrade/Verification", - // 更新报告 API 地址 - ReportUrl = "http://127.0.0.1:5000/Upgrade/Report", - // 主应用程序名称 - MainAppName = "ClientSample.exe", - // 升级程序名称 - AppName = "UpgradeSample.exe", - // 当前客户端版本 - ClientVersion = "1.0.0.0", - // 升级端版本 - UpgradeClientVersion = "1.0.0.0", - // 安装路径 - InstallPath = Thread.GetDomain().BaseDirectory, - // 产品 ID(用于多产品分支管理) - ProductId = "2d974e2a-31e6-4887-9bb1-b4689e98c77a", - // 应用密钥(用于服务器验证) - AppSecretKey = "dfeb5833-975e-4afb-88f1-6278ee9aeff6" - }; - - // 启动更新流程 - await new GeneralClientBootstrap() - // 监听下载统计信息 - .AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics) - // 监听单个下载完成 - .AddListenerMultiDownloadCompleted(OnMultiDownloadCompleted) - // 监听所有下载完成 - .AddListenerMultiAllDownloadCompleted(OnMultiAllDownloadCompleted) - // 监听下载错误 - .AddListenerMultiDownloadError(OnMultiDownloadError) - // 监听异常 - .AddListenerException(OnException) - // 设置配置 - .SetConfig(configinfo) - // 设置选项 - .Option(UpdateOption.DownloadTimeOut, 60) - .Option(UpdateOption.Encoding, Encoding.Default) - // 启动异步更新 - .LaunchAsync(); - - Console.WriteLine($"主程序已启动,{DateTime.Now}!"); -} -catch (Exception e) -{ - Console.WriteLine(e.Message + "\n" + e.StackTrace); -} - -// 事件处理方法 -void OnMultiDownloadStatistics(object arg1, MultiDownloadStatisticsEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine($"下载版本:{version.Version},速度:{arg2.Speed}," + - $"剩余时间:{arg2.Remaining},进度:{arg2.ProgressPercentage}%"); -} - -void OnMultiDownloadCompleted(object arg1, MultiDownloadCompletedEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine(arg2.IsComplated ? - $"版本 {version.Version} 下载完成!" : - $"版本 {version.Version} 下载失败!"); -} - -void OnMultiAllDownloadCompleted(object arg1, MultiAllDownloadCompletedEventArgs arg2) -{ - Console.WriteLine(arg2.IsAllDownloadCompleted ? - "所有下载任务已完成!" : - $"下载任务失败!失败数量:{arg2.FailedVersions.Count}"); -} - -void OnMultiDownloadError(object arg1, MultiDownloadErrorEventArgs arg2) -{ - var version = arg2.Version as VersionInfo; - Console.WriteLine($"版本 {version.Version} 下载错误:{arg2.Exception}"); -} - -void OnException(object arg1, ExceptionEventArgs arg2) -{ - Console.WriteLine($"更新异常:{arg2.Exception}"); -} -``` - ---- - -## 核心 API 参考 - -### GeneralClientBootstrap 类方法 - -#### LaunchAsync 方法 - -异步启动更新流程。 - -```csharp -public async Task LaunchAsync() -``` - -#### SetConfig 方法 - -设置更新配置信息。 - -```csharp -public GeneralClientBootstrap SetConfig(Configinfo configinfo) -``` - -#### Option 方法 - -设置更新选项。 - -```csharp -public GeneralClientBootstrap Option(UpdateOption option, object value) -``` - -#### SetBlacklist 方法 - -设置更新黑名单,指定不需要更新的文件。 - -```csharp -public GeneralClientBootstrap SetBlacklist(List blackFiles = null, - List blackFormats = null) -``` - -#### AddListenerMultiDownloadStatistics 方法 - -监听下载统计信息(速度、进度、剩余时间等)。 - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadStatistics( - Action callbackAction) -``` - -#### AddListenerMultiDownloadCompleted 方法 - -监听单个更新包下载完成事件。 - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiAllDownloadCompleted 方法 - -监听所有下载任务完成事件。 - -```csharp -public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiDownloadError 方法 - -监听下载错误事件。 - -```csharp -public GeneralClientBootstrap AddListenerMultiDownloadError( - Action callbackAction) -``` - -#### AddListenerException 方法 - -监听更新过程中的所有异常。 - -```csharp -public GeneralClientBootstrap AddListenerException( - Action callbackAction) -``` - -#### AddCustomOption 方法 - -添加自定义异步操作,可在更新前后执行自定义逻辑。 - -```csharp -public GeneralClientBootstrap AddCustomOption(Func customFunc) -``` - -#### AddListenerUpdateInfo 方法 - -注册更新版本信息回调。版本验证完成后立即触发,可用于展示更新日志或版本列表。 - -```csharp -public GeneralClientBootstrap AddListenerUpdateInfo( - Action callbackAction) -``` - -**UpdateInfoEventArgs 属性:** -- `Info`: `VersionRespDTO` — 服务端返回的版本响应数据,包含可用版本列表及每个版本的 `UpdateLog` 字段 - -**示例:** -```csharp -.AddListenerUpdateInfo((sender, e) => -{ - foreach (var v in e.Info.Body ?? []) - Console.WriteLine($"{v.Version}: {v.UpdateLog}"); -}) -``` - -#### AddListenerUpdatePrecheck 方法 - -注册更新预检回调,将更新信息通知和跳过更新决策合并为单一入口。回调接收完整的 `UpdateInfoEventArgs`（版本列表、强制更新标志等），返回 `true` 跳过更新，返回 `false` 继续更新。 - -> **注意：** 此方法替代了旧的 `AddListenerUpdateInfo` + `SetCustomSkipOption` 组合写法。`IsForcibly` 为强制更新时，回调返回值将被忽略，更新始终执行。 - -```csharp -public GeneralClientBootstrap AddListenerUpdatePrecheck( - Func precheckFunc) -``` - -**示例:** -```csharp -.AddListenerUpdatePrecheck(updateInfo => -{ - // 在此可访问完整版本信息 - bool userChoseSkip = ShowUpdateDialog(updateInfo.Info); - return userChoseSkip; // true = 跳过, false = 继续更新 -}) -``` - ---- - -## 配置类详解 - -### Configinfo 类 - -```csharp -public class Configinfo -{ - /// - /// 更新检查 API 地址 - /// - public string UpdateUrl { get; set; } - - /// - /// 更新状态报告 API 地址 - /// - public string ReportUrl { get; set; } - - /// - /// 需要启动的应用程序名称(升级程序) - /// - public string AppName { get; set; } - - /// - /// 需要启动的主应用程序名称 - /// - public string MainAppName { get; set; } - - /// - /// 更新日志网页地址 - /// - public string UpdateLogUrl { get; set; } - - /// - /// 应用密钥,与服务器约定用于身份验证和产品分支 - /// - public string AppSecretKey { get; set; } - - /// - /// 当前客户端版本号 - /// - public string ClientVersion { get; set; } - - /// - /// 当前升级客户端版本号 - /// - public string UpgradeClientVersion { get; set; } - - /// - /// 安装路径(用于更新文件逻辑) - /// - public string InstallPath { get; set; } - - /// - /// 黑名单文件列表,这些文件在更新时会被跳过 - /// - public List BlackFiles { get; set; } - - /// - /// 黑名单文件格式列表,这些格式的文件在更新时会被跳过 - /// - public List BlackFormats { get; set; } - - /// - /// 需要跳过的目录路径列表,这些目录不需要更新 - /// - public List SkipDirectorys { get; set; } - - /// - /// 当前产品分支的唯一 ID - /// - public string ProductId { get; set; } - - /// - /// Bowl 监控进程路径,更新完成后启动 Bowl 检查客户端是否正常启动 - /// - public string Bowl { get; set; } - - /// - /// HTTP 请求中用于传递 token 的 Scheme(如 Bearer) - /// - public string Scheme { get; set; } - - /// - /// HTTP 请求中用于身份验证的 Token - /// - public string Token { get; set; } - - /// - /// Linux 平台下的脚本,用于在更新完成后为文件分配权限 - /// - public string Script { get; set; } - - /// - /// 驱动程序目录路径,指定包含需要更新的驱动文件的目录 - /// - public string DriverDirectory { get; set; } -} -``` - -### UpdateOption 枚举 - -```csharp -public enum UpdateOption -{ - /// - /// 更新包文件格式(默认为 Zip) - /// - Format, - - /// - /// 压缩编码格式 - /// - Encoding, - - /// - /// 下载超时时间(秒)。如果不指定,默认超时时间为 30 秒 - /// - DownloadTimeOut, - - /// - /// 是否启用二进制差异更新功能,默认启用;设置为 false 则执行全量覆盖安装 - /// - Patch, - - /// - /// 是否在更新前启用备份功能,默认启用;设置为 false 则不进行备份 - /// - BackUp, - - /// - /// 是否启用静默更新模式。启用后将在后台轮询检测新版本、静默下载更新包, - /// 并在主程序退出后自动启动升级流程,不影响用户的正常使用。 - /// - EnableSilentUpdate -} -``` - ---- - -## ConfiginfoBuilder 构建器 - -`ConfiginfoBuilder` 是零配置模式的 `Configinfo` 构建器,灵感来自 [Velopack](https://github.com/velopack/velopack) 的设计。只需提供三个必填参数即可自动生成完整的平台适配配置。 - -**命名空间:** `GeneralUpdate.Common.Shared.Object` - -### 特性 - -- 仅需三个参数：`UpdateUrl`、`Token`、`Scheme` -- 自动从 `.csproj` 文件提取应用名称、版本号和发布者信息 -- 自动适配 Windows / Linux / macOS 平台差异（路径、权限脚本等） -- 安装路径默认使用宿主程序所在目录（`AppDomain.CurrentDomain.BaseDirectory`） - -### 快速使用 - -```csharp -using GeneralUpdate.Common.Shared.Object; - -// 零配置:从 .csproj 自动提取名称、版本、发布者 -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .Build(); - -await new GeneralClientBootstrap() - .SetConfig(config) - .LaunchAsync(); -``` - -### 自定义覆盖 - -```csharp -var config = ConfiginfoBuilder - .Create("https://api.example.com/updates", "your-token", "Bearer") - .SetAppName("CustomApp.exe") // 覆盖自动检测的名称 - .SetClientVersion("2.0.0") // 覆盖自动检测的版本 - .SetInstallPath("/custom/path") // 覆盖安装路径 - .Build(); -``` - -### 自动提取规则 - -| 配置项 | 提取来源 | csproj 字段 | 映射目标 | -|--------|----------|-------------|----------| -| 应用名称 | 项目文件 | `` 或文件名 | `AppName`、`MainAppName` | -| 版本号 | 项目文件 | `` | `ClientVersion`、`UpgradeClientVersion` | -| 发布者 | 项目文件 | `` 或 `` | `ProductId` | -| 安装路径 | 宿主程序运行时目录 | — | `InstallPath` | - -### 平台支持 - -| 平台 | 应用名称后缀 | 默认脚本 | -|------|------------|---------| -| Windows | `.exe` | 无 | -| Linux | 无后缀 | chmod 权限脚本 | -| macOS | 无后缀 | chmod 权限脚本 | - ---- - -## 实际使用示例 - -### 示例 1:基本更新流程 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ReportUrl = "http://your-server.com/api/update/report", - MainAppName = "MyApp.exe", - AppName = "Updater.exe", - ClientVersion = "1.0.0.0", - UpgradeClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory, - ProductId = "your-product-id", - AppSecretKey = "your-secret-key" -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - .AddListenerException((sender, args) => - { - Console.WriteLine($"更新异常: {args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### 示例 2:带黑名单的更新 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory, - // 黑名单配置 - BlackFiles = new List { "config.json", "userdata.db" }, - BlackFormats = new List { ".log", ".cache" }, - SkipDirectorys = new List { "logs", "temp" } -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - .LaunchAsync(); -``` - -### 示例 3:自定义更新选项 - -```csharp -using System.Text; -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // 设置下载超时 - .Option(UpdateOption.DownloadTimeOut, 120) - // 设置编码格式 - .Option(UpdateOption.Encoding, Encoding.UTF8) - // 启用二进制差异更新 - .Option(UpdateOption.Patch, true) - // 启用备份 - .Option(UpdateOption.BackUp, true) - .LaunchAsync(); -``` - -### 示例 4:完整的事件监听 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // 下载统计 - .AddListenerMultiDownloadStatistics((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"[{version.Version}] 进度: {args.ProgressPercentage}% | " + - $"速度: {args.Speed} | 剩余: {args.Remaining}"); - }) - // 单个下载完成 - .AddListenerMultiDownloadCompleted((sender, args) => - { - var version = args.Version as VersionInfo; - if (args.IsComplated) - Console.WriteLine($"✓ 版本 {version.Version} 下载成功"); - else - Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); - }) - // 所有下载完成 - .AddListenerMultiAllDownloadCompleted((sender, args) => - { - if (args.IsAllDownloadCompleted) - Console.WriteLine("✓ 所有更新包下载完成,准备安装..."); - else - Console.WriteLine($"✗ 下载失败,共 {args.FailedVersions.Count} 个版本失败"); - }) - // 下载错误 - .AddListenerMultiDownloadError((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); - }) - // 异常处理 - .AddListenerException((sender, args) => - { - Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); - }) - .LaunchAsync(); -``` - -### 示例 5：更新预检与跳过（AddListenerUpdatePrecheck） - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -await new GeneralClientBootstrap() - .SetConfig(config) - // 统一的更新预检回调：可获取版本信息并决定是否跳过 - .AddListenerUpdatePrecheck(updateInfo => - { - Console.WriteLine($"发现 {updateInfo.Info.Body?.Count ?? 0} 个新版本"); - Console.WriteLine("是否现在更新？(y/n)"); - var input = Console.ReadLine(); - return input?.ToLower() != "y"; // true = 跳过, false = 继续更新 - }) - .AddListenerException((sender, args) => - { - Console.WriteLine($"更新异常：{args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### 示例 6：静默更新模式（EnableSilentUpdate） - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Internal.Bootstrap; - -var config = new Configinfo -{ - UpdateUrl = "http://your-server.com/api/update/check", - ClientVersion = "1.0.0.0", - InstallPath = AppDomain.CurrentDomain.BaseDirectory -}; - -// 启用静默更新：后台每 20 分钟轮询，主程序退出后自动启动升级 -await new GeneralClientBootstrap() - .SetConfig(config) - .Option(UpdateOption.EnableSilentUpdate, true) - .AddListenerException((sender, args) => - { - Console.WriteLine($"静默更新异常：{args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### 示例 7：使用 ConfiginfoBuilder 零配置构建 - -```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; - -// 从 .csproj 自动提取应用名称、版本和发布者 -var config = ConfiginfoBuilder - .Create("http://your-server.com/api/update/check", "your-token", "Bearer") - .Build(); - -await new GeneralClientBootstrap() - .SetConfig(config) - .AddListenerException((sender, args) => - { - Console.WriteLine($"更新异常：{args.Exception.Message}"); - }) - .LaunchAsync(); -``` - ---- - -## 注意事项与警告 - -### ⚠️ 重要提示 - -1. **版本号格式** - - 版本号必须遵循语义化版本规范(如 1.0.0.0) - - 确保客户端和服务器端版本号格式一致 - -2. **网络连接** - - 确保更新服务器地址可访问 - - 建议实现重试机制处理网络波动 - -3. **进程管理** - - 更新过程会关闭主程序并启动升级助手 - - 确保保存所有用户数据后再执行更新 - -4. **权限要求** - - 在 Windows 上可能需要管理员权限来替换文件 - - 在 Linux/macOS 上需要适当的文件系统权限 - -5. **黑名单使用** - - 黑名单中的文件和目录不会被更新 - - 常用于保护配置文件、用户数据等 - -6. **更新预检回调** - - `AddListenerUpdatePrecheck` 已替代旧的 `SetCustomSkipOption` + `AddListenerUpdateInfo` 组合 - - 强制更新（`IsForcibly = true`）时，回调返回值被忽略，更新始终执行 - -7. **静默更新** - - `EnableSilentUpdate` 不改变默认更新行为，需显式启用 - - 静默模式下，升级助手将在主程序退出事件触发后才启动 - -### 💡 最佳实践 - -- **零配置构建**：优先使用 `ConfiginfoBuilder.Create()` 减少手动配置错误 -- **备份策略**:始终启用 BackUp 选项,以便更新失败时可以回滚 -- **差异更新**:启用 Patch 选项以减少下载量和更新时间 -- **错误处理**:实现完整的异常监听和错误处理逻辑 -- **用户体验**:使用 `AddListenerUpdatePrecheck` 在更新前提示用户并允许选择更新时机 -- **测试验证**:在生产环境部署前充分测试更新流程 - ---- - -## 适用平台 - -| 产品 | 版本 | -| ------------------ | -------------------- | -| .NET | 5, 6, 7, 8, 9, 10 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - ---- - -## 相关资源 - -- **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) -- **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md index 563acfb..4b717e3 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Core.md @@ -6,7 +6,11 @@ sidebar_position: 5 ## 组件概览 -**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一,提供了完整的升级执行能力。与 ClientCore 不同,Core 组件作为独立的升级助手程序运行,负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式,Core 接收来自 ClientCore 的更新指令,并安全地完成主程序的升级任务。 +**GeneralUpdate.Core** 是 GeneralUpdate 框架的统一核心组件。自最新版本起，原先独立的 `GeneralUpdate.ClientCore`（客户端更新管理）和 `GeneralUpdate.Common`（公共基础代码）已合并到 `GeneralUpdate.Core` 中。现在只需引用一个 `GeneralUpdate.Core` 包即可同时获得： + +- **客户端更新管理**（原 ClientCore）：版本检查、更新包下载、完整性验证、拉起升级程序 +- **升级执行引擎**（原 Core）：独立进程升级、文件替换、差分包应用、驱动安装 +- **公共基础设施**（原 Common）：生命周期追踪、下载引擎、序列化等底层能力 **命名空间:** `GeneralUpdate.Core` **程序集:** `GeneralUpdate.Core.dll` @@ -57,9 +61,6 @@ dotnet add package GeneralUpdate.Core 以下示例展示了如何在升级助手程序中配置和启动升级流程: ```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; using GeneralUpdate.Core; try @@ -222,7 +223,7 @@ public enum UpdateOption ### Packet 类 -升级包信息类,由 ClientCore 通过参数传递给 Core: +升级包信息类，由客户端（原 ClientCore，现已合并到 Core）通过参数传递给升级程序： ```csharp public class Packet @@ -351,9 +352,6 @@ public class Packet ### 示例 1:基本升级流程 ```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; using GeneralUpdate.Core; try @@ -383,13 +381,12 @@ catch (Exception e) ### 示例 2：启用驱动升级 -驱动升级通过 `GeneralUpdate.ClientCore` 中的 `Configinfo.DriverDirectory` 字段传入驱动目录，`GeneralUpdate.Core` 中的 `DrivelutionMiddleware` 会自动处理驱动安装。 +驱动升级通过 `Configinfo.DriverDirectory` 字段传入驱动目录（`Configinfo` 现在位于 `GeneralUpdate.Core` 中），`DrivelutionMiddleware` 会自动处理驱动安装。 -在 `ClientCore` 侧配置： +在客户端侧配置： ```csharp -using GeneralUpdate.ClientCore; -using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; var config = new Configinfo { @@ -427,8 +424,6 @@ await new GeneralUpdateBootstrap() ```csharp using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; await new GeneralUpdateBootstrap() // 下载统计 @@ -485,8 +480,6 @@ await new GeneralUpdateBootstrap() ```csharp using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; // 记录升级开始时间 var startTime = DateTime.Now; @@ -531,7 +524,7 @@ await new GeneralUpdateBootstrap() - 升级时主程序必须完全关闭,否则文件替换会失败 2. **参数传递** - - ClientCore 通过 Base64 编码的参数传递配置给 Core + - 客户端通过 Base64 编码的参数传递配置给 Core（原 ClientCore 现已合并到 Core） - 确保参数传递过程中不会被截断或损坏 3. **文件权限** @@ -544,7 +537,7 @@ await new GeneralUpdateBootstrap() 5. **回滚机制** - Core 不直接提供回滚功能,但保留了备份文件 - - 如需回滚,可使用 ClientCore 的备份功能 + - Core 提供内置的备份与回滚机制，无需额外组件 ### 💡 最佳实践 @@ -571,4 +564,5 @@ await new GeneralUpdateBootstrap() - **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) - **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) -- **相关组件**:[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) +- **相关组件**:[GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) | [GeneralUpdate.Drivelution](./GeneralUpdate.Drivelution.md) +- **迁移说明**：`GeneralUpdate.ClientCore` 和 `GeneralUpdate.Common` 已合并到 `GeneralUpdate.Core`。迁移时只需将 `using GeneralUpdate.ClientCore` / `using GeneralUpdate.Common.*` 替换为 `using GeneralUpdate.Core`，并移除旧的 NuGet 包引用。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md index 18c1262..71cd3b0 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Differential.md @@ -402,7 +402,7 @@ await manager.GeneratePatchWithProgressAsync( 5. **备份建议** - 在应用补丁前建议备份原始文件 - - 可以使用 ClientCore 的 BackUp 选项自动备份 + - 可以使用 Core 的 BackUp 选项自动备份 ### 💡 最佳实践 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md index ad1e7ee..e5f6cd8 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Extension.md @@ -872,7 +872,7 @@ if (!Directory.Exists(backupDir)) ### 另请参阅 -- [GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) - 主客户端更新组件 +- [GeneralUpdate.Core](./GeneralUpdate.Core.md) - 主客户端更新组件 - [GeneralUpdate.Core](./GeneralUpdate.Core.md) - 核心更新逻辑 - [GitHub 源代码](https://github.com/GeneralLibrary/GeneralUpdate/tree/master/src/c%23/GeneralUpdate.Extension) - 完整源代码和更多示例 - [快速入门指南](../quickstart/Quik%20start.md) - GeneralUpdate 入门 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md index 7a78d16..44d6f3a 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/UpgradeHub.md @@ -4,9 +4,9 @@ sidebar_position: 7 ### 定义 -命名空间：GeneralUpdate.ClientCore.Hubs +命名空间：GeneralUpdate.Core.Hubs -程序集：GeneralUpdate.ClientCore.dll +程序集：GeneralUpdate.Core.dll