From e457ad766fdac2f95418bf12869abf2006e4d5b9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:13:19 +0000 Subject: [PATCH 1/7] Initial plan From 4009fa5720ff0cbce05ca9292b0c51b284fb6144 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:21:44 +0000 Subject: [PATCH 2/7] Enhanced documentation for all four core components with bilingual content Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com> --- website/docs/doc/GeneralUpdate.Bowl.md | 423 ++++++---- website/docs/doc/GeneralUpdate.ClientCore.md | 765 +++++++++++++++--- website/docs/doc/GeneralUpdate.Core.md | 639 ++++++++++++++- .../docs/doc/GeneralUpdate.Differential.md | 494 +++++++++-- 4 files changed, 1960 insertions(+), 361 deletions(-) diff --git a/website/docs/doc/GeneralUpdate.Bowl.md b/website/docs/doc/GeneralUpdate.Bowl.md index 6cfe08b..5af0825 100644 --- a/website/docs/doc/GeneralUpdate.Bowl.md +++ b/website/docs/doc/GeneralUpdate.Bowl.md @@ -2,59 +2,237 @@ sidebar_position: 3 --- -### Definition +# GeneralUpdate.Bowl -Namespace: GeneralUpdate.Bowl +## 组件概览 | Component Overview -Assembly: GeneralUpdate.Bowl.dll +**GeneralUpdate.Bowl** 是一个独立的进程监控组件，在升级流程结束前启动，负责启动主客户端应用程序并监控其运行状态。该组件提供了完整的崩溃监控和诊断能力，当被监控的应用程序发生异常时，会自动导出Dump文件、驱动信息、系统信息和事件日志，帮助开发者快速定位问题。 -This component is an independent process launched before the end of the upgrade process. It starts the main client application and monitors its normal operation before the process ends. +**GeneralUpdate.Bowl** is an independent process monitoring component that launches before the end of the upgrade process. It is responsible for starting the main client application and monitoring its running status. This component provides comprehensive crash monitoring and diagnostic capabilities. When the monitored application encounters an exception, it automatically exports Dump files, driver information, system information, and event logs to help developers quickly locate issues. -```c# +**命名空间 | Namespace:** `GeneralUpdate.Bowl` +**程序集 | Assembly:** `GeneralUpdate.Bowl.dll` + +```csharp public sealed class Bowl ``` +--- + +## 核心特性 | Core Features + +### 1. 进程监控 | Process Monitoring +- 实时监控目标应用程序的运行状态 | Real-time monitoring of target application status +- 自动检测进程崩溃和异常退出 | Automatic detection of process crashes and abnormal exits + +### 2. 崩溃诊断 | Crash Diagnostics +- 自动生成Dump文件（.dmp）用于崩溃分析 | Automatic generation of Dump files (.dmp) for crash analysis +- 导出详细的系统和驱动信息 | Export detailed system and driver information +- 收集Windows系统事件日志 | Collect Windows system event logs + +### 3. 版本化管理 | Version Management +- 按版本号分类存储故障信息 | Store failure information categorized by version number +- 支持升级和正常两种工作模式 | Support both upgrade and normal working modes + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Bowl： + +Install GeneralUpdate.Bowl via NuGet: + +```bash +dotnet add package GeneralUpdate.Bowl +``` + +### 初始化与使用 | Initialization and Usage +以下示例展示了如何使用 Bowl 组件监控应用程序： -### Example +The following example demonstrates how to use the Bowl component to monitor an application: -The following example defines a method that includes the use of Bowl. +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; -```c# var installPath = AppDomain.CurrentDomain.BaseDirectory; var lastVersion = "1.0.0.3"; var processInfo = new MonitorParameter { - ProcessNameOrId = "JsonTest.exe", + ProcessNameOrId = "YourApp.exe", DumpFileName = $"{lastVersion}_fail.dmp", FailFileName = $"{lastVersion}_fail.json", TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", lastVersion), BackupDirectory = Path.Combine(installPath, lastVersion), - WorkModel = "Normal" + WorkModel = "Normal" // 使用 Normal 模式独立监控 | Use Normal mode for standalone monitoring }; Bowl.Launch(processInfo); ``` -### Capture +--- + +## 核心 API 参考 | Core API Reference + +### Launch 方法 | Launch Method + +启动进程监控功能。 + +Start the process monitoring functionality. + +**方法签名 | Method Signature:** + +```csharp +public static void Launch(MonitorParameter? monitorParameter = null) +``` + +**参数 | Parameters:** + +#### MonitorParameter 类 | MonitorParameter Class + +```csharp +public class MonitorParameter +{ + /// + /// 被监控的目录 + /// Directory being monitored + /// + public string TargetPath { get; set; } + + /// + /// 导出异常信息的目录 + /// Directory where captured exception information is exported + /// + public string FailDirectory { get; set; } + + /// + /// 备份目录 + /// Backup directory + /// + public string BackupDirectory { get; set; } + + /// + /// 被监控进程的名称或ID + /// Name or ID of the process being monitored + /// + public string ProcessNameOrId { get; set; } + + /// + /// Dump 文件名 + /// Dump file name + /// + public string DumpFileName { get; set; } + + /// + /// 升级包版本信息（.json）文件名 + /// Upgrade package version information (.json) file name + /// + public string FailFileName { get; set; } + + /// + /// 工作模式： + /// - Upgrade: 升级模式，主要用于与 GeneralUpdate 配合使用，内部逻辑处理，默认模式启动时请勿随意修改 + /// - Normal: 正常模式，可独立使用监控单个程序，程序崩溃时导出崩溃信息 + /// + /// Work Mode: + /// - Upgrade: Upgrade mode, primarily used in conjunction with GeneralUpdate for internal logic handling. + /// Do not modify arbitrarily when the default mode is activated. + /// - Normal: Normal mode, can be used independently to monitor a single program. + /// Exports crash information when the program crashes. + /// + public string WorkModel { get; set; } = "Upgrade"; +} +``` + +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：独立模式监控应用 | Example 1: Standalone Mode Application Monitoring + +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; + +// 配置监控参数 | Configure monitoring parameters +var installPath = AppDomain.CurrentDomain.BaseDirectory; +var currentVersion = "1.0.0.5"; + +var monitorConfig = new MonitorParameter +{ + ProcessNameOrId = "MyApplication.exe", + DumpFileName = $"{currentVersion}_crash.dmp", + FailFileName = $"{currentVersion}_crash.json", + TargetPath = installPath, + FailDirectory = Path.Combine(installPath, "crash_reports", currentVersion), + BackupDirectory = Path.Combine(installPath, "backups", currentVersion), + WorkModel = "Normal" // 独立监控模式 | Standalone monitoring mode +}; + +// 启动监控 | Start monitoring +Bowl.Launch(monitorConfig); +``` + +### 示例 2：结合 GeneralUpdate 使用 | Example 2: Use with GeneralUpdate -If a crash is detected, the following files will be generated in the running directory: +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; -- 📒 Dump file (1.0.0.*_fail.dmp) -- 📒 Upgrade package version information (1.0.0.*_fail.json) -- 📒 Driver information (driverInfo.txt) -- 📒 Operating system/hardware information (systeminfo.txt) -- 📒 System event log (systemlog.evtx) +// 在升级完成后启动 Bowl 监控 | Start Bowl monitoring after upgrade completion +var installPath = AppDomain.CurrentDomain.BaseDirectory; +var upgradedVersion = "2.0.0.1"; -These will be exported to the "fail" directory, categorized by version number. +var upgradeMonitor = new MonitorParameter +{ + ProcessNameOrId = "UpdatedApp.exe", + DumpFileName = $"{upgradedVersion}_fail.dmp", + FailFileName = $"{upgradedVersion}_fail.json", + TargetPath = installPath, + FailDirectory = Path.Combine(installPath, "fail", upgradedVersion), + BackupDirectory = Path.Combine(installPath, upgradedVersion), + WorkModel = "Upgrade" // 升级模式 | Upgrade mode +}; -![](imgs\crash.jpg) +Bowl.Launch(upgradeMonitor); +``` -#### (1) x.0.0.*_fail.dmp +--- -![](imgs\dump.png) +## 崩溃信息捕获 | Crash Information Capture -#### (2) x.0.0.*_fail.json +当检测到崩溃时，以下文件将在运行目录中生成： + +When a crash is detected, the following files will be generated in the running directory: + +- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) | **Dump file** (`x.0.0.*_fail.dmp`) +- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) | **Upgrade package version information** (`x.0.0.*_fail.json`) +- 📒 **驱动信息** (`driverInfo.txt`) | **Driver information** (`driverInfo.txt`) +- 📒 **操作系统/硬件信息** (`systeminfo.txt`) | **Operating system/hardware information** (`systeminfo.txt`) +- 📒 **系统事件日志** (`systemlog.evtx`) | **System event log** (`systemlog.evtx`) + +这些文件将按版本号分类导出到 "fail" 目录中。 + +These files will be exported to the "fail" directory, categorized by version number. + +![Crash Files](imgs/crash.jpg) + +### 1. Dump 文件 | Dump File + +Dump 文件包含崩溃时刻的内存快照，可用于调试分析： + +The Dump file contains a memory snapshot at the moment of crash, which can be used for debugging analysis: + +![Dump File](imgs/dump.png) + +### 2. 版本信息文件 | Version Information File + +JSON 格式的详细崩溃报告，包含参数配置和 ProcDump 输出： + +Detailed crash report in JSON format, including parameter configuration and ProcDump output: ```json { @@ -96,147 +274,100 @@ These will be exported to the "fail" directory, categorized by version number. } ``` -#### (3) driverInfo.txt +### 3. 驱动信息文件 | Driver Information File -```json -Module Name Display Name Description Driver Type Start Mode State Status Accept Stop Accept Pause Paged Pool Code(Bytes) BSS(Bytes) Link Date Path Init(Bytes) -============ ====================== ====================== ============= ========== ========== ========== =========== ============ ========== ========== ======= ====================== ================================================ ========== -360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK TRUE FALSE 4,096 36,864 0 9/29/2022 3:45:03 PM C:\Windows\system32\Drivers\360AntiAttack64.sys 4,096 -360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK TRUE FALSE 4,096 139,264 0 11/27/2023 3:43:37 PM C:\Windows\system32\Drivers\360AntiHacker64.sys 8,192 -360AntiHijac 360Safe Anti Hijack Se 360Safe Anti Hijack Se Kernel System Running OK TRUE FALSE 4,096 73,728 0 5/8/2024 12:19:52 PM C:\Windows\system32\Drivers\360AntiHijack64.sys 4,096 -360AntiSteal 360Safe Anti Steal Fil 360Safe Anti Steal Fil Kernel System Running OK TRUE FALSE 4,096 20,480 0 4/18/2024 3:58:04 PM C:\Windows\system32\Drivers\360AntiSteal64.sys 8,192 -360Box64 360Box mini-filter dri 360Box mini-filter dri File System System Running OK TRUE FALSE 0 225,280 0 8/7/2024 11:50:19 AM C:\Windows\system32\DRIVERS\360Box64.sys 12,288 - -//... +包含系统中所有驱动程序的详细信息： + +Contains detailed information about all drivers in the system: + +```text +Module Name Display Name Description Driver Type Start Mode State Status +============ ====================== ====================== ============= ========== ========== ========== +360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK +360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK +// ...更多驱动信息 | ...more driver information ``` -#### (4) systeminfo.txt +### 4. 系统信息文件 | System Information File -```json +完整的操作系统和硬件配置信息： + +Complete operating system and hardware configuration information: + +```text Host Name: **** -OS Name: Microsoft Windows 11 Pro -OS Version: 10.0.2*** Build 22*** -OS Manufacturer: Microsoft Corporation -OS Configuration: Standalone Workstation -OS Build Type: Multiprocessor Free -Registered Owner: ****@outlook.com -Registered Organization: -Product ID: ****-80000-***00-A**** -Original Install Date: 11/16/2023, 9:56:28 PM -System Boot Time: 11/26/2024, 9:37:51 PM -System Manufacturer: ASUS -System Model: System Product Name -System Type: x64-based PC -Processor(s): Installed 1 Processor(s). - [01]: Intel** Family * Model *** Stepping * GenuineIntel ~**** Mhz -BIOS Version: American Megatrends Inc. 1402, 4/1/2022 -Windows Directory: C:\Windows -System Directory: C:\Windows\system32 -Boot Device: \Device\Ha*****olume1 -System Locale: zh-cn;Chinese (China) -Input Locale: zh-cn;Chinese (China) -Time Zone: (UTC+08:00) **，**，*******，**** -Total Physical Memory: 16,194 MB -Available Physical Memory: 1,795 MB -Virtual Memory: Max Size: 25,410 MB -Virtual Memory: Available: 9,438 MB -Virtual Memory: In Use: 15,972 MB -Page File Location(s): D:\****file.sys -Domain: WORKGROUP -Logon Server: \\**** -Hotfix(s):: 6 Hotfix(s) Installed. - [01]: KB504**** - [02]: KB502**** - [03]: KB503**** - [04]: KB503**** - [05]: KB504**** - [06]: KB504**** -Network Card(s): 3 NIC(s) Installed. - [01]: Intel(R) Ethernet Connection (**) I***-V - Connection Name: Ethernet - DHCP Enabled: Yes - DHCP Server: 192.168.**.** - IP Address - [01]: 192.168.**.** - [02]: ***::2640:***:****:**** - [02]: VMware Virtual Ethernet Adapter for VMnet1 - Connection Name: VMware Network Adapter VMnet1 - DHCP Enabled: Yes - DHCP Server: 192.168.**.** - IP Address - [01]: 192.168.**.** - [02]: ***::9b3:***,***:**** - [03]: VMware Virtual Ethernet Adapter for VMnet8 - Connection Name: VMware Network Adapter VMnet8 - DHCP Enabled: Yes - DHCP Server: 192.168.**.** - IP Address - [01]: 192.***,***:**** - [02]: fe80::***:***:***:**** -Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed. - -//... +OS Name: Microsoft Windows 11 Pro +OS Version: 10.0.*** Build 22*** +System Manufacturer: ASUS +System Model: System Product Name +Processor(s): Intel** Family * Model *** +Total Physical Memory: 16,194 MB +// ...更多系统信息 | ...more system information ``` -#### (5) systemlog.evtx +### 5. 系统事件日志 | System Event Log -![](imgs\evtx.png) +Windows 事件查看器格式的系统日志（.evtx 文件）： -### Notes +System log in Windows Event Viewer format (.evtx file): -Bowl provides runtime monitoring capabilities and exports relevant error information. +![System Event Log](imgs/evtx.png) -#### Methods +--- -| Method | Description | -| -------- | ---------------- | -| Launch() | Start monitoring | +## 注意事项与警告 | Notes and Warnings -### 🌼Launch() +### ⚠️ 重要提示 | Important Notes -**Launch Function** +1. **工作模式选择 | Work Mode Selection** + - `Upgrade` 模式：专门用于与 GeneralUpdate 框架集成，包含内部逻辑处理 + - `Normal` 模式：可独立使用，适合监控任何 .NET 应用程序 + - `Upgrade` mode: Specifically for integration with GeneralUpdate framework, includes internal logic processing + - `Normal` mode: Can be used independently, suitable for monitoring any .NET application -```c# -Launch(MonitorParameter? monitorParameter = null); -``` +2. **权限要求 | Permission Requirements** + - Bowl 需要足够的权限来生成 Dump 文件和读取系统信息 + - 建议以管理员权限运行需要监控的应用程序 + - Bowl requires sufficient permissions to generate Dump files and read system information + - It is recommended to run the monitored application with administrator privileges -**Parameters** +3. **磁盘空间 | Disk Space** + - Dump 文件可能占用大量磁盘空间（通常 50-200 MB） + - 确保 FailDirectory 所在磁盘有足够的可用空间 + - Dump files may consume significant disk space (typically 50-200 MB) + - Ensure sufficient available space on the disk where FailDirectory is located -```c# -public class MonitorParameter -{ - // Directory being monitored - public string TargetPath { get; set; } - - // Directory where captured exception information is exported - public string FailDirectory { get; set; } - - // Backup directory - public string BackupDirectory { get; set; } - - // Name or ID of the process being monitored - public string ProcessNameOrId { get; set; } - - // Dump file name - public string DumpFileName { get; set; } - - // Upgrade package version information (.json) file name - public string FailFileName { get; set; } +4. **依赖项 | Dependencies** + - Bowl 使用 ProcDump 工具生成 Dump 文件，该工具已内置在组件中 + - 无需额外安装依赖项 + - Bowl uses the ProcDump tool to generate Dump files, which is built into the component + - No additional dependencies need to be installed - /// - /// Upgrade: upgrade mode. This mode is primarily used in conjunction with GeneralUpdate for internal use. Please do not modify it arbitrarily when the default mode is activated. - /// Normal: Normal mode, This mode can be used independently to monitor a single program. If the program crashes, it will export the crash information. - /// - public string WorkModel { get; set; } = "Upgrade"; -} -``` +### 💡 最佳实践 | Best Practices + +- **版本号管理**：为每个版本使用独立的故障目录，便于问题追踪 +- **日志清理**：定期清理旧版本的故障信息，避免磁盘空间耗尽 +- **测试验证**：在生产环境部署前，在测试环境验证监控功能 +- **Version Management**: Use separate failure directories for each version for easier issue tracking +- **Log Cleanup**: Regularly clean up failure information from old versions to avoid disk space exhaustion +- **Testing**: Verify monitoring functionality in a test environment before production deployment + +--- + +## 适用平台 | Applicable Platforms + +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +| ASP.NET | Any | + +--- -### Applicable To +## 相关资源 | Related Resources -| Product | Version | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | -| ASP.NET | Any | \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) +- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) | [Watch Bilibili Tutorial](https://www.bilibili.com/video/BV1c8iyYZE7P) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) \ No newline at end of file diff --git a/website/docs/doc/GeneralUpdate.ClientCore.md b/website/docs/doc/GeneralUpdate.ClientCore.md index 5a9a29f..005337f 100644 --- a/website/docs/doc/GeneralUpdate.ClientCore.md +++ b/website/docs/doc/GeneralUpdate.ClientCore.md @@ -2,129 +2,670 @@ sidebar_position: 4 --- -### Definition +# GeneralUpdate.ClientCore -Namespace: GeneralUpdate.ClientCore +## 组件概览 | Component Overview -Assembly: GeneralUpdate.ClientCore.dll +**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一，提供了丰富的客户端更新功能。该组件运行在主应用程序中，负责检查更新、下载更新包、验证完整性，并在完成后启动升级助手（GeneralUpdate.Core）来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新，而不影响当前运行状态。 +**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` -GeneralUpdate.ClientCore is one of the core components, offering a wide range of primary functionalities. Its essence is similar to Core, but it has a different role: ClientCore is used in the main program, where it assists in updates and upgrades and then closes the main program to launch the upgrade assistant. - -```c# +```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 + +### 3. 完整的事件通知 | Comprehensive Event Notifications +- 下载进度、完成、错误事件 | Download progress, completion, and error events +- 支持用户自定义跳过更新选项 | Support user-defined skip update options +- 异常和错误全程监控 | Exception and error monitoring throughout the process + +### 4. 多平台支持 | Multi-Platform Support +- Windows、Linux、macOS 平台支持 | Windows, Linux, macOS platform support +- 自动平台检测和策略选择 | Automatic platform detection and strategy selection + +![Multi Download](imgs/muti_donwload.png) + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.ClientCore： + +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($"主程序初始化，{DateTime.Now}！"); + + // 配置更新参数 | Configure update parameters + var configinfo = new Configinfo + { + // 更新验证 API 地址 | Update verification API address + UpdateUrl = "http://127.0.0.1:5000/Upgrade/Verification", + // 更新报告 API 地址 | 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, + // 产品 ID（用于多产品分支管理）| 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($"主程序已启动，{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($"下载版本：{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 参考 | Core API Reference + +### GeneralClientBootstrap 类方法 | GeneralClientBootstrap Class Methods + +#### LaunchAsync 方法 | LaunchAsync Method + +异步启动更新流程。 + +Launch the update process asynchronously. + +```csharp +public async Task LaunchAsync() +``` + +#### SetConfig 方法 | SetConfig Method + +设置更新配置信息。 + +Set update configuration information. + +```csharp +public GeneralClientBootstrap SetConfig(Configinfo configinfo) +``` + +#### Option 方法 | Option Method + +设置更新选项。 + +Set update options. + +```csharp +public GeneralClientBootstrap Option(UpdateOption option, object value) +``` + +#### SetBlacklist 方法 | SetBlacklist Method + +设置更新黑名单，指定不需要更新的文件。 + +Set update blacklist to specify files that should not be updated. + +```csharp +public GeneralClientBootstrap SetBlacklist(List blackFiles = null, + List blackFormats = null) +``` + +#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method + +监听下载统计信息（速度、进度、剩余时间等）。 + +Listen for download statistics (speed, progress, remaining time, etc.). + +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadStatistics( + Action callbackAction) +``` + +#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method + +监听单个更新包下载完成事件。 + +Listen for single update package download completion event. + +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method + +监听所有下载任务完成事件。 + +Listen for all download tasks completion event. + +```csharp +public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method + +监听下载错误事件。 + +Listen for download error events. + +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadError( + Action callbackAction) +``` + +#### AddListenerException 方法 | AddListenerException Method + +监听更新过程中的所有异常。 + +Listen for all exceptions during the update process. + +```csharp +public GeneralClientBootstrap AddListenerException( + Action callbackAction) +``` + +#### AddCustomOption 方法 | AddCustomOption Method + +添加自定义异步操作，可在更新前后执行自定义逻辑。 + +Add custom asynchronous operations that can execute custom logic before or after updates. + +```csharp +public GeneralClientBootstrap AddCustomOption(Func customFunc) +``` + +#### SetCustomSkipOption 方法 | SetCustomSkipOption Method + +设置自定义跳过选项，允许用户决定是否继续更新。 + +Set custom skip options, allowing users to decide whether to continue with the update. + +```csharp +public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) +``` + +--- +## 配置类详解 | Configuration Class Details + +### Configinfo 类 | Configinfo Class + +```csharp +public class Configinfo +{ + /// + /// 更新检查 API 地址 + /// Update check API address + /// + public string UpdateUrl { get; set; } + + /// + /// 更新状态报告 API 地址 + /// 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; } + + /// + /// 当前产品分支的唯一 ID + /// Unique ID of the current product branch + /// + public string ProductId { get; set; } + + /// + /// Bowl 监控进程路径，更新完成后启动 Bowl 检查客户端是否正常启动 + /// Bowl monitoring process path, starts after updates to check if the client starts normally + /// + public string Bowl { get; set; } + + /// + /// HTTP 请求中用于传递 token 的 Scheme（如 Bearer） + /// Scheme used for passing token in HTTP requests (e.g., Bearer) + /// + public string Scheme { get; set; } + + /// + /// HTTP 请求中用于身份验证的 Token + /// Token used for authentication in HTTP requests + /// + public string Token { get; set; } + + /// + /// Linux 平台下的脚本，用于在更新完成后为文件分配权限 + /// Script for Linux platform to assign permissions to files after update completion + /// + public string Script { get; set; } +} +``` -### Example +### UpdateOption 枚举 | UpdateOption Enum + +```csharp +public enum UpdateOption +{ + /// + /// 更新包文件格式（默认为 Zip） + /// Update package file format (default is Zip) + /// + Format, + + /// + /// 压缩编码格式 + /// Compression encoding format + /// + Encoding, + + /// + /// 下载超时时间（秒）。如果不指定，默认超时时间为 30 秒 + /// Download timeout duration (seconds). Default is 30 seconds if not specified + /// + DownloadTimeOut, + + /// + /// 是否启用二进制差异更新功能，默认启用；设置为 false 则执行全量覆盖安装 + /// Whether to enable binary differential update function, enabled by default; + /// if set to false, full overwrite installation will be performed + /// + Patch, + + /// + /// 是否在更新前启用备份功能，默认启用；设置为 false 则不进行备份 + /// Whether to enable backup function before update, enabled by default; + /// if set to false, no backup will be performed + /// + BackUp +} +``` -GeneralClientBootstrap uses code examples [[View]](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs)。 +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：基本更新流程 | 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($"更新异常: {args.Exception.Message}"); + }) + .LaunchAsync(); +``` + +### 示例 2：带黑名单的更新 | 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(); +``` + +### 示例 3：自定义更新选项 | 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(); +``` -![](imgs/muti_donwload.png) +### 示例 4：完整的事件监听 | 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}] 进度: {args.ProgressPercentage}% | " + + $"速度: {args.Speed} | 剩余: {args.Remaining}"); + }) + // 单个下载完成 | Single download completed + .AddListenerMultiDownloadCompleted((sender, args) => + { + var version = args.Version as VersionInfo; + if (args.IsComplated) + Console.WriteLine($"✓ 版本 {version.Version} 下载成功"); + else + Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); + }) + // 所有下载完成 | All downloads completed + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + Console.WriteLine("✓ 所有更新包下载完成，准备安装..."); + else + Console.WriteLine($"✗ 下载失败，共 {args.FailedVersions.Count} 个版本失败"); + }) + // 下载错误 | Download error + .AddListenerMultiDownloadError((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); + }) + // 异常处理 | Exception handling + .AddListenerException((sender, args) => + { + Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); + }) + .LaunchAsync(); +``` + +### 示例 5：自定义操作和跳过选项 | Example 5: Custom Operations and Skip Options + +```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) + // 添加自定义操作（更新前检查环境）| Add custom operation (check environment before update) + .AddCustomOption(async () => + { + Console.WriteLine("正在检查运行环境..."); + await Task.Delay(1000); + // 检查磁盘空间、依赖项等 | Check disk space, dependencies, etc. + Console.WriteLine("环境检查完成"); + }) + // 设置用户跳过选项 | Set user skip option + .SetCustomSkipOption(() => + { + Console.WriteLine("发现新版本，是否更新？(y/n)"); + var input = Console.ReadLine(); + return input?.ToLower() == "y"; + }) + .LaunchAsync(); +``` + +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **版本号格式 | Version Number Format** + - 版本号必须遵循语义化版本规范（如 1.0.0.0） + - 确保客户端和服务器端版本号格式一致 + - 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** + - 在 Windows 上可能需要管理员权限来替换文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + - 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. + +### 💡 最佳实践 | Best Practices + +- **备份策略**：始终启用 BackUp 选项，以便更新失败时可以回滚 +- **差异更新**：启用 Patch 选项以减少下载量和更新时间 +- **错误处理**：实现完整的异常监听和错误处理逻辑 +- **用户体验**：在更新前提示用户并允许选择更新时机 +- **测试验证**：在生产环境部署前充分测试更新流程 +- **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**: 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 - -### Annotations - -GeneralClientBootstrap provides the following capabilities. - -#### Properties - -| Properties | Description | -| ------------ | ------------------------------------------------------------ | -| UpdateOption | Enum for update operation configuration settings | -| Configinfo | Client-related parameter class (fields like AppType, AppName, AppSecretKey, etc.) | - -#### Methods - -| Method | Description | -| -------------------------------------- | ------------------------------------------------------------ | -| LaunchTaskAsync() | Task-based asynchronous update launch | -| LaunchAsync() | Launch update | -| SetBlacklist() | Set blacklist for update files; pass in if certain files should not be updated. | -| Option() | Set update configuration. | -| Config() | Configure update-related parameters, such as server URL and port, appSecretKey for client identification and product branching. | -| GetOption() | Get update configuration. | -| SetCustomSkipOption() | Allow users to decide whether to proceed with an update in non-mandatory update scenarios. | -| AddCustomOption() | Add an asynchronous custom operation. In theory, any custom operation can be completed. It's recommended to register environment check methods to ensure dependencies and environment are intact after the update. | -| AddListenerMultiAllDownloadCompleted() | Notification for the completion of all download tasks. | -| AddListenerMultiDownloadCompleted() | Event for the completion of single or multiple update package downloads. | -| AddListenerMultiDownloadError() | Listen for errors during each version download | -| AddListenerMultiDownloadStatistics() | Notification for download speed, remaining download time, and current download version info. | -| AddListenerException() | Notification for any issues during the entire update process. | - -### 🌴Packet - -| Property | -| ------------------------------------------------------------ | -| **MainUpdateUrl** string Main update check API address. | -| **AppType** int 1:ClientApp 2:UpdateApp | -| **UpdateUrl** string Update check API address. | -| **AppName** string Name of the application to be launched. | -| **MainAppName** string Name of the main application to be launched. | -| **Format** string Update package file format (default is Zip). | -| **IsUpgradeUpdate** bool Indicates if the update is needed to upgrade the application. | -| **IsMainUpdate** bool Indicates if the main application needs an update. | -| **UpdateLogUrl** string URL for the update log webpage. | -| **UpdateVersions** List Version information that needs updating. | -| **Encoding** Encoding File operation encoding format. | -| **DownloadTimeOut** int Download timeout duration. | -| **AppSecretKey** string Application secret key, agreed upon with the server. | -| **ClientVersion** string Current client version. | -| **LastVersion** string Latest version. | -| **InstallPath** string Installation path (used for update file logic). | -| **TempPath** string Temporary storage path for downloaded files (used for update file logic). | -| **ProcessBase64** string Configuration parameters for the upgrade terminal program. | -| **Platform** string Platform to which the current strategy belongs (Windows\Linux\Mac). | -| **BlackFiles** List Files in the blacklist will be skipped during updates. | -| **BlackFormats** File formats in the blacklist will be skipped during updates. | -| **DriveEnabled** bool Indicates if the driver upgrade feature is enabled. | - - - -### 🌴Configinfo - -Certainly! Here's the translated content: - -| **Attribute** | Type | Notes | -| -------------------- | ------ | ------------------------------------------------------------ | -| UpdateUrl | string | API address for update checks. | -| ReportUrl | string | API address for reporting update status. | -| AppName | string | Name of the application that needs to be launched. | -| MainAppName | string | Name of the main application that needs to be launched. | -| UpdateLogUrl | string | Web address for the update log. | -| AppSecretKey | string | Application secret key, agreed upon with the server for authentication and branching. | -| ClientVersion | string | Current version number of the client. | -| UpgradeClientVersion | string | Current version number of the upgrade client. | -| InstallPath | string | Installation path (used for update file logic). | -| BlackFiles | List | Files in the blacklist will be skipped during updates. | -| BlackFormats | List | File formats in the blacklist will be skipped during updates. | -| SkipDirectorys | List | Directory paths to be skipped that do not require updates. | -| ProductId | string | Unique ID of the current product branch. | -| Bowl | string | Path to the Bowl monitoring process, which starts after updates to check if the Bowl client starts normally. If an exception occurs after starting, the exception information will be captured. | -| Scheme | string | Used for passing a token in HTTP requests for authentication. | -| Token | string | Token used in HTTP requests for authentication. | -| Script | string | This script assigns permissions to files and is executed on the Linux platform after the update is completed. If permissions need to be assigned before the update, this can be injected via the `GeneralClientBootstrap.AddCustomOption` function in the bootstrap startup class, and the function will be executed prior to the update. | - -### 🍵UpdateOption - -| Enum | -| ------------------------------------------------------------ | -| **Format** File format of the update package. | -| **Encoding** Compression encoding. | -| **DownloadTimeOut** Timeout duration (in seconds). If not specified, the default timeout is 30 seconds. | -| **Patch** Whether to enable the binary differential update function, which is enabled by default; if set to `false`, a full overwrite installation will be performed instead. | -| **BackUp** Whether to enable the backup function before update, which is enabled by default; no backup will be performed if set to `false`. | - - - -### Applicable To - -| Product | Version | -| -------------- | ---------------- | -| .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) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) diff --git a/website/docs/doc/GeneralUpdate.Core.md b/website/docs/doc/GeneralUpdate.Core.md index a8e0bc5..09ce675 100644 --- a/website/docs/doc/GeneralUpdate.Core.md +++ b/website/docs/doc/GeneralUpdate.Core.md @@ -2,75 +2,628 @@ sidebar_position: 5 --- -### Definition +# GeneralUpdate.Core -Namespace: GeneralUpdate.Core +## 组件概览 | Component Overview -Assembly: GeneralUpdate.Core.dll +**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一，提供了完整的升级执行能力。与 ClientCore 不同，Core 组件作为独立的升级助手程序运行，负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式，Core 接收来自 ClientCore 的更新指令，并安全地完成主程序的升级任务。 +**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. +**命名空间 | Namespace:** `GeneralUpdate.Core` +**程序集 | Assembly:** `GeneralUpdate.Core.dll` -GeneralUpdate.Core is one of the most essential components, providing a wide range of primary functionalities. Once the main program upgrade operation is completed, this component is invoked through process startup and parameter passing to complete the main program upgrade operation. (Main responsibility is updating the main program) - -```c# +```csharp public class GeneralUpdateBootstrap : AbstractBootstrap ``` +--- + +## 核心特性 | Core Features + +### 1. 文件替换与版本管理 | File Replacement and Version Management +- 安全的文件替换机制，避免文件占用问题 | Safe file replacement mechanism to avoid file locking issues +- 支持多版本增量升级 | Support multi-version incremental upgrades +- 自动处理文件依赖关系 | Automatic handling of file dependencies + +### 2. 驱动升级支持 | Driver Upgrade Support +- 可选的驱动程序升级功能 | Optional driver upgrade functionality +- 字段映射表配置 | Field mapping table configuration +- 安全的驱动安装流程 | Safe driver installation process + +### 3. 完整的事件通知 | Comprehensive Event Notifications +- 下载进度实时监控 | Real-time download progress monitoring +- 多版本下载管理 | Multi-version download management +- 异常和错误完整捕获 | Complete exception and error capture + +### 4. 跨平台支持 | Cross-Platform Support +- Windows、Linux、macOS 平台全支持 | Full support for Windows, Linux, macOS platforms +- 自动平台检测和策略适配 | Automatic platform detection and strategy adaptation + +![Multi Download](imgs/muti_donwload.png) + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Core： + +Install GeneralUpdate.Core via NuGet: + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 | Initialization and Usage + +以下示例展示了如何在升级助手程序中配置和启动升级流程： + +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 +{ + Console.WriteLine($"升级程序初始化，{DateTime.Now}！"); + Console.WriteLine("当前运行目录：" + Thread.GetDomain().BaseDirectory); + + // 启动升级流程 | Launch upgrade process + await new GeneralUpdateBootstrap() + // 监听下载统计信息 | 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) + // 启动异步升级 | Launch async upgrade + .LaunchAsync(); + + Console.WriteLine($"升级程序已启动，{DateTime.Now}！"); + await Task.Delay(2000); +} +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($"当前下载版本：{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 参考 | Core API Reference + +### GeneralUpdateBootstrap 类方法 | GeneralUpdateBootstrap Class Methods + +#### LaunchAsync 方法 | LaunchAsync Method + +异步启动升级流程。 + +Launch the upgrade process asynchronously. + +```csharp +public async Task LaunchAsync() +``` + +**返回值 | Return Value:** +- 返回当前 GeneralUpdateBootstrap 实例，支持链式调用 +- Returns the current GeneralUpdateBootstrap instance, supporting method chaining + +#### Option 方法 | Option Method + +设置升级选项。 + +Set upgrade options. + +```csharp +public GeneralUpdateBootstrap Option(UpdateOption option, object value) +``` + +**参数 | Parameters:** +- `option`: 升级选项枚举 | Upgrade option enum +- `value`: 选项值 | Option value + +**示例 | Example:** +```csharp +.Option(UpdateOption.Drive, true) // 启用驱动升级 | Enable driver upgrade +``` + +#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method + +监听下载统计信息（速度、进度、剩余时间等）。 + +Listen for download statistics (speed, progress, remaining time, etc.). + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( + Action callbackAction) +``` + +#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method + +监听单个更新包下载完成事件。 + +Listen for single update package download completion event. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method + +监听所有版本下载完成事件。 + +Listen for all version downloads completion event. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method +监听每个版本下载错误事件。 -### Example +Listen for download error events for each version. -GeneralUpdateBootstrap uses code examples [[View]](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs)。 +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadError( + Action callbackAction) +``` -![](imgs/muti_donwload.png) +#### AddListenerException 方法 | AddListenerException Method +监听升级组件内部所有异常。 +Listen for all internal exceptions in the upgrade component. -### Annotations +```csharp +public GeneralUpdateBootstrap AddListenerException( + Action callbackAction) +``` -GeneralUpdateBootstrap provides the following capabilities. +#### SetFieldMappings 方法 | SetFieldMappings Method -#### Constructors +设置字段映射表，用于解析驱动包信息。 -| Constructors | Description | -| ------------------------ | ------------------------------------------ | -| GeneralUpdateBootstrap() | Current GeneralUpdateBootstrap constructor | -| base:AbstractBootstrap() | Parent class AbstractBootstrap constructor | +Set field mapping table for parsing driver package information. -#### Properties +```csharp +public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) +``` -| Properties | Description | -| ------------ | ------------------------------------------ | -| Packet | Update package information | -| UpdateOption | Update operation configuration enumeration | +**参数 | Parameters:** +- `fieldMappings`: 字段映射字典，键为英文字段名，值为本地化字段名 +- Field mapping dictionary, key is English field name, value is localized field name -#### Methods +--- + +## 配置类详解 | Configuration Class Details -| Method | Description | -| -------------------------------------- | ---------------------------------------------------------- | -| LaunchTaskAsync() | Asynchronously launch update with Task | -| LaunchAsync() | Launch update | -| Option() | Set update configuration | -| GetOption() | Get update configuration | -| AddListenerMultiAllDownloadCompleted() | Listen for completion of all version downloads | -| AddListenerMultiDownloadCompleted() | Listen for completion of each version download | -| AddListenerMultiDownloadError() | Listen for download errors for each version | -| AddListenerMultiDownloadStatistics() | Listen for download statistics/progress for each version | -| AddListenerException() | Listen for all internal exceptions in the update component | +### UpdateOption 枚举 | UpdateOption Enum -### 🍵UpdateOption +```csharp +public enum UpdateOption +{ + /// + /// 是否启用驱动升级功能 + /// Whether to enable driver upgrade functionality + /// + Drive +} +``` -**Enumeration** +### Packet 类 | Packet Class -**Drive** Whether to enable driver upgrade functionality. +升级包信息类，由 ClientCore 通过参数传递给 Core： +Upgrade package information class, passed from ClientCore to Core via parameters: +```csharp +public class Packet +{ + /// + /// 主更新检查 API 地址 + /// Main update check API address + /// + public string MainUpdateUrl { get; set; } + + /// + /// 应用类型：1=客户端应用，2=更新应用 + /// Application type: 1=ClientApp, 2=UpdateApp + /// + public int AppType { get; set; } + + /// + /// 更新检查 API 地址 + /// Update check API address + /// + public string UpdateUrl { get; set; } + + /// + /// 需要启动的应用程序名称 + /// Name of the application to be launched + /// + public string AppName { get; set; } + + /// + /// 主应用程序名称 + /// Main application name + /// + public string MainAppName { get; set; } + + /// + /// 更新包文件格式（默认为 Zip） + /// Update package file format (default is Zip) + /// + public string Format { get; set; } + + /// + /// 是否需要升级更新应用 + /// Indicates if the update application needs to be upgraded + /// + public bool IsUpgradeUpdate { get; set; } + + /// + /// 是否需要更新主应用 + /// Indicates if the main application needs to be updated + /// + public bool IsMainUpdate { get; set; } + + /// + /// 更新日志网页 URL + /// Update log webpage URL + /// + public string UpdateLogUrl { get; set; } + + /// + /// 需要更新的版本信息列表 + /// List of version information that needs updating + /// + public List UpdateVersions { get; set; } + + /// + /// 文件操作编码格式 + /// File operation encoding format + /// + public Encoding Encoding { get; set; } + + /// + /// 下载超时时间（秒） + /// Download timeout duration (seconds) + /// + public int DownloadTimeOut { get; set; } + + /// + /// 应用密钥，与服务器约定 + /// Application secret key, agreed upon with the server + /// + public string AppSecretKey { get; set; } + + /// + /// 当前客户端版本 + /// Current client version + /// + public string ClientVersion { get; set; } + + /// + /// 最新版本 + /// Latest version + /// + public string LastVersion { get; set; } + + /// + /// 安装路径（用于更新文件逻辑） + /// Installation path (used for update file logic) + /// + public string InstallPath { get; set; } + + /// + /// 下载文件的临时存储路径 + /// Temporary storage path for downloaded files + /// + public string TempPath { get; set; } + + /// + /// 升级终端程序的配置参数（Base64 编码） + /// Configuration parameters for the upgrade terminal program (Base64 encoded) + /// + public string ProcessBase64 { get; set; } + + /// + /// 当前策略所属平台（Windows/Linux/Mac） + /// Platform to which the current strategy belongs (Windows/Linux/Mac) + /// + public string Platform { get; set; } + + /// + /// 黑名单文件列表 + /// Files in the blacklist + /// + public List BlackFiles { get; set; } + + /// + /// 黑名单文件格式列表 + /// File formats in the blacklist + /// + public List BlackFormats { get; set; } + + /// + /// 是否启用驱动升级功能 + /// Indicates if the driver upgrade feature is enabled + /// + public bool DriveEnabled { get; set; } +} +``` + +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：基本升级流程 | Example 1: Basic Upgrade Process + +```csharp +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Internal; +using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + +try +{ + Console.WriteLine("升级程序初始化..."); + + // 启动升级流程 | Launch upgrade process + await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}] 下载进度: {args.ProgressPercentage}%"); + }) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); + + Console.WriteLine("升级完成！"); +} +catch (Exception e) +{ + Console.WriteLine($"升级失败: {e.Message}"); +} +``` + +### 示例 2：启用驱动升级 | Example 2: Enable Driver Upgrade + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Internal.Bootstrap; + +// 中文字段映射表 | Chinese field mapping table +var fieldMappingsCN = new Dictionary +{ + { "DriverName", "驱动名称" }, + { "DriverVersion", "驱动版本" }, + { "DriverDescription", "驱动描述" }, + { "InstallPath", "安装路径" } +}; + +await new GeneralUpdateBootstrap() + // 设置字段映射表 | Set field mappings + .SetFieldMappings(fieldMappingsCN) + // 启用驱动更新 | Enable driver update + .Option(UpdateOption.Drive, true) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); +``` + +### 示例 3：完整事件监听 | Example 3: Complete Event Listening + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; + +await new GeneralUpdateBootstrap() + // 下载统计 | Download statistics + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}]"); + Console.WriteLine($" 速度: {args.Speed}"); + Console.WriteLine($" 进度: {args.ProgressPercentage}%"); + Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); + Console.WriteLine($" 剩余时间: {args.Remaining}"); + }) + // 单个下载完成 | Single download completed + .AddListenerMultiDownloadCompleted((sender, args) => + { + var version = args.Version as VersionInfo; + string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; + Console.WriteLine($"版本 {version.Version} 下载{status}"); + }) + // 所有下载完成 | All downloads completed + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + Console.WriteLine("✓ 所有版本下载完成，开始安装..."); + } + else + { + Console.WriteLine($"✗ 下载失败，{args.FailedVersions.Count} 个版本失败："); + foreach (var version in args.FailedVersions) + { + Console.WriteLine($" - {version}"); + } + } + }) + // 下载错误 | Download error + .AddListenerMultiDownloadError((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"✗ 版本 {version.Version} 错误:"); + Console.WriteLine($" {args.Exception.Message}"); + }) + // 异常处理 | Exception handling + .AddListenerException((sender, args) => + { + Console.WriteLine("⚠ 升级过程异常:"); + Console.WriteLine($" 错误: {args.Exception.Message}"); + Console.WriteLine($" 堆栈: {args.Exception.StackTrace}"); + }) + .LaunchAsync(); +``` + +### 示例 4：自定义升级流程 | Example 4: Custom Upgrade Process + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; + +// 记录升级开始时间 | Record upgrade start time +var startTime = DateTime.Now; +var downloadedVersions = new List(); + +await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadCompleted((sender, args) => + { + if (args.IsComplated) + { + var version = args.Version as VersionInfo; + downloadedVersions.Add(version.Version); + } + }) + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + var duration = DateTime.Now - startTime; + Console.WriteLine($"升级完成！"); + Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); + Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); + } + }) + .AddListenerException((sender, args) => + { + // 记录日志到文件 | Log to file + File.AppendAllText("upgrade_error.log", + $"[{DateTime.Now}] {args.Exception}\n"); + }) + .LaunchAsync(); +``` + +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **进程隔离 | Process Isolation** + - Core 必须作为独立进程运行，不能在主程序中直接调用 + - 升级时主程序必须完全关闭，否则文件替换会失败 + - Core must run as an independent process, cannot be called directly in the main program + - The main program must be completely closed during upgrade, otherwise file replacement will fail + +2. **参数传递 | Parameter Passing** + - ClientCore 通过 Base64 编码的参数传递配置给 Core + - 确保参数传递过程中不会被截断或损坏 + - ClientCore passes configuration to Core via Base64 encoded parameters + - Ensure parameters are not truncated or corrupted during passing + +3. **文件权限 | File Permissions** + - 在 Windows 上可能需要管理员权限替换系统目录中的文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + - Administrator privileges may be required on Windows to replace files in system directories + - Appropriate file system permissions are required on Linux/macOS + +4. **驱动升级 | Driver Upgrade** + - 驱动升级功能需要系统级权限 + - 建议在测试环境充分验证后再使用 + - Driver upgrade functionality requires system-level permissions + - Recommended to thoroughly validate in test environment before use + +5. **回滚机制 | Rollback Mechanism** + - Core 不直接提供回滚功能，但保留了备份文件 + - 如需回滚，可使用 ClientCore 的备份功能 + - Core does not directly provide rollback functionality, but backup files are preserved + - For rollback, use ClientCore's backup functionality + +### 💡 最佳实践 | Best Practices + +- **日志记录**：实现完整的异常监听，记录升级过程中的所有问题 +- **超时设置**：根据网络环境合理设置下载超时时间 +- **进度反馈**：向用户显示升级进度，提升用户体验 +- **错误处理**：升级失败时提供清晰的错误信息和解决方案 +- **测试验证**：在各种网络条件下测试升级流程的稳定性 +- **Logging**: Implement complete exception listening to record all issues during the upgrade process +- **Timeout Settings**: Set download timeout appropriately based on network environment +- **Progress Feedback**: Display upgrade progress to users to improve user experience +- **Error Handling**: Provide clear error messages and solutions when upgrade fails +- **Testing**: Test upgrade process stability under various network conditions + +--- + +## 适用平台 | Applicable Platforms + +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | + +--- -### Applicable to +## 相关资源 | Related Resources -| Product | Versions | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **相关组件**：[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) diff --git a/website/docs/doc/GeneralUpdate.Differential.md b/website/docs/doc/GeneralUpdate.Differential.md index b7f8576..7bf5a80 100644 --- a/website/docs/doc/GeneralUpdate.Differential.md +++ b/website/docs/doc/GeneralUpdate.Differential.md @@ -2,100 +2,474 @@ sidebar_position: 6 --- -### Definition +# GeneralUpdate.Differential -Namespace: GeneralUpdate.Differential +## 组件概览 | Component Overview -Assembly: GeneralUpdate.Core.dll +**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法，可以精确识别两个版本之间的文件变化，生成高效的增量补丁包，并支持补丁还原操作。通过使用差异更新，可以显著减少更新包的大小和下载时间，特别适合频繁发布更新的应用场景。 +**GeneralUpdate.Differential** is the core component responsible for binary differential updates in the GeneralUpdate framework. This component provides powerful differential algorithms that can accurately identify file changes between two versions, generate efficient incremental patch packages, and support patch restoration operations. By using differential updates, you can significantly reduce update package size and download time, making it particularly suitable for scenarios with frequent update releases. +**命名空间 | Namespace:** `GeneralUpdate.Differential` +**程序集 | Assembly:** `GeneralUpdate.Core.dll` -This component provides capabilities for generating binary differential patch files (algorithm), file increment identification (version differences), deleted file identification (version differences), blacklisting, patch restoration, and more. - -```c# +```csharp public sealed class DifferentialCore ``` +--- +## 核心特性 | Core Features -### Example +### 1. 增量识别 | Incremental Identification +- 精确识别新增、修改、删除的文件 | Accurately identify added, modified, and deleted files +- 智能文件版本对比 | Intelligent file version comparison +- 支持跳过指定文件和格式 | Support skipping specified files and formats -The following example defines methods for increment identification, generating binary patches, patch restoration, and setting blacklists. The packaging tool in the GeneralUpdate.Tools project also strongly depends on this component. +### 2. 二进制补丁生成 | Binary Patch Generation +- 高效的二进制差异算法 | Efficient binary differential algorithm +- 最小化补丁文件大小 | Minimize patch file size +- 快速补丁生成速度 | Fast patch generation speed -```c# -// Increment identification, generating binary patches -public async Task TestDifferentialClean() -{ - // Path to the previous version's client folder - var path1 = "D:\\packet\\source"; - // Path to the latest version's client folder - var path2 = "D:\\packet\\target"; - // Path for generating patch files - var path3 = "D:\\packet\\patchs"; - await DifferentialCore.Instance.Clean(path1, path2, path3); -} +### 3. 补丁还原 | Patch Restoration +- 安全的补丁应用流程 | Safe patch application process +- 自动处理文件依赖关系 | Automatic handling of file dependencies +- 完整性验证机制 | Integrity verification mechanism -// Patch restoration -public async Task TestDifferentialDirty() -{ - // Path to the current version's client folder - var path1 = "D:\\packet\\source"; - // Path for generating patch files - var path2 = "D:\\packet\\patchs"; - await DifferentialCore.Instance.Dirty(path1, path2); -} +### 4. 黑名单支持 | Blacklist Support +- 文件级黑名单 | File-level blacklist +- 格式级黑名单 | Format-level blacklist +- 灵活的过滤规则 | Flexible filtering rules + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Differential（包含在 Core 包中）： + +Install GeneralUpdate.Differential via NuGet (included in Core package): + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 | Initialization and Usage + +以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作： + +The following example demonstrates how to use DifferentialCore for incremental identification and patch operations: + +```csharp +using GeneralUpdate.Differential; + +// 增量识别并生成二进制补丁 | Identify increments and generate binary patches +var sourcePath = @"D:\packet\app"; // 旧版本路径 | Old version path +var targetPath = @"D:\packet\release"; // 新版本路径 | New version path +var patchPath = @"D:\packet\patch"; // 补丁输出路径 | Patch output path + +await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); + +// 应用补丁（还原） | Apply patches (restoration) +await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); +``` + +--- + +## 核心 API 参考 | Core API Reference + +### DifferentialCore 类 | DifferentialCore Class + +#### Instance 属性 | Instance Property + +获取 DifferentialCore 的单例实例。 + +Get the singleton instance of DifferentialCore. + +```csharp +public static DifferentialCore Instance { get; } +``` + +#### Clean 方法 | Clean Method + +执行增量识别、删除文件识别，并生成二进制补丁文件。 + +Perform incremental identification, deleted file identification, and generate binary patch files. + +**方法签名 | Method Signature:** + +```csharp +public async Task Clean(string sourcePath, string targetPath, string patchPath = null) ``` -### Annotations +**参数 | Parameters:** +- `sourcePath`: 旧版本文件夹路径 | Path to the old version folder +- `targetPath`: 新版本文件夹路径 | Path to the new version folder +- `patchPath`: 补丁文件输出目录（可选）| Directory to store discovered incremental update files (optional) + +**功能说明 | Function Description:** +1. 对比 sourcePath 和 targetPath 两个目录 +2. 识别新增、修改、删除的文件 +3. 为修改的文件生成二进制差异补丁 +4. 将补丁和新增文件保存到 patchPath + +**示例 | Example:** +```csharp +// 生成从 v1.0.0 到 v1.1.0 的补丁包 +var source = @"D:\MyApp\v1.0.0"; +var target = @"D:\MyApp\v1.1.0"; +var patch = @"D:\MyApp\patches\v1.1.0"; + +await DifferentialCore.Instance.Clean(source, target, patch); +// 结果：patch 目录包含所有必要的增量更新文件 +``` -DifferentialCore provides capabilities for increment identification, generating binary patches, patch restoration, and setting blacklists. +#### Dirty 方法 | Dirty Method -#### Methods +应用补丁，将旧版本文件更新到新版本。 -| Name | Type | Description | -| ------- | ------ | ------------------------------------------------------------ | -| Clean() | Method | Increment identification, deleted file identification, and generating binary patch files | -| Dirty() | Method | Patch restoration (applying patches to old client files to achieve updates) | +Apply patches to update old version files to the new version. -### 🌼Clean() +**方法签名 | Method Signature:** -**Method** +```csharp +public async Task Dirty(string appPath, string patchPath) +``` -Generate patch files [cannot include files with the same name but different extensions]. +**参数 | Parameters:** +- `appPath`: 客户端应用程序目录（当前版本）| Client application directory (current version) +- `patchPath`: 补丁文件路径 | Path to the patch files -```c# -public async Task Clean(string sourcePath, string targetPath, string patchPath = null); +**功能说明 | Function Description:** +1. 读取 patchPath 中的补丁文件 +2. 将补丁应用到 appPath 中的对应文件 +3. 处理新增文件的复制 +4. 处理删除文件的移除 + +**示例 | Example:** +```csharp +// 将补丁应用到当前应用程序 +var appDir = AppDomain.CurrentDomain.BaseDirectory; +var patchDir = Path.Combine(appDir, "temp", "patches"); + +await DifferentialCore.Instance.Dirty(appDir, patchDir); +// 结果：应用程序更新到新版本 ``` -**Parameters** +--- -**sourcePath** Path to the previous version's folder. +## 实际使用示例 | Practical Usage Examples -**targetPath** Path to the latest version's folder. +### 示例 1：基本补丁生成 | Example 1: Basic Patch Generation -**patchPath** Directory to store the discovered incremental update files temporarily. +```csharp +using GeneralUpdate.Differential; -### 🌼Dirty() +public async Task GeneratePatchAsync() +{ + try + { + // 版本路径 | Version paths + var oldVersion = @"D:\MyApp\1.0.0"; + var newVersion = @"D:\MyApp\1.0.1"; + var patchOutput = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始生成补丁..."); + + // 生成补丁 | Generate patches + await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); + + Console.WriteLine($"补丁生成完成！输出目录：{patchOutput}"); + + // 显示补丁信息 | Display patch information + var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); + Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); + + long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); + Console.WriteLine($"总补丁大小：{totalSize / 1024.0:F2} KB"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁生成失败：{ex.Message}"); + } +} +``` -**Method** +### 示例 2：应用补丁 | Example 2: Apply Patches -Apply patches [cannot include files with the same name but different extensions]. +```csharp +using GeneralUpdate.Differential; -```c# -public async Task Dirty(string appPath, string patchPath); +public async Task ApplyPatchAsync() +{ + try + { + // 应用程序目录 | Application directory + var appDirectory = @"D:\MyApp\current"; + // 补丁目录 | Patch directory + var patchDirectory = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始应用补丁..."); + + // 验证补丁存在 | Verify patch exists + if (!Directory.Exists(patchDirectory)) + { + throw new DirectoryNotFoundException($"补丁目录不存在：{patchDirectory}"); + } + + // 应用补丁 | Apply patches + await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); + + Console.WriteLine("补丁应用成功！应用程序已更新到新版本。"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁应用失败：{ex.Message}"); + } +} ``` -**Parameters** +### 示例 3：完整的补丁流程 | Example 3: Complete Patch Workflow -**appPath** Client application directory. +```csharp +using GeneralUpdate.Differential; +using System.IO.Compression; -**patchPath** Path to the patch files. +public class PatchManager +{ + // 生成并打包补丁 | Generate and package patches + public async Task CreatePatchPackageAsync( + string oldVersionPath, + string newVersionPath, + string outputPath) + { + try + { + // 1. 生成补丁文件 | Generate patch files + var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempPatchDir); + + Console.WriteLine($"正在生成补丁..."); + await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); + + // 2. 压缩补丁文件 | Compress patch files + var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); + Console.WriteLine($"正在打包补丁..."); + + if (File.Exists(patchZipPath)) + File.Delete(patchZipPath); + + ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, + CompressionLevel.Optimal, false); + + // 3. 清理临时文件 | Clean up temp files + Directory.Delete(tempPatchDir, true); + + var patchSize = new FileInfo(patchZipPath).Length; + Console.WriteLine($"补丁包创建成功：{patchZipPath}"); + Console.WriteLine($"补丁包大小：{patchSize / 1024.0:F2} KB"); + + return patchZipPath; + } + catch (Exception ex) + { + Console.WriteLine($"创建补丁包失败：{ex.Message}"); + throw; + } + } + + // 解压并应用补丁 | Extract and apply patches + public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) + { + try + { + // 1. 解压补丁包 | Extract patch package + var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempExtractDir); + + Console.WriteLine($"正在解压补丁包..."); + ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); + + // 2. 应用补丁 | Apply patches + Console.WriteLine($"正在应用补丁..."); + await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); + + // 3. 清理临时文件 | Clean up temp files + Directory.Delete(tempExtractDir, true); + + Console.WriteLine($"补丁应用成功！"); + } + catch (Exception ex) + { + Console.WriteLine($"应用补丁包失败：{ex.Message}"); + throw; + } + } +} + +// 使用示例 | Usage example +var manager = new PatchManager(); + +// 创建补丁包 | Create patch package +var patchZip = await manager.CreatePatchPackageAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\releases" +); + +// 应用补丁包 | Apply patch package +await manager.ApplyPatchPackageAsync( + @"D:\MyApp\current", + patchZip +); +``` + +### 示例 4：带进度显示的补丁操作 | Example 4: Patch Operations with Progress Display + +```csharp +using GeneralUpdate.Differential; + +public class ProgressivePatchManager +{ + public async Task GeneratePatchWithProgressAsync( + string sourcePath, + string targetPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始扫描文件差异..."); + + // 在实际场景中，可以在 Clean 前后添加进度报告 + await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); + + progress?.Report("补丁生成完成！"); + + // 统计信息 | Statistics + var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); + progress?.Report($"共生成 {files.Length} 个补丁文件"); + } + catch (Exception ex) + { + progress?.Report($"错误：{ex.Message}"); + throw; + } + } + + public async Task ApplyPatchWithProgressAsync( + string appPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始应用补丁..."); + + await DifferentialCore.Instance.Dirty(appPath, patchPath); + + progress?.Report("补丁应用成功！"); + } + catch (Exception ex) + { + progress?.Report($"错误：{ex.Message}"); + throw; + } + } +} + +// 使用示例 | Usage example +var manager = new ProgressivePatchManager(); +var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); + +await manager.GeneratePatchWithProgressAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\patches\1.0.1", + progress +); +``` +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **文件名限制 | File Name Restrictions** + - 不能包含同名但扩展名不同的文件（如 file.txt 和 file.log） + - 建议使用唯一的文件名命名规则 + - Cannot include files with the same name but different extensions (e.g., file.txt and file.log) + - Recommended to use unique file naming conventions + +2. **目录结构 | Directory Structure** + - 源目录和目标目录的相对结构应保持一致 + - 补丁生成时会保留目录层次关系 + - The relative structure of source and target directories should remain consistent + - Directory hierarchy is preserved during patch generation + +3. **磁盘空间 | Disk Space** + - 确保有足够的磁盘空间存储补丁文件 + - 二进制差异补丁通常比完整文件小，但仍需要临时空间 + - Ensure sufficient disk space for storing patch files + - Binary differential patches are usually smaller than complete files, but still require temporary space + +4. **文件占用 | File Locking** + - 应用补丁时，确保目标文件没有被其他进程占用 + - 建议在应用程序关闭后应用补丁 + - When applying patches, ensure target files are not locked by other processes + - Recommended to apply patches after the application is closed + +5. **备份建议 | Backup Recommendations** + - 在应用补丁前建议备份原始文件 + - 可以使用 ClientCore 的 BackUp 选项自动备份 + - Recommended to backup original files before applying patches + - Can use ClientCore's BackUp option for automatic backup + +### 💡 最佳实践 | Best Practices + +- **版本管理**：为每个版本维护独立的补丁包，便于版本追踪和回滚 +- **补丁验证**：生成补丁后进行验证测试，确保补丁可以正确应用 +- **增量更新**：优先使用差异更新而非全量更新，可节省 50%-90% 的下载量 +- **错误处理**：实现完整的异常捕获和错误恢复机制 +- **性能优化**：对于大文件，差异算法的性能优势更加明显 +- **Version Management**: Maintain separate patch packages for each version for easier version tracking and rollback +- **Patch Validation**: Perform validation testing after generating patches to ensure they can be applied correctly +- **Incremental Updates**: Prioritize differential updates over full updates, which can save 50%-90% of download size +- **Error Handling**: Implement complete exception capture and error recovery mechanisms +- **Performance Optimization**: For large files, the performance advantage of the differential algorithm is more pronounced + +### 🔍 工作原理 | How It Works + +**Clean 方法工作流程 | Clean Method Workflow:** +1. 扫描源目录和目标目录中的所有文件 +2. 比较文件的MD5哈希值以识别变化 +3. 对于修改的文件，使用二进制差异算法生成补丁 +4. 对于新增文件，直接复制到补丁目录 +5. 记录删除的文件列表 + +**Dirty 方法工作流程 | Dirty Method Workflow:** +1. 读取补丁目录中的所有文件 +2. 对于补丁文件，应用到对应的原文件上 +3. 对于新增文件，直接复制到应用目录 +4. 根据删除列表移除相应文件 +5. 验证更新完整性 + +--- + +## 适用平台 | Applicable Platforms + +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | + +--- -### Applicable to +## 相关资源 | Related Resources -| Product | Versions | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **打包工具**：GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 | The GeneralUpdate.PacketTool project depends on this component for differential packaging From a5818b38ba9594837b2251f7e8dd542009d404e0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:24:30 +0000 Subject: [PATCH 3/7] Update i18n files and add C# syntax highlighting support Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com> --- website/docusaurus.config.js | 1 + .../current/doc/GeneralUpdate.Bowl.md | 423 ++++++---- .../current/doc/GeneralUpdate.ClientCore.md | 733 +++++++++++++++--- .../current/doc/GeneralUpdate.Core.md | 637 ++++++++++++++- .../current/doc/GeneralUpdate.Differential.md | 494 ++++++++++-- 5 files changed, 1942 insertions(+), 346 deletions(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 4cb20ee..575efb3 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -127,6 +127,7 @@ const config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, + additionalLanguages: ['csharp', 'bash', 'json'], }, }), }; diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md index 6cfe08b..5af0825 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md @@ -2,59 +2,237 @@ sidebar_position: 3 --- -### Definition +# GeneralUpdate.Bowl -Namespace: GeneralUpdate.Bowl +## 组件概览 | Component Overview -Assembly: GeneralUpdate.Bowl.dll +**GeneralUpdate.Bowl** 是一个独立的进程监控组件，在升级流程结束前启动，负责启动主客户端应用程序并监控其运行状态。该组件提供了完整的崩溃监控和诊断能力，当被监控的应用程序发生异常时，会自动导出Dump文件、驱动信息、系统信息和事件日志，帮助开发者快速定位问题。 -This component is an independent process launched before the end of the upgrade process. It starts the main client application and monitors its normal operation before the process ends. +**GeneralUpdate.Bowl** is an independent process monitoring component that launches before the end of the upgrade process. It is responsible for starting the main client application and monitoring its running status. This component provides comprehensive crash monitoring and diagnostic capabilities. When the monitored application encounters an exception, it automatically exports Dump files, driver information, system information, and event logs to help developers quickly locate issues. -```c# +**命名空间 | Namespace:** `GeneralUpdate.Bowl` +**程序集 | Assembly:** `GeneralUpdate.Bowl.dll` + +```csharp public sealed class Bowl ``` +--- + +## 核心特性 | Core Features + +### 1. 进程监控 | Process Monitoring +- 实时监控目标应用程序的运行状态 | Real-time monitoring of target application status +- 自动检测进程崩溃和异常退出 | Automatic detection of process crashes and abnormal exits + +### 2. 崩溃诊断 | Crash Diagnostics +- 自动生成Dump文件（.dmp）用于崩溃分析 | Automatic generation of Dump files (.dmp) for crash analysis +- 导出详细的系统和驱动信息 | Export detailed system and driver information +- 收集Windows系统事件日志 | Collect Windows system event logs + +### 3. 版本化管理 | Version Management +- 按版本号分类存储故障信息 | Store failure information categorized by version number +- 支持升级和正常两种工作模式 | Support both upgrade and normal working modes + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Bowl： + +Install GeneralUpdate.Bowl via NuGet: + +```bash +dotnet add package GeneralUpdate.Bowl +``` + +### 初始化与使用 | Initialization and Usage +以下示例展示了如何使用 Bowl 组件监控应用程序： -### Example +The following example demonstrates how to use the Bowl component to monitor an application: -The following example defines a method that includes the use of Bowl. +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; -```c# var installPath = AppDomain.CurrentDomain.BaseDirectory; var lastVersion = "1.0.0.3"; var processInfo = new MonitorParameter { - ProcessNameOrId = "JsonTest.exe", + ProcessNameOrId = "YourApp.exe", DumpFileName = $"{lastVersion}_fail.dmp", FailFileName = $"{lastVersion}_fail.json", TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", lastVersion), BackupDirectory = Path.Combine(installPath, lastVersion), - WorkModel = "Normal" + WorkModel = "Normal" // 使用 Normal 模式独立监控 | Use Normal mode for standalone monitoring }; Bowl.Launch(processInfo); ``` -### Capture +--- + +## 核心 API 参考 | Core API Reference + +### Launch 方法 | Launch Method + +启动进程监控功能。 + +Start the process monitoring functionality. + +**方法签名 | Method Signature:** + +```csharp +public static void Launch(MonitorParameter? monitorParameter = null) +``` + +**参数 | Parameters:** + +#### MonitorParameter 类 | MonitorParameter Class + +```csharp +public class MonitorParameter +{ + /// + /// 被监控的目录 + /// Directory being monitored + /// + public string TargetPath { get; set; } + + /// + /// 导出异常信息的目录 + /// Directory where captured exception information is exported + /// + public string FailDirectory { get; set; } + + /// + /// 备份目录 + /// Backup directory + /// + public string BackupDirectory { get; set; } + + /// + /// 被监控进程的名称或ID + /// Name or ID of the process being monitored + /// + public string ProcessNameOrId { get; set; } + + /// + /// Dump 文件名 + /// Dump file name + /// + public string DumpFileName { get; set; } + + /// + /// 升级包版本信息（.json）文件名 + /// Upgrade package version information (.json) file name + /// + public string FailFileName { get; set; } + + /// + /// 工作模式： + /// - Upgrade: 升级模式，主要用于与 GeneralUpdate 配合使用，内部逻辑处理，默认模式启动时请勿随意修改 + /// - Normal: 正常模式，可独立使用监控单个程序，程序崩溃时导出崩溃信息 + /// + /// Work Mode: + /// - Upgrade: Upgrade mode, primarily used in conjunction with GeneralUpdate for internal logic handling. + /// Do not modify arbitrarily when the default mode is activated. + /// - Normal: Normal mode, can be used independently to monitor a single program. + /// Exports crash information when the program crashes. + /// + public string WorkModel { get; set; } = "Upgrade"; +} +``` + +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：独立模式监控应用 | Example 1: Standalone Mode Application Monitoring + +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; + +// 配置监控参数 | Configure monitoring parameters +var installPath = AppDomain.CurrentDomain.BaseDirectory; +var currentVersion = "1.0.0.5"; + +var monitorConfig = new MonitorParameter +{ + ProcessNameOrId = "MyApplication.exe", + DumpFileName = $"{currentVersion}_crash.dmp", + FailFileName = $"{currentVersion}_crash.json", + TargetPath = installPath, + FailDirectory = Path.Combine(installPath, "crash_reports", currentVersion), + BackupDirectory = Path.Combine(installPath, "backups", currentVersion), + WorkModel = "Normal" // 独立监控模式 | Standalone monitoring mode +}; + +// 启动监控 | Start monitoring +Bowl.Launch(monitorConfig); +``` + +### 示例 2：结合 GeneralUpdate 使用 | Example 2: Use with GeneralUpdate -If a crash is detected, the following files will be generated in the running directory: +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; -- 📒 Dump file (1.0.0.*_fail.dmp) -- 📒 Upgrade package version information (1.0.0.*_fail.json) -- 📒 Driver information (driverInfo.txt) -- 📒 Operating system/hardware information (systeminfo.txt) -- 📒 System event log (systemlog.evtx) +// 在升级完成后启动 Bowl 监控 | Start Bowl monitoring after upgrade completion +var installPath = AppDomain.CurrentDomain.BaseDirectory; +var upgradedVersion = "2.0.0.1"; -These will be exported to the "fail" directory, categorized by version number. +var upgradeMonitor = new MonitorParameter +{ + ProcessNameOrId = "UpdatedApp.exe", + DumpFileName = $"{upgradedVersion}_fail.dmp", + FailFileName = $"{upgradedVersion}_fail.json", + TargetPath = installPath, + FailDirectory = Path.Combine(installPath, "fail", upgradedVersion), + BackupDirectory = Path.Combine(installPath, upgradedVersion), + WorkModel = "Upgrade" // 升级模式 | Upgrade mode +}; -![](imgs\crash.jpg) +Bowl.Launch(upgradeMonitor); +``` -#### (1) x.0.0.*_fail.dmp +--- -![](imgs\dump.png) +## 崩溃信息捕获 | Crash Information Capture -#### (2) x.0.0.*_fail.json +当检测到崩溃时，以下文件将在运行目录中生成： + +When a crash is detected, the following files will be generated in the running directory: + +- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) | **Dump file** (`x.0.0.*_fail.dmp`) +- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) | **Upgrade package version information** (`x.0.0.*_fail.json`) +- 📒 **驱动信息** (`driverInfo.txt`) | **Driver information** (`driverInfo.txt`) +- 📒 **操作系统/硬件信息** (`systeminfo.txt`) | **Operating system/hardware information** (`systeminfo.txt`) +- 📒 **系统事件日志** (`systemlog.evtx`) | **System event log** (`systemlog.evtx`) + +这些文件将按版本号分类导出到 "fail" 目录中。 + +These files will be exported to the "fail" directory, categorized by version number. + +![Crash Files](imgs/crash.jpg) + +### 1. Dump 文件 | Dump File + +Dump 文件包含崩溃时刻的内存快照，可用于调试分析： + +The Dump file contains a memory snapshot at the moment of crash, which can be used for debugging analysis: + +![Dump File](imgs/dump.png) + +### 2. 版本信息文件 | Version Information File + +JSON 格式的详细崩溃报告，包含参数配置和 ProcDump 输出： + +Detailed crash report in JSON format, including parameter configuration and ProcDump output: ```json { @@ -96,147 +274,100 @@ These will be exported to the "fail" directory, categorized by version number. } ``` -#### (3) driverInfo.txt +### 3. 驱动信息文件 | Driver Information File -```json -Module Name Display Name Description Driver Type Start Mode State Status Accept Stop Accept Pause Paged Pool Code(Bytes) BSS(Bytes) Link Date Path Init(Bytes) -============ ====================== ====================== ============= ========== ========== ========== =========== ============ ========== ========== ======= ====================== ================================================ ========== -360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK TRUE FALSE 4,096 36,864 0 9/29/2022 3:45:03 PM C:\Windows\system32\Drivers\360AntiAttack64.sys 4,096 -360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK TRUE FALSE 4,096 139,264 0 11/27/2023 3:43:37 PM C:\Windows\system32\Drivers\360AntiHacker64.sys 8,192 -360AntiHijac 360Safe Anti Hijack Se 360Safe Anti Hijack Se Kernel System Running OK TRUE FALSE 4,096 73,728 0 5/8/2024 12:19:52 PM C:\Windows\system32\Drivers\360AntiHijack64.sys 4,096 -360AntiSteal 360Safe Anti Steal Fil 360Safe Anti Steal Fil Kernel System Running OK TRUE FALSE 4,096 20,480 0 4/18/2024 3:58:04 PM C:\Windows\system32\Drivers\360AntiSteal64.sys 8,192 -360Box64 360Box mini-filter dri 360Box mini-filter dri File System System Running OK TRUE FALSE 0 225,280 0 8/7/2024 11:50:19 AM C:\Windows\system32\DRIVERS\360Box64.sys 12,288 - -//... +包含系统中所有驱动程序的详细信息： + +Contains detailed information about all drivers in the system: + +```text +Module Name Display Name Description Driver Type Start Mode State Status +============ ====================== ====================== ============= ========== ========== ========== +360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK +360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK +// ...更多驱动信息 | ...more driver information ``` -#### (4) systeminfo.txt +### 4. 系统信息文件 | System Information File -```json +完整的操作系统和硬件配置信息： + +Complete operating system and hardware configuration information: + +```text Host Name: **** -OS Name: Microsoft Windows 11 Pro -OS Version: 10.0.2*** Build 22*** -OS Manufacturer: Microsoft Corporation -OS Configuration: Standalone Workstation -OS Build Type: Multiprocessor Free -Registered Owner: ****@outlook.com -Registered Organization: -Product ID: ****-80000-***00-A**** -Original Install Date: 11/16/2023, 9:56:28 PM -System Boot Time: 11/26/2024, 9:37:51 PM -System Manufacturer: ASUS -System Model: System Product Name -System Type: x64-based PC -Processor(s): Installed 1 Processor(s). - [01]: Intel** Family * Model *** Stepping * GenuineIntel ~**** Mhz -BIOS Version: American Megatrends Inc. 1402, 4/1/2022 -Windows Directory: C:\Windows -System Directory: C:\Windows\system32 -Boot Device: \Device\Ha*****olume1 -System Locale: zh-cn;Chinese (China) -Input Locale: zh-cn;Chinese (China) -Time Zone: (UTC+08:00) **，**，*******，**** -Total Physical Memory: 16,194 MB -Available Physical Memory: 1,795 MB -Virtual Memory: Max Size: 25,410 MB -Virtual Memory: Available: 9,438 MB -Virtual Memory: In Use: 15,972 MB -Page File Location(s): D:\****file.sys -Domain: WORKGROUP -Logon Server: \\**** -Hotfix(s):: 6 Hotfix(s) Installed. - [01]: KB504**** - [02]: KB502**** - [03]: KB503**** - [04]: KB503**** - [05]: KB504**** - [06]: KB504**** -Network Card(s): 3 NIC(s) Installed. - [01]: Intel(R) Ethernet Connection (**) I***-V - Connection Name: Ethernet - DHCP Enabled: Yes - DHCP Server: 192.168.**.** - IP Address - [01]: 192.168.**.** - [02]: ***::2640:***:****:**** - [02]: VMware Virtual Ethernet Adapter for VMnet1 - Connection Name: VMware Network Adapter VMnet1 - DHCP Enabled: Yes - DHCP Server: 192.168.**.** - IP Address - [01]: 192.168.**.** - [02]: ***::9b3:***,***:**** - [03]: VMware Virtual Ethernet Adapter for VMnet8 - Connection Name: VMware Network Adapter VMnet8 - DHCP Enabled: Yes - DHCP Server: 192.168.**.** - IP Address - [01]: 192.***,***:**** - [02]: fe80::***:***:***:**** -Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed. - -//... +OS Name: Microsoft Windows 11 Pro +OS Version: 10.0.*** Build 22*** +System Manufacturer: ASUS +System Model: System Product Name +Processor(s): Intel** Family * Model *** +Total Physical Memory: 16,194 MB +// ...更多系统信息 | ...more system information ``` -#### (5) systemlog.evtx +### 5. 系统事件日志 | System Event Log -![](imgs\evtx.png) +Windows 事件查看器格式的系统日志（.evtx 文件）： -### Notes +System log in Windows Event Viewer format (.evtx file): -Bowl provides runtime monitoring capabilities and exports relevant error information. +![System Event Log](imgs/evtx.png) -#### Methods +--- -| Method | Description | -| -------- | ---------------- | -| Launch() | Start monitoring | +## 注意事项与警告 | Notes and Warnings -### 🌼Launch() +### ⚠️ 重要提示 | Important Notes -**Launch Function** +1. **工作模式选择 | Work Mode Selection** + - `Upgrade` 模式：专门用于与 GeneralUpdate 框架集成，包含内部逻辑处理 + - `Normal` 模式：可独立使用，适合监控任何 .NET 应用程序 + - `Upgrade` mode: Specifically for integration with GeneralUpdate framework, includes internal logic processing + - `Normal` mode: Can be used independently, suitable for monitoring any .NET application -```c# -Launch(MonitorParameter? monitorParameter = null); -``` +2. **权限要求 | Permission Requirements** + - Bowl 需要足够的权限来生成 Dump 文件和读取系统信息 + - 建议以管理员权限运行需要监控的应用程序 + - Bowl requires sufficient permissions to generate Dump files and read system information + - It is recommended to run the monitored application with administrator privileges -**Parameters** +3. **磁盘空间 | Disk Space** + - Dump 文件可能占用大量磁盘空间（通常 50-200 MB） + - 确保 FailDirectory 所在磁盘有足够的可用空间 + - Dump files may consume significant disk space (typically 50-200 MB) + - Ensure sufficient available space on the disk where FailDirectory is located -```c# -public class MonitorParameter -{ - // Directory being monitored - public string TargetPath { get; set; } - - // Directory where captured exception information is exported - public string FailDirectory { get; set; } - - // Backup directory - public string BackupDirectory { get; set; } - - // Name or ID of the process being monitored - public string ProcessNameOrId { get; set; } - - // Dump file name - public string DumpFileName { get; set; } - - // Upgrade package version information (.json) file name - public string FailFileName { get; set; } +4. **依赖项 | Dependencies** + - Bowl 使用 ProcDump 工具生成 Dump 文件，该工具已内置在组件中 + - 无需额外安装依赖项 + - Bowl uses the ProcDump tool to generate Dump files, which is built into the component + - No additional dependencies need to be installed - /// - /// Upgrade: upgrade mode. This mode is primarily used in conjunction with GeneralUpdate for internal use. Please do not modify it arbitrarily when the default mode is activated. - /// Normal: Normal mode, This mode can be used independently to monitor a single program. If the program crashes, it will export the crash information. - /// - public string WorkModel { get; set; } = "Upgrade"; -} -``` +### 💡 最佳实践 | Best Practices + +- **版本号管理**：为每个版本使用独立的故障目录，便于问题追踪 +- **日志清理**：定期清理旧版本的故障信息，避免磁盘空间耗尽 +- **测试验证**：在生产环境部署前，在测试环境验证监控功能 +- **Version Management**: Use separate failure directories for each version for easier issue tracking +- **Log Cleanup**: Regularly clean up failure information from old versions to avoid disk space exhaustion +- **Testing**: Verify monitoring functionality in a test environment before production deployment + +--- + +## 适用平台 | Applicable Platforms + +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +| ASP.NET | Any | + +--- -### Applicable To +## 相关资源 | Related Resources -| Product | Version | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | -| ASP.NET | Any | \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) +- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) | [Watch Bilibili Tutorial](https://www.bilibili.com/video/BV1c8iyYZE7P) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) \ No newline at end of file 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 index fbf4086..005337f 100644 --- 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 @@ -2,131 +2,670 @@ sidebar_position: 4 --- -### Definition +# GeneralUpdate.ClientCore -Namespace: GeneralUpdate.ClientCore +## 组件概览 | Component Overview -Assembly: GeneralUpdate.ClientCore.dll +**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一，提供了丰富的客户端更新功能。该组件运行在主应用程序中，负责检查更新、下载更新包、验证完整性，并在完成后启动升级助手（GeneralUpdate.Core）来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新，而不影响当前运行状态。 +**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` -GeneralUpdate.ClientCore is one of the core components, offering a wide range of primary functionalities. Its essence is similar to Core, but it has a different role: ClientCore is used in the main program, where it assists in updates and upgrades and then closes the main program to launch the upgrade assistant. - -```c# +```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 + +### 3. 完整的事件通知 | Comprehensive Event Notifications +- 下载进度、完成、错误事件 | Download progress, completion, and error events +- 支持用户自定义跳过更新选项 | Support user-defined skip update options +- 异常和错误全程监控 | Exception and error monitoring throughout the process + +### 4. 多平台支持 | Multi-Platform Support +- Windows、Linux、macOS 平台支持 | Windows, Linux, macOS platform support +- 自动平台检测和策略选择 | Automatic platform detection and strategy selection + +![Multi Download](imgs/muti_donwload.png) + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.ClientCore： + +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($"主程序初始化，{DateTime.Now}！"); + + // 配置更新参数 | Configure update parameters + var configinfo = new Configinfo + { + // 更新验证 API 地址 | Update verification API address + UpdateUrl = "http://127.0.0.1:5000/Upgrade/Verification", + // 更新报告 API 地址 | 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, + // 产品 ID（用于多产品分支管理）| 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($"主程序已启动，{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($"下载版本：{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 参考 | Core API Reference + +### GeneralClientBootstrap 类方法 | GeneralClientBootstrap Class Methods + +#### LaunchAsync 方法 | LaunchAsync Method + +异步启动更新流程。 + +Launch the update process asynchronously. + +```csharp +public async Task LaunchAsync() +``` + +#### SetConfig 方法 | SetConfig Method +设置更新配置信息。 -### Example +Set update configuration information. -GeneralClientBootstrap uses code examples [[View]](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs)。 +```csharp +public GeneralClientBootstrap SetConfig(Configinfo configinfo) +``` -![](imgs/muti_donwload.png) +#### Option 方法 | Option Method +设置更新选项。 +Set update options. -### Annotations +```csharp +public GeneralClientBootstrap Option(UpdateOption option, object value) +``` -GeneralClientBootstrap provides the following capabilities. +#### SetBlacklist 方法 | SetBlacklist Method -#### Properties +设置更新黑名单，指定不需要更新的文件。 -| Properties | Description | -| ------------ | ------------------------------------------------------------ | -| UpdateOption | Enum for update operation configuration settings | -| Configinfo | Client-related parameter class (fields like AppType, AppName, AppSecretKey, etc.) | +Set update blacklist to specify files that should not be updated. -#### Methods +```csharp +public GeneralClientBootstrap SetBlacklist(List blackFiles = null, + List blackFormats = null) +``` -| Method | Description | -| -------------------------------------- | ------------------------------------------------------------ | -| LaunchTaskAsync() | Task-based asynchronous update launch | -| LaunchAsync() | Launch update | -| SetBlacklist() | Set blacklist for update files; pass in if certain files should not be updated. | -| Option() | Set update configuration. | -| Config() | Configure update-related parameters, such as server URL and port, appSecretKey for client identification and product branching. | -| GetOption() | Get update configuration. | -| SetCustomSkipOption() | Allow users to decide whether to proceed with an update in non-mandatory update scenarios. | -| AddCustomOption() | Add an asynchronous custom operation. In theory, any custom operation can be completed. It's recommended to register environment check methods to ensure dependencies and environment are intact after the update. | -| AddListenerMultiAllDownloadCompleted() | Notification for the completion of all download tasks. | -| AddListenerMultiDownloadCompleted() | Event for the completion of single or multiple update package downloads. | -| AddListenerMultiDownloadError() | Listen for errors during each version download | -| AddListenerMultiDownloadStatistics() | Notification for download speed, remaining download time, and current download version info. | -| AddListenerException() | Notification for any issues during the entire update process. | +#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method -### 🌴Packet +监听下载统计信息（速度、进度、剩余时间等）。 -| Property | -| ------------------------------------------------------------ | -| **MainUpdateUrl** string Main update check API address. | -| **AppType** int 1:ClientApp 2:UpdateApp | -| **UpdateUrl** string Update check API address. | -| **AppName** string Name of the application to be launched. | -| **MainAppName** string Name of the main application to be launched. | -| **Format** string Update package file format (default is Zip). | -| **IsUpgradeUpdate** bool Indicates if the update is needed to upgrade the application. | -| **IsMainUpdate** bool Indicates if the main application needs an update. | -| **UpdateLogUrl** string URL for the update log webpage. | -| **UpdateVersions** List Version information that needs updating. | -| **Encoding** Encoding File operation encoding format. | -| **DownloadTimeOut** int Download timeout duration. | -| **AppSecretKey** string Application secret key, agreed upon with the server. | -| **ClientVersion** string Current client version. | -| **LastVersion** string Latest version. | -| **InstallPath** string Installation path (used for update file logic). | -| **TempPath** string Temporary storage path for downloaded files (used for update file logic). | -| **ProcessBase64** string Configuration parameters for the upgrade terminal program. | -| **Platform** string Platform to which the current strategy belongs (Windows\Linux\Mac). | -| **BlackFiles** List Files in the blacklist will be skipped during updates. | -| **BlackFormats** File formats in the blacklist will be skipped during updates. | -| **DriveEnabled** bool Indicates if the driver upgrade feature is enabled. | +Listen for download statistics (speed, progress, remaining time, etc.). +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadStatistics( + Action callbackAction) +``` +#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method -### 🌴Configinfo +监听单个更新包下载完成事件。 -Certainly! Here's the translated content: +Listen for single update package download completion event. -| **Attribute** | Type | Notes | -| -------------------- | ------ | ------------------------------------------------------------ | -| UpdateUrl | string | API address for update checks. | -| ReportUrl | string | API address for reporting update status. | -| AppName | string | Name of the application that needs to be launched. | -| MainAppName | string | Name of the main application that needs to be launched. | -| UpdateLogUrl | string | Web address for the update log. | -| AppSecretKey | string | Application secret key, agreed upon with the server for authentication and branching. | -| ClientVersion | string | Current version number of the client. | -| UpgradeClientVersion | string | Current version number of the upgrade client. | -| InstallPath | string | Installation path (used for update file logic). | -| BlackFiles | List | Files in the blacklist will be skipped during updates. | -| BlackFormats | List | File formats in the blacklist will be skipped during updates. | -| SkipDirectorys | List | Directory paths to be skipped that do not require updates. | -| ProductId | string | Unique ID of the current product branch. | -| Bowl | string | Path to the Bowl monitoring process, which starts after updates to check if the Bowl client starts normally. If an exception occurs after starting, the exception information will be captured. | -| Scheme | string | Used for passing a token in HTTP requests for authentication. | -| Token | string | Token used in HTTP requests for authentication. | -| Script | string | This script assigns permissions to files and is executed on the Linux platform after the update is completed. If permissions need to be assigned before the update, this can be injected via the `GeneralClientBootstrap.AddCustomOption` function in the bootstrap startup class, and the function will be executed prior to the update. | +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method + +监听所有下载任务完成事件。 + +Listen for all download tasks completion event. + +```csharp +public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method + +监听下载错误事件。 +Listen for download error events. + +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadError( + Action callbackAction) +``` +#### AddListenerException 方法 | AddListenerException Method + +监听更新过程中的所有异常。 + +Listen for all exceptions during the update process. + +```csharp +public GeneralClientBootstrap AddListenerException( + Action callbackAction) +``` + +#### AddCustomOption 方法 | AddCustomOption Method + +添加自定义异步操作，可在更新前后执行自定义逻辑。 + +Add custom asynchronous operations that can execute custom logic before or after updates. + +```csharp +public GeneralClientBootstrap AddCustomOption(Func customFunc) +``` + +#### SetCustomSkipOption 方法 | SetCustomSkipOption Method + +设置自定义跳过选项，允许用户决定是否继续更新。 + +Set custom skip options, allowing users to decide whether to continue with the update. + +```csharp +public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) +``` + +--- + +## 配置类详解 | Configuration Class Details + +### Configinfo 类 | Configinfo Class + +```csharp +public class Configinfo +{ + /// + /// 更新检查 API 地址 + /// Update check API address + /// + public string UpdateUrl { get; set; } + + /// + /// 更新状态报告 API 地址 + /// 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; } + + /// + /// 当前产品分支的唯一 ID + /// Unique ID of the current product branch + /// + public string ProductId { get; set; } + + /// + /// Bowl 监控进程路径，更新完成后启动 Bowl 检查客户端是否正常启动 + /// Bowl monitoring process path, starts after updates to check if the client starts normally + /// + public string Bowl { get; set; } + + /// + /// HTTP 请求中用于传递 token 的 Scheme（如 Bearer） + /// Scheme used for passing token in HTTP requests (e.g., Bearer) + /// + public string Scheme { get; set; } + + /// + /// HTTP 请求中用于身份验证的 Token + /// Token used for authentication in HTTP requests + /// + public string Token { get; set; } + + /// + /// Linux 平台下的脚本，用于在更新完成后为文件分配权限 + /// Script for Linux platform to assign permissions to files after update completion + /// + public string Script { get; set; } +} +``` + +### UpdateOption 枚举 | UpdateOption Enum + +```csharp +public enum UpdateOption +{ + /// + /// 更新包文件格式（默认为 Zip） + /// Update package file format (default is Zip) + /// + Format, + + /// + /// 压缩编码格式 + /// Compression encoding format + /// + Encoding, + + /// + /// 下载超时时间（秒）。如果不指定，默认超时时间为 30 秒 + /// Download timeout duration (seconds). Default is 30 seconds if not specified + /// + DownloadTimeOut, + + /// + /// 是否启用二进制差异更新功能，默认启用；设置为 false 则执行全量覆盖安装 + /// Whether to enable binary differential update function, enabled by default; + /// if set to false, full overwrite installation will be performed + /// + Patch, + + /// + /// 是否在更新前启用备份功能，默认启用；设置为 false 则不进行备份 + /// Whether to enable backup function before update, enabled by default; + /// if set to false, no backup will be performed + /// + BackUp +} +``` + +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：基本更新流程 | 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($"更新异常: {args.Exception.Message}"); + }) + .LaunchAsync(); +``` + +### 示例 2：带黑名单的更新 | 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(); +``` + +### 示例 3：自定义更新选项 | 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(); +``` + +### 示例 4：完整的事件监听 | 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}] 进度: {args.ProgressPercentage}% | " + + $"速度: {args.Speed} | 剩余: {args.Remaining}"); + }) + // 单个下载完成 | Single download completed + .AddListenerMultiDownloadCompleted((sender, args) => + { + var version = args.Version as VersionInfo; + if (args.IsComplated) + Console.WriteLine($"✓ 版本 {version.Version} 下载成功"); + else + Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); + }) + // 所有下载完成 | All downloads completed + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + Console.WriteLine("✓ 所有更新包下载完成，准备安装..."); + else + Console.WriteLine($"✗ 下载失败，共 {args.FailedVersions.Count} 个版本失败"); + }) + // 下载错误 | Download error + .AddListenerMultiDownloadError((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); + }) + // 异常处理 | Exception handling + .AddListenerException((sender, args) => + { + Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); + }) + .LaunchAsync(); +``` + +### 示例 5：自定义操作和跳过选项 | Example 5: Custom Operations and Skip Options + +```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) + // 添加自定义操作（更新前检查环境）| Add custom operation (check environment before update) + .AddCustomOption(async () => + { + Console.WriteLine("正在检查运行环境..."); + await Task.Delay(1000); + // 检查磁盘空间、依赖项等 | Check disk space, dependencies, etc. + Console.WriteLine("环境检查完成"); + }) + // 设置用户跳过选项 | Set user skip option + .SetCustomSkipOption(() => + { + Console.WriteLine("发现新版本，是否更新？(y/n)"); + var input = Console.ReadLine(); + return input?.ToLower() == "y"; + }) + .LaunchAsync(); +``` + +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **版本号格式 | Version Number Format** + - 版本号必须遵循语义化版本规范（如 1.0.0.0） + - 确保客户端和服务器端版本号格式一致 + - 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** + - 在 Windows 上可能需要管理员权限来替换文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + - 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. + +### 💡 最佳实践 | Best Practices + +- **备份策略**：始终启用 BackUp 选项，以便更新失败时可以回滚 +- **差异更新**：启用 Patch 选项以减少下载量和更新时间 +- **错误处理**：实现完整的异常监听和错误处理逻辑 +- **用户体验**：在更新前提示用户并允许选择更新时机 +- **测试验证**：在生产环境部署前充分测试更新流程 +- **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**: 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 | + +--- -### 🍵UpdateOption +## 相关资源 | Related Resources -| Enum | -| ------------------------------------------------------------ | -| **Format** File format of the update package. | -| **Encoding** Compression encoding. | -| **DownloadTimeOut** Timeout duration (in seconds). If not specified, the default timeout is 30 seconds. | -| **Patch** Whether to enable the binary differential update function, which is enabled by default; if set to `false`, a full overwrite installation will be performed instead. | -| **BackUp** Whether to enable the backup function before update, which is enabled by default; no backup will be performed if set to `false`. | - - - -### Applicable To - -| Product | Version | -| -------------- | ---------------- | -| .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) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [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 31d5db9..09ce675 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 @@ -2,77 +2,628 @@ sidebar_position: 5 --- -### Definition +# GeneralUpdate.Core -Namespace: GeneralUpdate.Core +## 组件概览 | Component Overview -Assembly: GeneralUpdate.Core.dll +**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一，提供了完整的升级执行能力。与 ClientCore 不同，Core 组件作为独立的升级助手程序运行，负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式，Core 接收来自 ClientCore 的更新指令，并安全地完成主程序的升级任务。 +**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. +**命名空间 | Namespace:** `GeneralUpdate.Core` +**程序集 | Assembly:** `GeneralUpdate.Core.dll` -GeneralUpdate.Core is one of the most essential components, providing a wide range of primary functionalities. Once the main program upgrade operation is completed, this component is invoked through process startup and parameter passing to complete the main program upgrade operation. (Main responsibility is updating the main program) - -```c# +```csharp public class GeneralUpdateBootstrap : AbstractBootstrap ``` +--- + +## 核心特性 | Core Features + +### 1. 文件替换与版本管理 | File Replacement and Version Management +- 安全的文件替换机制，避免文件占用问题 | Safe file replacement mechanism to avoid file locking issues +- 支持多版本增量升级 | Support multi-version incremental upgrades +- 自动处理文件依赖关系 | Automatic handling of file dependencies + +### 2. 驱动升级支持 | Driver Upgrade Support +- 可选的驱动程序升级功能 | Optional driver upgrade functionality +- 字段映射表配置 | Field mapping table configuration +- 安全的驱动安装流程 | Safe driver installation process + +### 3. 完整的事件通知 | Comprehensive Event Notifications +- 下载进度实时监控 | Real-time download progress monitoring +- 多版本下载管理 | Multi-version download management +- 异常和错误完整捕获 | Complete exception and error capture + +### 4. 跨平台支持 | Cross-Platform Support +- Windows、Linux、macOS 平台全支持 | Full support for Windows, Linux, macOS platforms +- 自动平台检测和策略适配 | Automatic platform detection and strategy adaptation + +![Multi Download](imgs/muti_donwload.png) + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Core： + +Install GeneralUpdate.Core via NuGet: + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 | Initialization and Usage + +以下示例展示了如何在升级助手程序中配置和启动升级流程： + +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 +{ + Console.WriteLine($"升级程序初始化，{DateTime.Now}！"); + Console.WriteLine("当前运行目录：" + Thread.GetDomain().BaseDirectory); + + // 启动升级流程 | Launch upgrade process + await new GeneralUpdateBootstrap() + // 监听下载统计信息 | 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) + // 启动异步升级 | Launch async upgrade + .LaunchAsync(); + + Console.WriteLine($"升级程序已启动，{DateTime.Now}！"); + await Task.Delay(2000); +} +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($"当前下载版本：{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 参考 | Core API Reference + +### GeneralUpdateBootstrap 类方法 | GeneralUpdateBootstrap Class Methods + +#### LaunchAsync 方法 | LaunchAsync Method + +异步启动升级流程。 + +Launch the upgrade process asynchronously. + +```csharp +public async Task LaunchAsync() +``` + +**返回值 | Return Value:** +- 返回当前 GeneralUpdateBootstrap 实例，支持链式调用 +- Returns the current GeneralUpdateBootstrap instance, supporting method chaining + +#### Option 方法 | Option Method + +设置升级选项。 + +Set upgrade options. + +```csharp +public GeneralUpdateBootstrap Option(UpdateOption option, object value) +``` + +**参数 | Parameters:** +- `option`: 升级选项枚举 | Upgrade option enum +- `value`: 选项值 | Option value + +**示例 | Example:** +```csharp +.Option(UpdateOption.Drive, true) // 启用驱动升级 | Enable driver upgrade +``` + +#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method + +监听下载统计信息（速度、进度、剩余时间等）。 + +Listen for download statistics (speed, progress, remaining time, etc.). + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( + Action callbackAction) +``` + +#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method + +监听单个更新包下载完成事件。 + +Listen for single update package download completion event. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method + +监听所有版本下载完成事件。 + +Listen for all version downloads completion event. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method + +监听每个版本下载错误事件。 + +Listen for download error events for each version. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadError( + Action callbackAction) +``` + +#### AddListenerException 方法 | AddListenerException Method + +监听升级组件内部所有异常。 + +Listen for all internal exceptions in the upgrade component. + +```csharp +public GeneralUpdateBootstrap AddListenerException( + Action callbackAction) +``` + +#### SetFieldMappings 方法 | SetFieldMappings Method + +设置字段映射表，用于解析驱动包信息。 + +Set field mapping table for parsing driver package information. + +```csharp +public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) +``` + +**参数 | Parameters:** +- `fieldMappings`: 字段映射字典，键为英文字段名，值为本地化字段名 +- Field mapping dictionary, key is English field name, value is localized field name + +--- + +## 配置类详解 | Configuration Class Details + +### UpdateOption 枚举 | UpdateOption Enum + +```csharp +public enum UpdateOption +{ + /// + /// 是否启用驱动升级功能 + /// Whether to enable driver upgrade functionality + /// + Drive +} +``` + +### Packet 类 | Packet Class + +升级包信息类，由 ClientCore 通过参数传递给 Core： + +Upgrade package information class, passed from ClientCore to Core via parameters: + +```csharp +public class Packet +{ + /// + /// 主更新检查 API 地址 + /// Main update check API address + /// + public string MainUpdateUrl { get; set; } + + /// + /// 应用类型：1=客户端应用，2=更新应用 + /// Application type: 1=ClientApp, 2=UpdateApp + /// + public int AppType { get; set; } + + /// + /// 更新检查 API 地址 + /// Update check API address + /// + public string UpdateUrl { get; set; } + + /// + /// 需要启动的应用程序名称 + /// Name of the application to be launched + /// + public string AppName { get; set; } + + /// + /// 主应用程序名称 + /// Main application name + /// + public string MainAppName { get; set; } + + /// + /// 更新包文件格式（默认为 Zip） + /// Update package file format (default is Zip) + /// + public string Format { get; set; } + + /// + /// 是否需要升级更新应用 + /// Indicates if the update application needs to be upgraded + /// + public bool IsUpgradeUpdate { get; set; } + + /// + /// 是否需要更新主应用 + /// Indicates if the main application needs to be updated + /// + public bool IsMainUpdate { get; set; } + + /// + /// 更新日志网页 URL + /// Update log webpage URL + /// + public string UpdateLogUrl { get; set; } + + /// + /// 需要更新的版本信息列表 + /// List of version information that needs updating + /// + public List UpdateVersions { get; set; } + + /// + /// 文件操作编码格式 + /// File operation encoding format + /// + public Encoding Encoding { get; set; } + + /// + /// 下载超时时间（秒） + /// Download timeout duration (seconds) + /// + public int DownloadTimeOut { get; set; } + + /// + /// 应用密钥，与服务器约定 + /// Application secret key, agreed upon with the server + /// + public string AppSecretKey { get; set; } + + /// + /// 当前客户端版本 + /// Current client version + /// + public string ClientVersion { get; set; } + + /// + /// 最新版本 + /// Latest version + /// + public string LastVersion { get; set; } + + /// + /// 安装路径（用于更新文件逻辑） + /// Installation path (used for update file logic) + /// + public string InstallPath { get; set; } + + /// + /// 下载文件的临时存储路径 + /// Temporary storage path for downloaded files + /// + public string TempPath { get; set; } + + /// + /// 升级终端程序的配置参数（Base64 编码） + /// Configuration parameters for the upgrade terminal program (Base64 encoded) + /// + public string ProcessBase64 { get; set; } + + /// + /// 当前策略所属平台（Windows/Linux/Mac） + /// Platform to which the current strategy belongs (Windows/Linux/Mac) + /// + public string Platform { get; set; } + + /// + /// 黑名单文件列表 + /// Files in the blacklist + /// + public List BlackFiles { get; set; } + + /// + /// 黑名单文件格式列表 + /// File formats in the blacklist + /// + public List BlackFormats { get; set; } + + /// + /// 是否启用驱动升级功能 + /// Indicates if the driver upgrade feature is enabled + /// + public bool DriveEnabled { get; set; } +} +``` + +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：基本升级流程 | Example 1: Basic Upgrade Process + +```csharp +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Internal; +using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + +try +{ + Console.WriteLine("升级程序初始化..."); + + // 启动升级流程 | Launch upgrade process + await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}] 下载进度: {args.ProgressPercentage}%"); + }) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); + + Console.WriteLine("升级完成！"); +} +catch (Exception e) +{ + Console.WriteLine($"升级失败: {e.Message}"); +} +``` + +### 示例 2：启用驱动升级 | Example 2: Enable Driver Upgrade +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Internal.Bootstrap; -### Example +// 中文字段映射表 | Chinese field mapping table +var fieldMappingsCN = new Dictionary +{ + { "DriverName", "驱动名称" }, + { "DriverVersion", "驱动版本" }, + { "DriverDescription", "驱动描述" }, + { "InstallPath", "安装路径" } +}; -GeneralUpdateBootstrap uses code examples [[View]](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs)。 +await new GeneralUpdateBootstrap() + // 设置字段映射表 | Set field mappings + .SetFieldMappings(fieldMappingsCN) + // 启用驱动更新 | Enable driver update + .Option(UpdateOption.Drive, true) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); +``` -![](imgs/muti_donwload.png) +### 示例 3：完整事件监听 | Example 3: Complete Event Listening +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; +await new GeneralUpdateBootstrap() + // 下载统计 | Download statistics + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}]"); + Console.WriteLine($" 速度: {args.Speed}"); + Console.WriteLine($" 进度: {args.ProgressPercentage}%"); + Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); + Console.WriteLine($" 剩余时间: {args.Remaining}"); + }) + // 单个下载完成 | Single download completed + .AddListenerMultiDownloadCompleted((sender, args) => + { + var version = args.Version as VersionInfo; + string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; + Console.WriteLine($"版本 {version.Version} 下载{status}"); + }) + // 所有下载完成 | All downloads completed + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + Console.WriteLine("✓ 所有版本下载完成，开始安装..."); + } + else + { + Console.WriteLine($"✗ 下载失败，{args.FailedVersions.Count} 个版本失败："); + foreach (var version in args.FailedVersions) + { + Console.WriteLine($" - {version}"); + } + } + }) + // 下载错误 | Download error + .AddListenerMultiDownloadError((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"✗ 版本 {version.Version} 错误:"); + Console.WriteLine($" {args.Exception.Message}"); + }) + // 异常处理 | Exception handling + .AddListenerException((sender, args) => + { + Console.WriteLine("⚠ 升级过程异常:"); + Console.WriteLine($" 错误: {args.Exception.Message}"); + Console.WriteLine($" 堆栈: {args.Exception.StackTrace}"); + }) + .LaunchAsync(); +``` -### Annotations +### 示例 4：自定义升级流程 | Example 4: Custom Upgrade Process -GeneralUpdateBootstrap provides the following capabilities. +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; -#### Constructors +// 记录升级开始时间 | Record upgrade start time +var startTime = DateTime.Now; +var downloadedVersions = new List(); -| Constructors | Description | -| ------------------------ | ------------------------------------------ | -| GeneralUpdateBootstrap() | Current GeneralUpdateBootstrap constructor | -| base:AbstractBootstrap() | Parent class AbstractBootstrap constructor | +await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadCompleted((sender, args) => + { + if (args.IsComplated) + { + var version = args.Version as VersionInfo; + downloadedVersions.Add(version.Version); + } + }) + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + var duration = DateTime.Now - startTime; + Console.WriteLine($"升级完成！"); + Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); + Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); + } + }) + .AddListenerException((sender, args) => + { + // 记录日志到文件 | Log to file + File.AppendAllText("upgrade_error.log", + $"[{DateTime.Now}] {args.Exception}\n"); + }) + .LaunchAsync(); +``` -#### Properties +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes -| Properties | Description | -| ------------ | ------------------------------------------ | -| Packet | Update package information | -| UpdateOption | Update operation configuration enumeration | +1. **进程隔离 | Process Isolation** + - Core 必须作为独立进程运行，不能在主程序中直接调用 + - 升级时主程序必须完全关闭，否则文件替换会失败 + - Core must run as an independent process, cannot be called directly in the main program + - The main program must be completely closed during upgrade, otherwise file replacement will fail -#### Methods +2. **参数传递 | Parameter Passing** + - ClientCore 通过 Base64 编码的参数传递配置给 Core + - 确保参数传递过程中不会被截断或损坏 + - ClientCore passes configuration to Core via Base64 encoded parameters + - Ensure parameters are not truncated or corrupted during passing -| Method | Description | -| -------------------------------------- | ---------------------------------------------------------- | -| LaunchTaskAsync() | Asynchronously launch update with Task | -| LaunchAsync() | Launch update | -| Option() | Set update configuration | -| GetOption() | Get update configuration | -| AddListenerMultiAllDownloadCompleted() | Listen for completion of all version downloads | -| AddListenerMultiDownloadCompleted() | Listen for completion of each version download | -| AddListenerMultiDownloadError() | Listen for download errors for each version | -| AddListenerMultiDownloadStatistics() | Listen for download statistics/progress for each version | -| AddListenerException() | Listen for all internal exceptions in the update component | +3. **文件权限 | File Permissions** + - 在 Windows 上可能需要管理员权限替换系统目录中的文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + - Administrator privileges may be required on Windows to replace files in system directories + - Appropriate file system permissions are required on Linux/macOS +4. **驱动升级 | Driver Upgrade** + - 驱动升级功能需要系统级权限 + - 建议在测试环境充分验证后再使用 + - Driver upgrade functionality requires system-level permissions + - Recommended to thoroughly validate in test environment before use +5. **回滚机制 | Rollback Mechanism** + - Core 不直接提供回滚功能，但保留了备份文件 + - 如需回滚，可使用 ClientCore 的备份功能 + - Core does not directly provide rollback functionality, but backup files are preserved + - For rollback, use ClientCore's backup functionality -### 🍵UpdateOption +### 💡 最佳实践 | Best Practices -**Enumeration** +- **日志记录**：实现完整的异常监听，记录升级过程中的所有问题 +- **超时设置**：根据网络环境合理设置下载超时时间 +- **进度反馈**：向用户显示升级进度，提升用户体验 +- **错误处理**：升级失败时提供清晰的错误信息和解决方案 +- **测试验证**：在各种网络条件下测试升级流程的稳定性 +- **Logging**: Implement complete exception listening to record all issues during the upgrade process +- **Timeout Settings**: Set download timeout appropriately based on network environment +- **Progress Feedback**: Display upgrade progress to users to improve user experience +- **Error Handling**: Provide clear error messages and solutions when upgrade fails +- **Testing**: Test upgrade process stability under various network conditions -**Drive** Whether to enable driver upgrade functionality. +--- + +## 适用平台 | Applicable Platforms +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +--- -### Applicable to +## 相关资源 | Related Resources -| Product | Versions | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **相关组件**：[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) 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 b7f8576..7bf5a80 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 @@ -2,100 +2,474 @@ sidebar_position: 6 --- -### Definition +# GeneralUpdate.Differential -Namespace: GeneralUpdate.Differential +## 组件概览 | Component Overview -Assembly: GeneralUpdate.Core.dll +**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法，可以精确识别两个版本之间的文件变化，生成高效的增量补丁包，并支持补丁还原操作。通过使用差异更新，可以显著减少更新包的大小和下载时间，特别适合频繁发布更新的应用场景。 +**GeneralUpdate.Differential** is the core component responsible for binary differential updates in the GeneralUpdate framework. This component provides powerful differential algorithms that can accurately identify file changes between two versions, generate efficient incremental patch packages, and support patch restoration operations. By using differential updates, you can significantly reduce update package size and download time, making it particularly suitable for scenarios with frequent update releases. +**命名空间 | Namespace:** `GeneralUpdate.Differential` +**程序集 | Assembly:** `GeneralUpdate.Core.dll` -This component provides capabilities for generating binary differential patch files (algorithm), file increment identification (version differences), deleted file identification (version differences), blacklisting, patch restoration, and more. - -```c# +```csharp public sealed class DifferentialCore ``` +--- +## 核心特性 | Core Features -### Example +### 1. 增量识别 | Incremental Identification +- 精确识别新增、修改、删除的文件 | Accurately identify added, modified, and deleted files +- 智能文件版本对比 | Intelligent file version comparison +- 支持跳过指定文件和格式 | Support skipping specified files and formats -The following example defines methods for increment identification, generating binary patches, patch restoration, and setting blacklists. The packaging tool in the GeneralUpdate.Tools project also strongly depends on this component. +### 2. 二进制补丁生成 | Binary Patch Generation +- 高效的二进制差异算法 | Efficient binary differential algorithm +- 最小化补丁文件大小 | Minimize patch file size +- 快速补丁生成速度 | Fast patch generation speed -```c# -// Increment identification, generating binary patches -public async Task TestDifferentialClean() -{ - // Path to the previous version's client folder - var path1 = "D:\\packet\\source"; - // Path to the latest version's client folder - var path2 = "D:\\packet\\target"; - // Path for generating patch files - var path3 = "D:\\packet\\patchs"; - await DifferentialCore.Instance.Clean(path1, path2, path3); -} +### 3. 补丁还原 | Patch Restoration +- 安全的补丁应用流程 | Safe patch application process +- 自动处理文件依赖关系 | Automatic handling of file dependencies +- 完整性验证机制 | Integrity verification mechanism -// Patch restoration -public async Task TestDifferentialDirty() -{ - // Path to the current version's client folder - var path1 = "D:\\packet\\source"; - // Path for generating patch files - var path2 = "D:\\packet\\patchs"; - await DifferentialCore.Instance.Dirty(path1, path2); -} +### 4. 黑名单支持 | Blacklist Support +- 文件级黑名单 | File-level blacklist +- 格式级黑名单 | Format-level blacklist +- 灵活的过滤规则 | Flexible filtering rules + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Differential（包含在 Core 包中）： + +Install GeneralUpdate.Differential via NuGet (included in Core package): + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 | Initialization and Usage + +以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作： + +The following example demonstrates how to use DifferentialCore for incremental identification and patch operations: + +```csharp +using GeneralUpdate.Differential; + +// 增量识别并生成二进制补丁 | Identify increments and generate binary patches +var sourcePath = @"D:\packet\app"; // 旧版本路径 | Old version path +var targetPath = @"D:\packet\release"; // 新版本路径 | New version path +var patchPath = @"D:\packet\patch"; // 补丁输出路径 | Patch output path + +await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); + +// 应用补丁（还原） | Apply patches (restoration) +await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); +``` + +--- + +## 核心 API 参考 | Core API Reference + +### DifferentialCore 类 | DifferentialCore Class + +#### Instance 属性 | Instance Property + +获取 DifferentialCore 的单例实例。 + +Get the singleton instance of DifferentialCore. + +```csharp +public static DifferentialCore Instance { get; } +``` + +#### Clean 方法 | Clean Method + +执行增量识别、删除文件识别，并生成二进制补丁文件。 + +Perform incremental identification, deleted file identification, and generate binary patch files. + +**方法签名 | Method Signature:** + +```csharp +public async Task Clean(string sourcePath, string targetPath, string patchPath = null) ``` -### Annotations +**参数 | Parameters:** +- `sourcePath`: 旧版本文件夹路径 | Path to the old version folder +- `targetPath`: 新版本文件夹路径 | Path to the new version folder +- `patchPath`: 补丁文件输出目录（可选）| Directory to store discovered incremental update files (optional) + +**功能说明 | Function Description:** +1. 对比 sourcePath 和 targetPath 两个目录 +2. 识别新增、修改、删除的文件 +3. 为修改的文件生成二进制差异补丁 +4. 将补丁和新增文件保存到 patchPath + +**示例 | Example:** +```csharp +// 生成从 v1.0.0 到 v1.1.0 的补丁包 +var source = @"D:\MyApp\v1.0.0"; +var target = @"D:\MyApp\v1.1.0"; +var patch = @"D:\MyApp\patches\v1.1.0"; + +await DifferentialCore.Instance.Clean(source, target, patch); +// 结果：patch 目录包含所有必要的增量更新文件 +``` -DifferentialCore provides capabilities for increment identification, generating binary patches, patch restoration, and setting blacklists. +#### Dirty 方法 | Dirty Method -#### Methods +应用补丁，将旧版本文件更新到新版本。 -| Name | Type | Description | -| ------- | ------ | ------------------------------------------------------------ | -| Clean() | Method | Increment identification, deleted file identification, and generating binary patch files | -| Dirty() | Method | Patch restoration (applying patches to old client files to achieve updates) | +Apply patches to update old version files to the new version. -### 🌼Clean() +**方法签名 | Method Signature:** -**Method** +```csharp +public async Task Dirty(string appPath, string patchPath) +``` -Generate patch files [cannot include files with the same name but different extensions]. +**参数 | Parameters:** +- `appPath`: 客户端应用程序目录（当前版本）| Client application directory (current version) +- `patchPath`: 补丁文件路径 | Path to the patch files -```c# -public async Task Clean(string sourcePath, string targetPath, string patchPath = null); +**功能说明 | Function Description:** +1. 读取 patchPath 中的补丁文件 +2. 将补丁应用到 appPath 中的对应文件 +3. 处理新增文件的复制 +4. 处理删除文件的移除 + +**示例 | Example:** +```csharp +// 将补丁应用到当前应用程序 +var appDir = AppDomain.CurrentDomain.BaseDirectory; +var patchDir = Path.Combine(appDir, "temp", "patches"); + +await DifferentialCore.Instance.Dirty(appDir, patchDir); +// 结果：应用程序更新到新版本 ``` -**Parameters** +--- -**sourcePath** Path to the previous version's folder. +## 实际使用示例 | Practical Usage Examples -**targetPath** Path to the latest version's folder. +### 示例 1：基本补丁生成 | Example 1: Basic Patch Generation -**patchPath** Directory to store the discovered incremental update files temporarily. +```csharp +using GeneralUpdate.Differential; -### 🌼Dirty() +public async Task GeneratePatchAsync() +{ + try + { + // 版本路径 | Version paths + var oldVersion = @"D:\MyApp\1.0.0"; + var newVersion = @"D:\MyApp\1.0.1"; + var patchOutput = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始生成补丁..."); + + // 生成补丁 | Generate patches + await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); + + Console.WriteLine($"补丁生成完成！输出目录：{patchOutput}"); + + // 显示补丁信息 | Display patch information + var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); + Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); + + long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); + Console.WriteLine($"总补丁大小：{totalSize / 1024.0:F2} KB"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁生成失败：{ex.Message}"); + } +} +``` -**Method** +### 示例 2：应用补丁 | Example 2: Apply Patches -Apply patches [cannot include files with the same name but different extensions]. +```csharp +using GeneralUpdate.Differential; -```c# -public async Task Dirty(string appPath, string patchPath); +public async Task ApplyPatchAsync() +{ + try + { + // 应用程序目录 | Application directory + var appDirectory = @"D:\MyApp\current"; + // 补丁目录 | Patch directory + var patchDirectory = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始应用补丁..."); + + // 验证补丁存在 | Verify patch exists + if (!Directory.Exists(patchDirectory)) + { + throw new DirectoryNotFoundException($"补丁目录不存在：{patchDirectory}"); + } + + // 应用补丁 | Apply patches + await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); + + Console.WriteLine("补丁应用成功！应用程序已更新到新版本。"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁应用失败：{ex.Message}"); + } +} ``` -**Parameters** +### 示例 3：完整的补丁流程 | Example 3: Complete Patch Workflow -**appPath** Client application directory. +```csharp +using GeneralUpdate.Differential; +using System.IO.Compression; -**patchPath** Path to the patch files. +public class PatchManager +{ + // 生成并打包补丁 | Generate and package patches + public async Task CreatePatchPackageAsync( + string oldVersionPath, + string newVersionPath, + string outputPath) + { + try + { + // 1. 生成补丁文件 | Generate patch files + var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempPatchDir); + + Console.WriteLine($"正在生成补丁..."); + await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); + + // 2. 压缩补丁文件 | Compress patch files + var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); + Console.WriteLine($"正在打包补丁..."); + + if (File.Exists(patchZipPath)) + File.Delete(patchZipPath); + + ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, + CompressionLevel.Optimal, false); + + // 3. 清理临时文件 | Clean up temp files + Directory.Delete(tempPatchDir, true); + + var patchSize = new FileInfo(patchZipPath).Length; + Console.WriteLine($"补丁包创建成功：{patchZipPath}"); + Console.WriteLine($"补丁包大小：{patchSize / 1024.0:F2} KB"); + + return patchZipPath; + } + catch (Exception ex) + { + Console.WriteLine($"创建补丁包失败：{ex.Message}"); + throw; + } + } + + // 解压并应用补丁 | Extract and apply patches + public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) + { + try + { + // 1. 解压补丁包 | Extract patch package + var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempExtractDir); + + Console.WriteLine($"正在解压补丁包..."); + ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); + + // 2. 应用补丁 | Apply patches + Console.WriteLine($"正在应用补丁..."); + await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); + + // 3. 清理临时文件 | Clean up temp files + Directory.Delete(tempExtractDir, true); + + Console.WriteLine($"补丁应用成功！"); + } + catch (Exception ex) + { + Console.WriteLine($"应用补丁包失败：{ex.Message}"); + throw; + } + } +} + +// 使用示例 | Usage example +var manager = new PatchManager(); + +// 创建补丁包 | Create patch package +var patchZip = await manager.CreatePatchPackageAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\releases" +); + +// 应用补丁包 | Apply patch package +await manager.ApplyPatchPackageAsync( + @"D:\MyApp\current", + patchZip +); +``` + +### 示例 4：带进度显示的补丁操作 | Example 4: Patch Operations with Progress Display + +```csharp +using GeneralUpdate.Differential; + +public class ProgressivePatchManager +{ + public async Task GeneratePatchWithProgressAsync( + string sourcePath, + string targetPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始扫描文件差异..."); + + // 在实际场景中，可以在 Clean 前后添加进度报告 + await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); + + progress?.Report("补丁生成完成！"); + + // 统计信息 | Statistics + var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); + progress?.Report($"共生成 {files.Length} 个补丁文件"); + } + catch (Exception ex) + { + progress?.Report($"错误：{ex.Message}"); + throw; + } + } + + public async Task ApplyPatchWithProgressAsync( + string appPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始应用补丁..."); + + await DifferentialCore.Instance.Dirty(appPath, patchPath); + + progress?.Report("补丁应用成功！"); + } + catch (Exception ex) + { + progress?.Report($"错误：{ex.Message}"); + throw; + } + } +} + +// 使用示例 | Usage example +var manager = new ProgressivePatchManager(); +var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); + +await manager.GeneratePatchWithProgressAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\patches\1.0.1", + progress +); +``` +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **文件名限制 | File Name Restrictions** + - 不能包含同名但扩展名不同的文件（如 file.txt 和 file.log） + - 建议使用唯一的文件名命名规则 + - Cannot include files with the same name but different extensions (e.g., file.txt and file.log) + - Recommended to use unique file naming conventions + +2. **目录结构 | Directory Structure** + - 源目录和目标目录的相对结构应保持一致 + - 补丁生成时会保留目录层次关系 + - The relative structure of source and target directories should remain consistent + - Directory hierarchy is preserved during patch generation + +3. **磁盘空间 | Disk Space** + - 确保有足够的磁盘空间存储补丁文件 + - 二进制差异补丁通常比完整文件小，但仍需要临时空间 + - Ensure sufficient disk space for storing patch files + - Binary differential patches are usually smaller than complete files, but still require temporary space + +4. **文件占用 | File Locking** + - 应用补丁时，确保目标文件没有被其他进程占用 + - 建议在应用程序关闭后应用补丁 + - When applying patches, ensure target files are not locked by other processes + - Recommended to apply patches after the application is closed + +5. **备份建议 | Backup Recommendations** + - 在应用补丁前建议备份原始文件 + - 可以使用 ClientCore 的 BackUp 选项自动备份 + - Recommended to backup original files before applying patches + - Can use ClientCore's BackUp option for automatic backup + +### 💡 最佳实践 | Best Practices + +- **版本管理**：为每个版本维护独立的补丁包，便于版本追踪和回滚 +- **补丁验证**：生成补丁后进行验证测试，确保补丁可以正确应用 +- **增量更新**：优先使用差异更新而非全量更新，可节省 50%-90% 的下载量 +- **错误处理**：实现完整的异常捕获和错误恢复机制 +- **性能优化**：对于大文件，差异算法的性能优势更加明显 +- **Version Management**: Maintain separate patch packages for each version for easier version tracking and rollback +- **Patch Validation**: Perform validation testing after generating patches to ensure they can be applied correctly +- **Incremental Updates**: Prioritize differential updates over full updates, which can save 50%-90% of download size +- **Error Handling**: Implement complete exception capture and error recovery mechanisms +- **Performance Optimization**: For large files, the performance advantage of the differential algorithm is more pronounced + +### 🔍 工作原理 | How It Works + +**Clean 方法工作流程 | Clean Method Workflow:** +1. 扫描源目录和目标目录中的所有文件 +2. 比较文件的MD5哈希值以识别变化 +3. 对于修改的文件，使用二进制差异算法生成补丁 +4. 对于新增文件，直接复制到补丁目录 +5. 记录删除的文件列表 + +**Dirty 方法工作流程 | Dirty Method Workflow:** +1. 读取补丁目录中的所有文件 +2. 对于补丁文件，应用到对应的原文件上 +3. 对于新增文件，直接复制到应用目录 +4. 根据删除列表移除相应文件 +5. 验证更新完整性 + +--- + +## 适用平台 | Applicable Platforms + +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | + +--- -### Applicable to +## 相关资源 | Related Resources -| Product | Versions | -| -------------- | ------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **打包工具**：GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 | The GeneralUpdate.PacketTool project depends on this component for differential packaging From 6d504ea958af8b906ce3ebe53487dda19cc3e819 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:28:09 +0000 Subject: [PATCH 4/7] Complete bilingual documentation for all four core components Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com> --- .../current/doc/GeneralUpdate.Bowl.md | 417 ++++++---- .../current/doc/GeneralUpdate.ClientCore.md | 730 +++++++++++++++--- .../current/doc/GeneralUpdate.Core.md | 640 ++++++++++++++- .../current/doc/GeneralUpdate.Differential.md | 486 ++++++++++-- 4 files changed, 1922 insertions(+), 351 deletions(-) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md index 38885be..5af0825 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md @@ -2,67 +2,237 @@ sidebar_position: 3 --- -### 定义 +# GeneralUpdate.Bowl -命名空间：GeneralUpdate.Bowl +## 组件概览 | Component Overview -程序集：GeneralUpdate.Bowl.dll +**GeneralUpdate.Bowl** 是一个独立的进程监控组件，在升级流程结束前启动，负责启动主客户端应用程序并监控其运行状态。该组件提供了完整的崩溃监控和诊断能力，当被监控的应用程序发生异常时，会自动导出Dump文件、驱动信息、系统信息和事件日志，帮助开发者快速定位问题。 +**GeneralUpdate.Bowl** is an independent process monitoring component that launches before the end of the upgrade process. It is responsible for starting the main client application and monitoring its running status. This component provides comprehensive crash monitoring and diagnostic capabilities. When the monitored application encounters an exception, it automatically exports Dump files, driver information, system information, and event logs to help developers quickly locate issues. +**命名空间 | Namespace:** `GeneralUpdate.Bowl` +**程序集 | Assembly:** `GeneralUpdate.Bowl.dll` -该组件在升级流程结束之前启动的一个独立进程，它在流程结束之前去启动主客户端应用程序并监控是否正常运行。 - -```c# +```csharp public sealed class Bowl ``` +--- + +## 核心特性 | Core Features + +### 1. 进程监控 | Process Monitoring +- 实时监控目标应用程序的运行状态 | Real-time monitoring of target application status +- 自动检测进程崩溃和异常退出 | Automatic detection of process crashes and abnormal exits + +### 2. 崩溃诊断 | Crash Diagnostics +- 自动生成Dump文件（.dmp）用于崩溃分析 | Automatic generation of Dump files (.dmp) for crash analysis +- 导出详细的系统和驱动信息 | Export detailed system and driver information +- 收集Windows系统事件日志 | Collect Windows system event logs + +### 3. 版本化管理 | Version Management +- 按版本号分类存储故障信息 | Store failure information categorized by version number +- 支持升级和正常两种工作模式 | Support both upgrade and normal working modes + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Bowl： + +Install GeneralUpdate.Bowl via NuGet: + +```bash +dotnet add package GeneralUpdate.Bowl +``` + +### 初始化与使用 | Initialization and Usage +以下示例展示了如何使用 Bowl 组件监控应用程序： -### 示例 +The following example demonstrates how to use the Bowl component to monitor an application: -以下示例定义方法，包含Bowl使用。 +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; -```c# var installPath = AppDomain.CurrentDomain.BaseDirectory; var lastVersion = "1.0.0.3"; var processInfo = new MonitorParameter { - ProcessNameOrId = "JsonTest.exe", + ProcessNameOrId = "YourApp.exe", DumpFileName = $"{lastVersion}_fail.dmp", FailFileName = $"{lastVersion}_fail.json", TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", lastVersion), BackupDirectory = Path.Combine(installPath, lastVersion), - WorkModel = "Normal" + WorkModel = "Normal" // 使用 Normal 模式独立监控 | Use Normal mode for standalone monitoring }; Bowl.Launch(processInfo); ``` +--- + +## 核心 API 参考 | Core API Reference + +### Launch 方法 | Launch Method + +启动进程监控功能。 +Start the process monitoring functionality. + +**方法签名 | Method Signature:** + +```csharp +public static void Launch(MonitorParameter? monitorParameter = null) +``` -### 捕获 +**参数 | Parameters:** -如果监控到崩溃闪退将会在运行目录下生成： +#### MonitorParameter 类 | MonitorParameter Class -- 📒Dump文件（1.0.0.*_fail.dmp） -- 📒升级包版本信息（1.0.0.*_fail.json） -- 📒驱动信息（driverInfo.txt） -- 📒操作系统信息/硬件信息（systeminfo.txt） -- 📒系统事件日志（systemlog.evtx） +```csharp +public class MonitorParameter +{ + /// + /// 被监控的目录 + /// Directory being monitored + /// + public string TargetPath { get; set; } + + /// + /// 导出异常信息的目录 + /// Directory where captured exception information is exported + /// + public string FailDirectory { get; set; } + + /// + /// 备份目录 + /// Backup directory + /// + public string BackupDirectory { get; set; } + + /// + /// 被监控进程的名称或ID + /// Name or ID of the process being monitored + /// + public string ProcessNameOrId { get; set; } + + /// + /// Dump 文件名 + /// Dump file name + /// + public string DumpFileName { get; set; } + + /// + /// 升级包版本信息（.json）文件名 + /// Upgrade package version information (.json) file name + /// + public string FailFileName { get; set; } -导出到“fail”目录下并根据版本号区分文件夹。 + /// + /// 工作模式： + /// - Upgrade: 升级模式，主要用于与 GeneralUpdate 配合使用，内部逻辑处理，默认模式启动时请勿随意修改 + /// - Normal: 正常模式，可独立使用监控单个程序，程序崩溃时导出崩溃信息 + /// + /// Work Mode: + /// - Upgrade: Upgrade mode, primarily used in conjunction with GeneralUpdate for internal logic handling. + /// Do not modify arbitrarily when the default mode is activated. + /// - Normal: Normal mode, can be used independently to monitor a single program. + /// Exports crash information when the program crashes. + /// + public string WorkModel { get; set; } = "Upgrade"; +} +``` -![](imgs\crash.jpg) +--- +## 实际使用示例 | Practical Usage Examples +### 示例 1：独立模式监控应用 | Example 1: Standalone Mode Application Monitoring -#### (1)x.0.0.*_fail.dmp +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; -![](imgs\dump.png) +// 配置监控参数 | Configure monitoring parameters +var installPath = AppDomain.CurrentDomain.BaseDirectory; +var currentVersion = "1.0.0.5"; +var monitorConfig = new MonitorParameter +{ + ProcessNameOrId = "MyApplication.exe", + DumpFileName = $"{currentVersion}_crash.dmp", + FailFileName = $"{currentVersion}_crash.json", + TargetPath = installPath, + FailDirectory = Path.Combine(installPath, "crash_reports", currentVersion), + BackupDirectory = Path.Combine(installPath, "backups", currentVersion), + WorkModel = "Normal" // 独立监控模式 | Standalone monitoring mode +}; +// 启动监控 | Start monitoring +Bowl.Launch(monitorConfig); +``` -#### (2)x.0.0.*_fail.json +### 示例 2：结合 GeneralUpdate 使用 | Example 2: Use with GeneralUpdate + +```csharp +using GeneralUpdate.Bowl; +using GeneralUpdate.Bowl.Strategys; + +// 在升级完成后启动 Bowl 监控 | Start Bowl monitoring after upgrade completion +var installPath = AppDomain.CurrentDomain.BaseDirectory; +var upgradedVersion = "2.0.0.1"; + +var upgradeMonitor = new MonitorParameter +{ + ProcessNameOrId = "UpdatedApp.exe", + DumpFileName = $"{upgradedVersion}_fail.dmp", + FailFileName = $"{upgradedVersion}_fail.json", + TargetPath = installPath, + FailDirectory = Path.Combine(installPath, "fail", upgradedVersion), + BackupDirectory = Path.Combine(installPath, upgradedVersion), + WorkModel = "Upgrade" // 升级模式 | Upgrade mode +}; + +Bowl.Launch(upgradeMonitor); +``` + +--- + +## 崩溃信息捕获 | Crash Information Capture + +当检测到崩溃时，以下文件将在运行目录中生成： + +When a crash is detected, the following files will be generated in the running directory: + +- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) | **Dump file** (`x.0.0.*_fail.dmp`) +- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) | **Upgrade package version information** (`x.0.0.*_fail.json`) +- 📒 **驱动信息** (`driverInfo.txt`) | **Driver information** (`driverInfo.txt`) +- 📒 **操作系统/硬件信息** (`systeminfo.txt`) | **Operating system/hardware information** (`systeminfo.txt`) +- 📒 **系统事件日志** (`systemlog.evtx`) | **System event log** (`systemlog.evtx`) + +这些文件将按版本号分类导出到 "fail" 目录中。 + +These files will be exported to the "fail" directory, categorized by version number. + +![Crash Files](imgs/crash.jpg) + +### 1. Dump 文件 | Dump File + +Dump 文件包含崩溃时刻的内存快照，可用于调试分析： + +The Dump file contains a memory snapshot at the moment of crash, which can be used for debugging analysis: + +![Dump File](imgs/dump.png) + +### 2. 版本信息文件 | Version Information File + +JSON 格式的详细崩溃报告，包含参数配置和 ProcDump 输出： + +Detailed crash report in JSON format, including parameter configuration and ProcDump output: ```json { @@ -104,163 +274,100 @@ Bowl.Launch(processInfo); } ``` +### 3. 驱动信息文件 | Driver Information File +包含系统中所有驱动程序的详细信息： -#### (3)driverInfo.txt +Contains detailed information about all drivers in the system: -```json - -模块名 显示名称 描述 驱动程序类型 启动模式 状态 状态 接受停止 接受暂停 分页缓冲池 代码(字节) BSS(字 链接日期 路径 Init(字节) -============ ====================== ====================== ============= ========== ========== ========== =========== ============ ========== ========== ======= ====================== ================================================ ========== -360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK TRUE FALSE 4,096 36,864 0 9/29/2022 3:45:03 PM C:\Windows\system32\Drivers\360AntiAttack64.sys 4,096 -360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK TRUE FALSE 4,096 139,264 0 11/27/2023 3:43:37 PM C:\Windows\system32\Drivers\360AntiHacker64.sys 8,192 -360AntiHijac 360Safe Anti Hijack Se 360Safe Anti Hijack Se Kernel System Running OK TRUE FALSE 4,096 73,728 0 5/8/2024 12:19:52 PM C:\Windows\system32\Drivers\360AntiHijack64.sys 4,096 -360AntiSteal 360Safe Anti Steal Fil 360Safe Anti Steal Fil Kernel System Running OK TRUE FALSE 4,096 20,480 0 4/18/2024 3:58:04 PM C:\Windows\system32\Drivers\360AntiSteal64.sys 8,192 -360Box64 360Box mini-filter dri 360Box mini-filter dri File System System Running OK TRUE FALSE 0 225,280 0 8/7/2024 11:50:19 AM C:\Windows\system32\DRIVERS\360Box64.sys 12,288 - -//... +```text +Module Name Display Name Description Driver Type Start Mode State Status +============ ====================== ====================== ============= ========== ========== ========== +360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK +360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK +// ...更多驱动信息 | ...more driver information ``` +### 4. 系统信息文件 | System Information File +完整的操作系统和硬件配置信息： -#### (4)systeminfo.txt +Complete operating system and hardware configuration information: -```json - -主机名: **** -OS 名称: Microsoft Windows 11 专业版 -OS 版本: 10.0.2*** Build 22*** -OS 制造商: Microsoft Corporation -OS 配置: 独立工作站 -OS 构建类型: Multiprocessor Free -注册的所有人: ****@outlook.com -注册的组织: -产品 ID: ****-80000-***00-A**** -初始安装日期: 11/16/2023, 9:56:28 PM -系统启动时间: 11/26/2024, 9:37:51 PM -系统制造商: ASUS -系统型号: System Product Name -系统类型: x64-based PC -处理器: 安装了 1 个处理器。 - [01]: Intel** Family * Model *** Stepping * GenuineIntel ~**** Mhz -BIOS 版本: American Megatrends Inc. 1402, 4/1/2022 -Windows 目录: C:\Windows -系统目录: C:\Windows\system32 -启动设备: \Device\Ha*****olume1 -系统区域设置: zh-cn;中文(中国) -输入法区域设置: zh-cn;中文(中国) -时区: (UTC+08:00) **，**，*******，**** -物理内存总量: 16,194 MB -可用的物理内存: 1,795 MB -虚拟内存: 最大值: 25,410 MB -虚拟内存: 可用: 9,438 MB -虚拟内存: 使用中: 15,972 MB -页面文件位置: D:\****file.sys -域: WORKGROUP -登录服务器: \\**** -修补程序: 安装了 6 个修补程序。 - [01]: KB504**** - [02]: KB502**** - [03]: KB503**** - [04]: KB503**** - [05]: KB504**** - [06]: KB504**** -网卡: 安装了 3 个 NIC。 - [01]: Intel(R) Ethernet Connection (**) I***-V - 连接名: 以太网 - 启用 DHCP: 是 - DHCP 服务器: 192.168.**.** - IP 地址 - [01]: 192.168.**.** - [02]: ***::2640:***:****:**** - [02]: VMware Virtual Ethernet Adapter for VMnet1 - 连接名: VMware Network Adapter VMnet1 - 启用 DHCP: 是 - DHCP 服务器: 192.168.**.** - IP 地址 - [01]: 192.168.**.** - [02]: ***::9b3:***,***:**** - [03]: VMware Virtual Ethernet Adapter for VMnet8 - 连接名: VMware Network Adapter VMnet8 - 启用 DHCP: 是 - DHCP 服务器: 192.168.**.** - IP 地址 - [01]: 192.***,***:**** - [02]: fe80::***:***:***:**** -Hyper-V 要求: 已检测到虚拟机监控程序。将不显示 Hyper-V 所需的功能。 - -//... +```text +Host Name: **** +OS Name: Microsoft Windows 11 Pro +OS Version: 10.0.*** Build 22*** +System Manufacturer: ASUS +System Model: System Product Name +Processor(s): Intel** Family * Model *** +Total Physical Memory: 16,194 MB +// ...更多系统信息 | ...more system information ``` +### 5. 系统事件日志 | System Event Log +Windows 事件查看器格式的系统日志（.evtx 文件）： -#### (5)systemlog.evtx - -![](imgs\evtx.png) - - - -### 注解 - -Bowl提供运行监控功能，并导出相关错误信息 。 +System log in Windows Event Viewer format (.evtx file): +![System Event Log](imgs/evtx.png) +--- -#### 方法 +## 注意事项与警告 | Notes and Warnings -| Method | | -| -------- | -------- | -| Launch() | 启动监控 | +### ⚠️ 重要提示 | Important Notes +1. **工作模式选择 | Work Mode Selection** + - `Upgrade` 模式：专门用于与 GeneralUpdate 框架集成，包含内部逻辑处理 + - `Normal` 模式：可独立使用，适合监控任何 .NET 应用程序 + - `Upgrade` mode: Specifically for integration with GeneralUpdate framework, includes internal logic processing + - `Normal` mode: Can be used independently, suitable for monitoring any .NET application +2. **权限要求 | Permission Requirements** + - Bowl 需要足够的权限来生成 Dump 文件和读取系统信息 + - 建议以管理员权限运行需要监控的应用程序 + - Bowl requires sufficient permissions to generate Dump files and read system information + - It is recommended to run the monitored application with administrator privileges -### 🌼Launch() +3. **磁盘空间 | Disk Space** + - Dump 文件可能占用大量磁盘空间（通常 50-200 MB） + - 确保 FailDirectory 所在磁盘有足够的可用空间 + - Dump files may consume significant disk space (typically 50-200 MB) + - Ensure sufficient available space on the disk where FailDirectory is located -**启动函数** +4. **依赖项 | Dependencies** + - Bowl 使用 ProcDump 工具生成 Dump 文件，该工具已内置在组件中 + - 无需额外安装依赖项 + - Bowl uses the ProcDump tool to generate Dump files, which is built into the component + - No additional dependencies need to be installed -```c# -Launch(MonitorParameter? monitorParameter = null); -``` +### 💡 最佳实践 | Best Practices -**参数** +- **版本号管理**：为每个版本使用独立的故障目录，便于问题追踪 +- **日志清理**：定期清理旧版本的故障信息，避免磁盘空间耗尽 +- **测试验证**：在生产环境部署前，在测试环境验证监控功能 +- **Version Management**: Use separate failure directories for each version for easier issue tracking +- **Log Cleanup**: Regularly clean up failure information from old versions to avoid disk space exhaustion +- **Testing**: Verify monitoring functionality in a test environment before production deployment -```c# -public class MonitorParameter -{ - //被监控的目录 - public string TargetPath { get; set; } - - //捕获的异常信息导出到的目录 - public string FailDirectory { get; set; } - - //备份目录 - public string BackupDirectory { get; set; } - - //监控进程名称或者进程id - public string ProcessNameOrId { get; set; } - - //dump文件名 - public string DumpFileName { get; set; } - - //升级包版本信息（.json）文件名 - public string FailFileName { get; set; } +--- - /// - /// Upgrade: upgrade mode. This mode is primarily used in conjunction with GeneralUpdate for internal use. Please do not modify it arbitrarily when the default mode is activated. - /// Normal: Normal mode,This mode can be used independently to monitor a single program. If the program crashes, it will export the crash information. - /// - public string WorkModel { get; set; } = "Upgrade"; -} -``` +## 适用平台 | Applicable Platforms +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +| ASP.NET | Any | +--- -### 适用于 +## 相关资源 | Related Resources -| 产品 | 版本 | -| -------------- | ------------- | -| .NET | 5、6、7、8、9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | -| ASP.NET | Any | \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) +- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) | [Watch Bilibili Tutorial](https://www.bilibili.com/video/BV1c8iyYZE7P) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) \ No newline at end of file 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 index 320e848..005337f 100644 --- 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 @@ -2,130 +2,670 @@ sidebar_position: 4 --- -### 定义 +# GeneralUpdate.ClientCore -命名空间：GeneralUpdate.ClientCore +## 组件概览 | Component Overview -程序集：GeneralUpdate.ClientCore.dll +**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一，提供了丰富的客户端更新功能。该组件运行在主应用程序中，负责检查更新、下载更新包、验证完整性，并在完成后启动升级助手（GeneralUpdate.Core）来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新，而不影响当前运行状态。 +**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` -GeneralUpdate.ClientCore是最核心的组件之一，提供了大量主要功能。本质和Core没有区别，但是有职责上的区别ClientCore用于主程序中，更新升级助手然后关闭主程序启动升级助手。 - -```c# +```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 + +### 3. 完整的事件通知 | Comprehensive Event Notifications +- 下载进度、完成、错误事件 | Download progress, completion, and error events +- 支持用户自定义跳过更新选项 | Support user-defined skip update options +- 异常和错误全程监控 | Exception and error monitoring throughout the process + +### 4. 多平台支持 | Multi-Platform Support +- Windows、Linux、macOS 平台支持 | Windows, Linux, macOS platform support +- 自动平台检测和策略选择 | Automatic platform detection and strategy selection + +![Multi Download](imgs/muti_donwload.png) + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.ClientCore： + +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($"主程序初始化，{DateTime.Now}！"); + + // 配置更新参数 | Configure update parameters + var configinfo = new Configinfo + { + // 更新验证 API 地址 | Update verification API address + UpdateUrl = "http://127.0.0.1:5000/Upgrade/Verification", + // 更新报告 API 地址 | 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, + // 产品 ID（用于多产品分支管理）| 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($"主程序已启动，{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($"下载版本：{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 参考 | Core API Reference + +### GeneralClientBootstrap 类方法 | GeneralClientBootstrap Class Methods + +#### LaunchAsync 方法 | LaunchAsync Method + +异步启动更新流程。 + +Launch the update process asynchronously. + +```csharp +public async Task LaunchAsync() +``` + +#### SetConfig 方法 | SetConfig Method + +设置更新配置信息。 + +Set update configuration information. + +```csharp +public GeneralClientBootstrap SetConfig(Configinfo configinfo) +``` + +#### Option 方法 | Option Method + +设置更新选项。 + +Set update options. + +```csharp +public GeneralClientBootstrap Option(UpdateOption option, object value) +``` + +#### SetBlacklist 方法 | SetBlacklist Method + +设置更新黑名单，指定不需要更新的文件。 + +Set update blacklist to specify files that should not be updated. + +```csharp +public GeneralClientBootstrap SetBlacklist(List blackFiles = null, + List blackFormats = null) +``` + +#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method +监听下载统计信息（速度、进度、剩余时间等）。 -### 示例 +Listen for download statistics (speed, progress, remaining time, etc.). -GeneralClientBootstrap使用代码示例 [进入](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs)。 +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadStatistics( + Action callbackAction) +``` -![](imgs/muti_donwload.png) +#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method +监听单个更新包下载完成事件。 +Listen for single update package download completion event. -### 注解 +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadCompleted( + Action callbackAction) +``` -GeneralClientBootstrap提供以下能力。 +#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method -#### 属性 +监听所有下载任务完成事件。 -| Properties | | -| ------------ | ---------------------------------------------------------- | -| UpdateOption | 更新操作配置设置枚举 | -| Configinfo | 客户端相关参数类（AppType、AppName、AppSecretKey等字段）。 | +Listen for all download tasks completion event. -#### 方法 +```csharp +public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( + Action callbackAction) +``` -| Method | | -| -------------------------------------- | ------------------------------------------------------------ | -| LaunchTaskAsync() | Task异步启动更新 | -| LaunchAsync() | 启动更新 | -| SetBlacklist() | 设置更新文件黑名单，如果不需要更新文件 名则传入即可。 | -| Option() | 设置更新配置。 | -| Config() | 更新相关内容配置参数，url 服务器地址及 端口号, appSecretKey客户端唯一标识用于 区分产品分支。 | -| GetOption() | 获取更新配置。 | -| SetCustomSkipOption() | 让用户在非强制更新的状态下决定是否进行更新。 | -| AddCustomOption() | 添加一个异步的自定义操作。理论上，任何自定义操作都可以完成。建议注册环境检查方法，以确保更新完成后存在正常的依赖和环境。 | -| AddListenerMultiAllDownloadCompleted() | 完成所有的下载任务通知。 | -| AddListenerMultiDownloadCompleted() | 单个或多个更新包下载完成事件。 | -| AddListenerMultiDownloadError() | 监听每个版本下载异常的事件 | -| AddListenerMultiDownloadStatistics() | 单个或多个更新包下载速度、剩余下载事 件、当前下载版本信息通知事件。 | -| AddListenerException() | 整个更新过程出现的任何问题都会通过这个回调函数通知。 | +#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method +监听下载错误事件。 +Listen for download error events. -### 🌴Packet +```csharp +public GeneralClientBootstrap AddListenerMultiDownloadError( + Action callbackAction) +``` -| 属性 | -| ------------------------------------------------------------ | -| **MainUpdateUrl** string 更新检查api地址。 | -| **AppType** int 1:ClientApp 2:UpdateApp | -| **UpdateUrl** string Update 更新检查api地址。 | -| **AppName** string 需要启动应用程序的名称。 | -| **MainAppName** string 需要启动主应用程序的名称。 | -| **Format** string 更新包文件格式（默认格式为Zip）。 | -| **IsUpgradeUpdate** bool 是否需要更新来升级应用程序。 | -| **IsMainUpdate** bool 主应用程序是否需要更新。 | -| **UpdateLogUrl** string 更新日志网页地址。 | -| **UpdateVersions** List 需要更新的版本信息VersionInfo。 | -| **Encoding** Encoding 文件操作的编码格式。 | -| **DownloadTimeOut** int 下载超时时间。 | -| **AppSecretKey** string 应用程序密钥，需要和服务器约定好。 | -| **ClientVersion** string 客户端当前版本号。 | -| **LastVersion** string 最新版本号。 | -| **InstallPath** string 安装路径（用于更新文件逻辑）。 | -| **TempPath** string 下载文件临时存储路径（用于更新文件逻辑）。 | -| **ProcessBase64** string 升级终端程序的配置参数。 | -| **Platform** string 当前策略所属的平台。（Windows\linux\Mac） | -| **BlackFiles** List 黑名单中的文件将跳过更新。 | -| **BlackFormats** 黑名单中的文件格式将跳过更新。 | +#### AddListenerException 方法 | AddListenerException Method +监听更新过程中的所有异常。 +Listen for all exceptions during the update process. -### 🌴Configinfo +```csharp +public GeneralClientBootstrap AddListenerException( + Action callbackAction) +``` + +#### AddCustomOption 方法 | AddCustomOption Method + +添加自定义异步操作，可在更新前后执行自定义逻辑。 -| **属性** | 类型 | 注释 | -| -------------------- | ------ | ------------------------------------------------------------ | -| UpdateUrl | string | 更新检查api地址。 | -| ReportUrl | string | 上报更新状态api地址。 | -| AppName | string | 需要启动应用程序的名称。 | -| MainAppName | string | 需要启动主应用程序的名称。 | -| UpdateLogUrl | string | 更新日志网页地址。 | -| AppSecretKey | string | 应用程序密钥，需要和服务端约定好验证身份和分支。 | -| ClientVersion | string | 客户端当前版本号。 | -| UpgradeClientVersion | string | 升级端当前版本号。 | -| InstallPath | string | 安装路径（用于更新文件逻辑）。 | -| BlackFiles | List | 黑名单中的文件将跳过更新。 | -| BlackFormats | List | 黑名单中的文件格式将跳过更新。 | -| SkipDirectorys | List | 跳过不需要更新的文件夹目录。 | -| ProductId | string | 当前产品分支的唯一id。 | -| Bowl | string | Bowl监控进程路径，更新完成之后启动Bowl监控客户端是否正常启动。如果启动后异常会捕捉异常信息。 | -| Scheme | string | 用于HTTP请求传入token进行身份验证。 | -| Token | string | 用于HTTP请求传入token进行身份验证。 | -| Script | string | 在Linux平台中更新完成之后执行，脚本给文件赋权限。更新之前需要赋权限在引导启动类里可通过GeneralClientBootstrap.AddCustomOption函数注入，函数会在更新前执行。 | +Add custom asynchronous operations that can execute custom logic before or after updates. + +```csharp +public GeneralClientBootstrap AddCustomOption(Func customFunc) +``` +#### SetCustomSkipOption 方法 | SetCustomSkipOption Method + +设置自定义跳过选项，允许用户决定是否继续更新。 + +Set custom skip options, allowing users to decide whether to continue with the update. + +```csharp +public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) +``` + +--- + +## 配置类详解 | Configuration Class Details + +### Configinfo 类 | Configinfo Class + +```csharp +public class Configinfo +{ + /// + /// 更新检查 API 地址 + /// Update check API address + /// + public string UpdateUrl { get; set; } + + /// + /// 更新状态报告 API 地址 + /// 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; } + + /// + /// 当前产品分支的唯一 ID + /// Unique ID of the current product branch + /// + public string ProductId { get; set; } + + /// + /// Bowl 监控进程路径，更新完成后启动 Bowl 检查客户端是否正常启动 + /// Bowl monitoring process path, starts after updates to check if the client starts normally + /// + public string Bowl { get; set; } + + /// + /// HTTP 请求中用于传递 token 的 Scheme（如 Bearer） + /// Scheme used for passing token in HTTP requests (e.g., Bearer) + /// + public string Scheme { get; set; } + + /// + /// HTTP 请求中用于身份验证的 Token + /// Token used for authentication in HTTP requests + /// + public string Token { get; set; } + + /// + /// Linux 平台下的脚本，用于在更新完成后为文件分配权限 + /// Script for Linux platform to assign permissions to files after update completion + /// + public string Script { get; set; } +} +``` + +### UpdateOption 枚举 | UpdateOption Enum + +```csharp +public enum UpdateOption +{ + /// + /// 更新包文件格式（默认为 Zip） + /// Update package file format (default is Zip) + /// + Format, + + /// + /// 压缩编码格式 + /// Compression encoding format + /// + Encoding, + + /// + /// 下载超时时间（秒）。如果不指定，默认超时时间为 30 秒 + /// Download timeout duration (seconds). Default is 30 seconds if not specified + /// + DownloadTimeOut, + + /// + /// 是否启用二进制差异更新功能，默认启用；设置为 false 则执行全量覆盖安装 + /// Whether to enable binary differential update function, enabled by default; + /// if set to false, full overwrite installation will be performed + /// + Patch, + + /// + /// 是否在更新前启用备份功能，默认启用；设置为 false 则不进行备份 + /// Whether to enable backup function before update, enabled by default; + /// if set to false, no backup will be performed + /// + BackUp +} +``` +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：基本更新流程 | 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($"更新异常: {args.Exception.Message}"); + }) + .LaunchAsync(); +``` + +### 示例 2：带黑名单的更新 | 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(); +``` + +### 示例 3：自定义更新选项 | 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(); +``` + +### 示例 4：完整的事件监听 | 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}] 进度: {args.ProgressPercentage}% | " + + $"速度: {args.Speed} | 剩余: {args.Remaining}"); + }) + // 单个下载完成 | Single download completed + .AddListenerMultiDownloadCompleted((sender, args) => + { + var version = args.Version as VersionInfo; + if (args.IsComplated) + Console.WriteLine($"✓ 版本 {version.Version} 下载成功"); + else + Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); + }) + // 所有下载完成 | All downloads completed + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + Console.WriteLine("✓ 所有更新包下载完成，准备安装..."); + else + Console.WriteLine($"✗ 下载失败，共 {args.FailedVersions.Count} 个版本失败"); + }) + // 下载错误 | Download error + .AddListenerMultiDownloadError((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); + }) + // 异常处理 | Exception handling + .AddListenerException((sender, args) => + { + Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); + }) + .LaunchAsync(); +``` + +### 示例 5：自定义操作和跳过选项 | Example 5: Custom Operations and Skip Options + +```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) + // 添加自定义操作（更新前检查环境）| Add custom operation (check environment before update) + .AddCustomOption(async () => + { + Console.WriteLine("正在检查运行环境..."); + await Task.Delay(1000); + // 检查磁盘空间、依赖项等 | Check disk space, dependencies, etc. + Console.WriteLine("环境检查完成"); + }) + // 设置用户跳过选项 | Set user skip option + .SetCustomSkipOption(() => + { + Console.WriteLine("发现新版本，是否更新？(y/n)"); + var input = Console.ReadLine(); + return input?.ToLower() == "y"; + }) + .LaunchAsync(); +``` + +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **版本号格式 | Version Number Format** + - 版本号必须遵循语义化版本规范（如 1.0.0.0） + - 确保客户端和服务器端版本号格式一致 + - 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** + - 在 Windows 上可能需要管理员权限来替换文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + - 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. + +### 💡 最佳实践 | Best Practices + +- **备份策略**：始终启用 BackUp 选项，以便更新失败时可以回滚 +- **差异更新**：启用 Patch 选项以减少下载量和更新时间 +- **错误处理**：实现完整的异常监听和错误处理逻辑 +- **用户体验**：在更新前提示用户并允许选择更新时机 +- **测试验证**：在生产环境部署前充分测试更新流程 +- **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**: 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 | + +--- -### 🍵UpdateOption +## 相关资源 | Related Resources -| **枚举** | -| ------------------------------------------------------------ | -| **Format** 更新包的文件格式。 | -| **Encoding** 压缩编码。 | -| **DownloadTimeOut** 超时时间（单位：秒）。如果未指定此参数，则默认超时时间为30秒。 | -| **Patch** 是否开启二进制差分功能，默认开启，如果设置为false均为覆盖安装。 | -| **BackUp** 是否开启更新前备份功能，默认开启，如果设置为false则不备份。 | - - - -### 适用于 - -| 产品 | 版本 | -| -------------- | ----------------- | -| .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) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](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 94503c0..09ce675 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 @@ -2,70 +2,628 @@ sidebar_position: 5 --- -### 定义 +# GeneralUpdate.Core -命名空间：GeneralUpdate.Core +## 组件概览 | Component Overview -程序集：GeneralUpdate.Core.dll +**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一，提供了完整的升级执行能力。与 ClientCore 不同，Core 组件作为独立的升级助手程序运行，负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式，Core 接收来自 ClientCore 的更新指令，并安全地完成主程序的升级任务。 +**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. +**命名空间 | Namespace:** `GeneralUpdate.Core` +**程序集 | Assembly:** `GeneralUpdate.Core.dll` -GeneralUpdate.Core是最核心的组件之一，提供了大量主要功能。当主程序升级操作完成之后会通过进程 启动并传参的方式调用本组件来完成主程序升级操作。（主要职责更新主程序） - -```c# +```csharp public class GeneralUpdateBootstrap : AbstractBootstrap ``` +--- + +## 核心特性 | Core Features + +### 1. 文件替换与版本管理 | File Replacement and Version Management +- 安全的文件替换机制，避免文件占用问题 | Safe file replacement mechanism to avoid file locking issues +- 支持多版本增量升级 | Support multi-version incremental upgrades +- 自动处理文件依赖关系 | Automatic handling of file dependencies + +### 2. 驱动升级支持 | Driver Upgrade Support +- 可选的驱动程序升级功能 | Optional driver upgrade functionality +- 字段映射表配置 | Field mapping table configuration +- 安全的驱动安装流程 | Safe driver installation process + +### 3. 完整的事件通知 | Comprehensive Event Notifications +- 下载进度实时监控 | Real-time download progress monitoring +- 多版本下载管理 | Multi-version download management +- 异常和错误完整捕获 | Complete exception and error capture + +### 4. 跨平台支持 | Cross-Platform Support +- Windows、Linux、macOS 平台全支持 | Full support for Windows, Linux, macOS platforms +- 自动平台检测和策略适配 | Automatic platform detection and strategy adaptation + +![Multi Download](imgs/muti_donwload.png) + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Core： + +Install GeneralUpdate.Core via NuGet: + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 | Initialization and Usage + +以下示例展示了如何在升级助手程序中配置和启动升级流程： + +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 +{ + Console.WriteLine($"升级程序初始化，{DateTime.Now}！"); + Console.WriteLine("当前运行目录：" + Thread.GetDomain().BaseDirectory); + + // 启动升级流程 | Launch upgrade process + await new GeneralUpdateBootstrap() + // 监听下载统计信息 | 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) + // 启动异步升级 | Launch async upgrade + .LaunchAsync(); + + Console.WriteLine($"升级程序已启动，{DateTime.Now}！"); + await Task.Delay(2000); +} +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($"当前下载版本：{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} 下载失败！"); +} -GeneralUpdateBootstrap使用代码示例 [进入](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs)。 +void OnMultiAllDownloadCompleted(object arg1, MultiAllDownloadCompletedEventArgs arg2) +{ + Console.WriteLine(arg2.IsAllDownloadCompleted ? + "所有下载任务已完成！" : + $"下载任务失败！失败数量：{arg2.FailedVersions.Count}"); +} -![](imgs/muti_donwload.png) +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 参考 | Core API Reference -### 注解 +### GeneralUpdateBootstrap 类方法 | GeneralUpdateBootstrap Class Methods -GeneralUpdateBootstrap提供以下能力。 +#### LaunchAsync 方法 | LaunchAsync Method -#### 构造函数 +异步启动升级流程。 -| Constructors | | -| ------------------------ | ---------------------------------- | -| GeneralUpdateBootstrap() | 当前GeneralUpdateBootstrap构造函数 | -| base:AbstractBootstrap() | 父类AbstractBootstrap构造函数 | +Launch the upgrade process asynchronously. -#### 属性 +```csharp +public async Task LaunchAsync() +``` -| Properties | | -| ------------ | -------------------- | -| Packet | 更新包信息 | -| UpdateOption | 更新操作配置设置枚举 | +**返回值 | Return Value:** +- 返回当前 GeneralUpdateBootstrap 实例，支持链式调用 +- Returns the current GeneralUpdateBootstrap instance, supporting method chaining -#### 方法 +#### Option 方法 | Option Method -| Method | | -| -------------------------------------- | ------------------------------------------------ | -| LaunchTaskAsync() | Task异步启动更新 | -| LaunchAsync() | 启动更新 | -| Option() | 设置更新配置。 | -| GetOption() | 获取更新配置。 | -| AddListenerMultiAllDownloadCompleted() | 监听所有更新版本下载完成事件 | -| AddListenerMultiDownloadCompleted() | 监听每个版本下载完成事件 | -| AddListenerMultiDownloadError() | 监听每个版本下载异常的事件 | -| AddListenerMultiDownloadStatistics() | 监听每个版本下载统计信息\下载进度事件 | -| AddListenerException() | 监听更新组件内部的所有异常 | -| SetFieldMappings() | 设置字段映射表，用于解析所有驱动包的信息的字符串 | +设置升级选项。 + +Set upgrade options. + +```csharp +public GeneralUpdateBootstrap Option(UpdateOption option, object value) +``` +**参数 | Parameters:** +- `option`: 升级选项枚举 | Upgrade option enum +- `value`: 选项值 | Option value + +**示例 | Example:** +```csharp +.Option(UpdateOption.Drive, true) // 启用驱动升级 | Enable driver upgrade +``` + +#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method + +监听下载统计信息（速度、进度、剩余时间等）。 + +Listen for download statistics (speed, progress, remaining time, etc.). + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( + Action callbackAction) +``` + +#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method + +监听单个更新包下载完成事件。 + +Listen for single update package download completion event. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method + +监听所有版本下载完成事件。 + +Listen for all version downloads completion event. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method + +监听每个版本下载错误事件。 + +Listen for download error events for each version. + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadError( + Action callbackAction) +``` + +#### AddListenerException 方法 | AddListenerException Method + +监听升级组件内部所有异常。 + +Listen for all internal exceptions in the upgrade component. + +```csharp +public GeneralUpdateBootstrap AddListenerException( + Action callbackAction) +``` +#### SetFieldMappings 方法 | SetFieldMappings Method + +设置字段映射表，用于解析驱动包信息。 + +Set field mapping table for parsing driver package information. + +```csharp +public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) +``` + +**参数 | Parameters:** +- `fieldMappings`: 字段映射字典，键为英文字段名，值为本地化字段名 +- Field mapping dictionary, key is English field name, value is localized field name + +--- + +## 配置类详解 | Configuration Class Details + +### UpdateOption 枚举 | UpdateOption Enum + +```csharp +public enum UpdateOption +{ + /// + /// 是否启用驱动升级功能 + /// Whether to enable driver upgrade functionality + /// + Drive +} +``` + +### Packet 类 | Packet Class + +升级包信息类，由 ClientCore 通过参数传递给 Core： + +Upgrade package information class, passed from ClientCore to Core via parameters: + +```csharp +public class Packet +{ + /// + /// 主更新检查 API 地址 + /// Main update check API address + /// + public string MainUpdateUrl { get; set; } + + /// + /// 应用类型：1=客户端应用，2=更新应用 + /// Application type: 1=ClientApp, 2=UpdateApp + /// + public int AppType { get; set; } + + /// + /// 更新检查 API 地址 + /// Update check API address + /// + public string UpdateUrl { get; set; } + + /// + /// 需要启动的应用程序名称 + /// Name of the application to be launched + /// + public string AppName { get; set; } + + /// + /// 主应用程序名称 + /// Main application name + /// + public string MainAppName { get; set; } + + /// + /// 更新包文件格式（默认为 Zip） + /// Update package file format (default is Zip) + /// + public string Format { get; set; } + + /// + /// 是否需要升级更新应用 + /// Indicates if the update application needs to be upgraded + /// + public bool IsUpgradeUpdate { get; set; } + + /// + /// 是否需要更新主应用 + /// Indicates if the main application needs to be updated + /// + public bool IsMainUpdate { get; set; } + + /// + /// 更新日志网页 URL + /// Update log webpage URL + /// + public string UpdateLogUrl { get; set; } + + /// + /// 需要更新的版本信息列表 + /// List of version information that needs updating + /// + public List UpdateVersions { get; set; } + + /// + /// 文件操作编码格式 + /// File operation encoding format + /// + public Encoding Encoding { get; set; } + + /// + /// 下载超时时间（秒） + /// Download timeout duration (seconds) + /// + public int DownloadTimeOut { get; set; } + + /// + /// 应用密钥，与服务器约定 + /// Application secret key, agreed upon with the server + /// + public string AppSecretKey { get; set; } + + /// + /// 当前客户端版本 + /// Current client version + /// + public string ClientVersion { get; set; } + + /// + /// 最新版本 + /// Latest version + /// + public string LastVersion { get; set; } + + /// + /// 安装路径（用于更新文件逻辑） + /// Installation path (used for update file logic) + /// + public string InstallPath { get; set; } + + /// + /// 下载文件的临时存储路径 + /// Temporary storage path for downloaded files + /// + public string TempPath { get; set; } + + /// + /// 升级终端程序的配置参数（Base64 编码） + /// Configuration parameters for the upgrade terminal program (Base64 encoded) + /// + public string ProcessBase64 { get; set; } + + /// + /// 当前策略所属平台（Windows/Linux/Mac） + /// Platform to which the current strategy belongs (Windows/Linux/Mac) + /// + public string Platform { get; set; } + + /// + /// 黑名单文件列表 + /// Files in the blacklist + /// + public List BlackFiles { get; set; } + + /// + /// 黑名单文件格式列表 + /// File formats in the blacklist + /// + public List BlackFormats { get; set; } + + /// + /// 是否启用驱动升级功能 + /// Indicates if the driver upgrade feature is enabled + /// + public bool DriveEnabled { get; set; } +} +``` + +--- + +## 实际使用示例 | Practical Usage Examples + +### 示例 1：基本升级流程 | Example 1: Basic Upgrade Process + +```csharp +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Internal; +using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + +try +{ + Console.WriteLine("升级程序初始化..."); + + // 启动升级流程 | Launch upgrade process + await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}] 下载进度: {args.ProgressPercentage}%"); + }) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); + + Console.WriteLine("升级完成！"); +} +catch (Exception e) +{ + Console.WriteLine($"升级失败: {e.Message}"); +} +``` + +### 示例 2：启用驱动升级 | Example 2: Enable Driver Upgrade + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Internal.Bootstrap; + +// 中文字段映射表 | Chinese field mapping table +var fieldMappingsCN = new Dictionary +{ + { "DriverName", "驱动名称" }, + { "DriverVersion", "驱动版本" }, + { "DriverDescription", "驱动描述" }, + { "InstallPath", "安装路径" } +}; + +await new GeneralUpdateBootstrap() + // 设置字段映射表 | Set field mappings + .SetFieldMappings(fieldMappingsCN) + // 启用驱动更新 | Enable driver update + .Option(UpdateOption.Drive, true) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); +``` + +### 示例 3：完整事件监听 | Example 3: Complete Event Listening + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; + +await new GeneralUpdateBootstrap() + // 下载统计 | Download statistics + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}]"); + Console.WriteLine($" 速度: {args.Speed}"); + Console.WriteLine($" 进度: {args.ProgressPercentage}%"); + Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); + Console.WriteLine($" 剩余时间: {args.Remaining}"); + }) + // 单个下载完成 | Single download completed + .AddListenerMultiDownloadCompleted((sender, args) => + { + var version = args.Version as VersionInfo; + string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; + Console.WriteLine($"版本 {version.Version} 下载{status}"); + }) + // 所有下载完成 | All downloads completed + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + Console.WriteLine("✓ 所有版本下载完成，开始安装..."); + } + else + { + Console.WriteLine($"✗ 下载失败，{args.FailedVersions.Count} 个版本失败："); + foreach (var version in args.FailedVersions) + { + Console.WriteLine($" - {version}"); + } + } + }) + // 下载错误 | Download error + .AddListenerMultiDownloadError((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"✗ 版本 {version.Version} 错误:"); + Console.WriteLine($" {args.Exception.Message}"); + }) + // 异常处理 | Exception handling + .AddListenerException((sender, args) => + { + Console.WriteLine("⚠ 升级过程异常:"); + Console.WriteLine($" 错误: {args.Exception.Message}"); + Console.WriteLine($" 堆栈: {args.Exception.StackTrace}"); + }) + .LaunchAsync(); +``` + +### 示例 4：自定义升级流程 | Example 4: Custom Upgrade Process + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; + +// 记录升级开始时间 | Record upgrade start time +var startTime = DateTime.Now; +var downloadedVersions = new List(); + +await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadCompleted((sender, args) => + { + if (args.IsComplated) + { + var version = args.Version as VersionInfo; + downloadedVersions.Add(version.Version); + } + }) + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + var duration = DateTime.Now - startTime; + Console.WriteLine($"升级完成！"); + Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); + Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); + } + }) + .AddListenerException((sender, args) => + { + // 记录日志到文件 | Log to file + File.AppendAllText("upgrade_error.log", + $"[{DateTime.Now}] {args.Exception}\n"); + }) + .LaunchAsync(); +``` + +--- + +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **进程隔离 | Process Isolation** + - Core 必须作为独立进程运行，不能在主程序中直接调用 + - 升级时主程序必须完全关闭，否则文件替换会失败 + - Core must run as an independent process, cannot be called directly in the main program + - The main program must be completely closed during upgrade, otherwise file replacement will fail + +2. **参数传递 | Parameter Passing** + - ClientCore 通过 Base64 编码的参数传递配置给 Core + - 确保参数传递过程中不会被截断或损坏 + - ClientCore passes configuration to Core via Base64 encoded parameters + - Ensure parameters are not truncated or corrupted during passing + +3. **文件权限 | File Permissions** + - 在 Windows 上可能需要管理员权限替换系统目录中的文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + - Administrator privileges may be required on Windows to replace files in system directories + - Appropriate file system permissions are required on Linux/macOS + +4. **驱动升级 | Driver Upgrade** + - 驱动升级功能需要系统级权限 + - 建议在测试环境充分验证后再使用 + - Driver upgrade functionality requires system-level permissions + - Recommended to thoroughly validate in test environment before use + +5. **回滚机制 | Rollback Mechanism** + - Core 不直接提供回滚功能，但保留了备份文件 + - 如需回滚，可使用 ClientCore 的备份功能 + - Core does not directly provide rollback functionality, but backup files are preserved + - For rollback, use ClientCore's backup functionality + +### 💡 最佳实践 | Best Practices + +- **日志记录**：实现完整的异常监听，记录升级过程中的所有问题 +- **超时设置**：根据网络环境合理设置下载超时时间 +- **进度反馈**：向用户显示升级进度，提升用户体验 +- **错误处理**：升级失败时提供清晰的错误信息和解决方案 +- **测试验证**：在各种网络条件下测试升级流程的稳定性 +- **Logging**: Implement complete exception listening to record all issues during the upgrade process +- **Timeout Settings**: Set download timeout appropriately based on network environment +- **Progress Feedback**: Display upgrade progress to users to improve user experience +- **Error Handling**: Provide clear error messages and solutions when upgrade fails +- **Testing**: Test upgrade process stability under various network conditions + +--- + +## 适用平台 | Applicable Platforms + +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | + +--- -### 适用于 +## 相关资源 | Related Resources -| 产品 | 版本 | -| -------------- | ------------- | -| .NET | 5、6、7、8、9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **相关组件**：[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) 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 20d7f65..7bf5a80 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 @@ -2,108 +2,474 @@ sidebar_position: 6 --- -### 定义 +# GeneralUpdate.Differential -命名空间：GeneralUpdate.Differential +## 组件概览 | Component Overview -程序集：GeneralUpdate.Core.dll +**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法，可以精确识别两个版本之间的文件变化，生成高效的增量补丁包，并支持补丁还原操作。通过使用差异更新，可以显著减少更新包的大小和下载时间，特别适合频繁发布更新的应用场景。 +**GeneralUpdate.Differential** is the core component responsible for binary differential updates in the GeneralUpdate framework. This component provides powerful differential algorithms that can accurately identify file changes between two versions, generate efficient incremental patch packages, and support patch restoration operations. By using differential updates, you can significantly reduce update package size and download time, making it particularly suitable for scenarios with frequent update releases. +**命名空间 | Namespace:** `GeneralUpdate.Differential` +**程序集 | Assembly:** `GeneralUpdate.Core.dll` -该组件提供文件的二进制差分补丁文件生成（算法），文件增量识别（版本差异）、删除文件识别（版本差异）、黑名单、补丁还原等能力。 - -```c# +```csharp public sealed class DifferentialCore ``` +--- +## 核心特性 | Core Features -### 示例 +### 1. 增量识别 | Incremental Identification +- 精确识别新增、修改、删除的文件 | Accurately identify added, modified, and deleted files +- 智能文件版本对比 | Intelligent file version comparison +- 支持跳过指定文件和格式 | Support skipping specified files and formats -以下示例定义方法，以包含增量识别，生成二进制补丁、补丁还原、设置黑名单示例GeneralUpdate.Tools项目中的打包工具也是强依赖此组件。 +### 2. 二进制补丁生成 | Binary Patch Generation +- 高效的二进制差异算法 | Efficient binary differential algorithm +- 最小化补丁文件大小 | Minimize patch file size +- 快速补丁生成速度 | Fast patch generation speed -```c# -//增量识别，生成二进制补丁 -public async Task TestDifferentialClean() -{ - //上一个版本的客户端文件夹路径 - var path1 = "D:\\packet\\source"; - //最新版本客户端文件夹路径 - var path2 = "D:\\packet\\target"; - //补丁文件生成路径 - var path3 = "D:\\packet\\patchs"; - await DifferentialCore.Instance.Clean(path1, path2, path3); -} +### 3. 补丁还原 | Patch Restoration +- 安全的补丁应用流程 | Safe patch application process +- 自动处理文件依赖关系 | Automatic handling of file dependencies +- 完整性验证机制 | Integrity verification mechanism -//补丁还原 -public async Task TestDifferentialDirty() -{ - //当前版本的客户端文件夹路径 - var path1 = "D:\\packet\\source"; - //补丁文件生成路径 - var path2 = "D:\\packet\\patchs"; - await DifferentialCore.Instance.Dirty(path1, path2); -} +### 4. 黑名单支持 | Blacklist Support +- 文件级黑名单 | File-level blacklist +- 格式级黑名单 | Format-level blacklist +- 灵活的过滤规则 | Flexible filtering rules + +--- + +## 快速开始 | Quick Start + +### 安装 | Installation + +通过 NuGet 安装 GeneralUpdate.Differential（包含在 Core 包中）： + +Install GeneralUpdate.Differential via NuGet (included in Core package): + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 | Initialization and Usage + +以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作： + +The following example demonstrates how to use DifferentialCore for incremental identification and patch operations: + +```csharp +using GeneralUpdate.Differential; + +// 增量识别并生成二进制补丁 | Identify increments and generate binary patches +var sourcePath = @"D:\packet\app"; // 旧版本路径 | Old version path +var targetPath = @"D:\packet\release"; // 新版本路径 | New version path +var patchPath = @"D:\packet\patch"; // 补丁输出路径 | Patch output path + +await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); + +// 应用补丁（还原） | Apply patches (restoration) +await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); +``` + +--- + +## 核心 API 参考 | Core API Reference + +### DifferentialCore 类 | DifferentialCore Class + +#### Instance 属性 | Instance Property + +获取 DifferentialCore 的单例实例。 + +Get the singleton instance of DifferentialCore. + +```csharp +public static DifferentialCore Instance { get; } ``` +#### Clean 方法 | Clean Method + +执行增量识别、删除文件识别，并生成二进制补丁文件。 + +Perform incremental identification, deleted file identification, and generate binary patch files. + +**方法签名 | Method Signature:** +```csharp +public async Task Clean(string sourcePath, string targetPath, string patchPath = null) +``` -### 注解 +**参数 | Parameters:** +- `sourcePath`: 旧版本文件夹路径 | Path to the old version folder +- `targetPath`: 新版本文件夹路径 | Path to the new version folder +- `patchPath`: 补丁文件输出目录（可选）| Directory to store discovered incremental update files (optional) + +**功能说明 | Function Description:** +1. 对比 sourcePath 和 targetPath 两个目录 +2. 识别新增、修改、删除的文件 +3. 为修改的文件生成二进制差异补丁 +4. 将补丁和新增文件保存到 patchPath + +**示例 | Example:** +```csharp +// 生成从 v1.0.0 到 v1.1.0 的补丁包 +var source = @"D:\MyApp\v1.0.0"; +var target = @"D:\MyApp\v1.1.0"; +var patch = @"D:\MyApp\patches\v1.1.0"; + +await DifferentialCore.Instance.Clean(source, target, patch); +// 结果：patch 目录包含所有必要的增量更新文件 +``` -DifferentialCore提供增量识别，生成二进制补丁、补丁还原、设置黑名单能力。 +#### Dirty 方法 | Dirty Method -#### 方法 +应用补丁，将旧版本文件更新到新版本。 -| 名称 | 类型 | 备注 | -| ------- | ---- | ---------------------------------------------------- | -| Clean() | 方法 | 增量识别，删除文件识别，生成二进制补丁文件 | -| Dirty() | 方法 | 补丁还原（将补丁打到旧的客户端文件上达到更新的目的） | +Apply patches to update old version files to the new version. +**方法签名 | Method Signature:** +```csharp +public async Task Dirty(string appPath, string patchPath) +``` -### 🌼Clean() +**参数 | Parameters:** +- `appPath`: 客户端应用程序目录（当前版本）| Client application directory (current version) +- `patchPath`: 补丁文件路径 | Path to the patch files -**方法** +**功能说明 | Function Description:** +1. 读取 patchPath 中的补丁文件 +2. 将补丁应用到 appPath 中的对应文件 +3. 处理新增文件的复制 +4. 处理删除文件的移除 -生成补丁文件[不能包含文件名相同但扩展名不同的文件]。 +**示例 | Example:** +```csharp +// 将补丁应用到当前应用程序 +var appDir = AppDomain.CurrentDomain.BaseDirectory; +var patchDir = Path.Combine(appDir, "temp", "patches"); -```c# -public async Task Clean(string sourcePath, string targetPath, string patchPath = null); +await DifferentialCore.Instance.Dirty(appDir, patchDir); +// 结果：应用程序更新到新版本 ``` -**参数** +--- -**sourcePath** 上一个版本的文件夹路径。 +## 实际使用示例 | Practical Usage Examples -**targetPath** 最近版本的文件夹路径。 +### 示例 1：基本补丁生成 | Example 1: Basic Patch Generation -**patchPath** 将发现的增量更新文件存储在临时目录中。 +```csharp +using GeneralUpdate.Differential; +public async Task GeneratePatchAsync() +{ + try + { + // 版本路径 | Version paths + var oldVersion = @"D:\MyApp\1.0.0"; + var newVersion = @"D:\MyApp\1.0.1"; + var patchOutput = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始生成补丁..."); + + // 生成补丁 | Generate patches + await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); + + Console.WriteLine($"补丁生成完成！输出目录：{patchOutput}"); + + // 显示补丁信息 | Display patch information + var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); + Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); + + long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); + Console.WriteLine($"总补丁大小：{totalSize / 1024.0:F2} KB"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁生成失败：{ex.Message}"); + } +} +``` + +### 示例 2：应用补丁 | Example 2: Apply Patches +```csharp +using GeneralUpdate.Differential; -### 🌼Dirty() +public async Task ApplyPatchAsync() +{ + try + { + // 应用程序目录 | Application directory + var appDirectory = @"D:\MyApp\current"; + // 补丁目录 | Patch directory + var patchDirectory = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始应用补丁..."); + + // 验证补丁存在 | Verify patch exists + if (!Directory.Exists(patchDirectory)) + { + throw new DirectoryNotFoundException($"补丁目录不存在：{patchDirectory}"); + } + + // 应用补丁 | Apply patches + await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); + + Console.WriteLine("补丁应用成功！应用程序已更新到新版本。"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁应用失败：{ex.Message}"); + } +} +``` -**方法** +### 示例 3：完整的补丁流程 | Example 3: Complete Patch Workflow -应用补丁[不能包含文件名相同但扩展名不同的文件]。 +```csharp +using GeneralUpdate.Differential; +using System.IO.Compression; -```c# -public async Task Dirty(string appPath, string patchPath); +public class PatchManager +{ + // 生成并打包补丁 | Generate and package patches + public async Task CreatePatchPackageAsync( + string oldVersionPath, + string newVersionPath, + string outputPath) + { + try + { + // 1. 生成补丁文件 | Generate patch files + var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempPatchDir); + + Console.WriteLine($"正在生成补丁..."); + await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); + + // 2. 压缩补丁文件 | Compress patch files + var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); + Console.WriteLine($"正在打包补丁..."); + + if (File.Exists(patchZipPath)) + File.Delete(patchZipPath); + + ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, + CompressionLevel.Optimal, false); + + // 3. 清理临时文件 | Clean up temp files + Directory.Delete(tempPatchDir, true); + + var patchSize = new FileInfo(patchZipPath).Length; + Console.WriteLine($"补丁包创建成功：{patchZipPath}"); + Console.WriteLine($"补丁包大小：{patchSize / 1024.0:F2} KB"); + + return patchZipPath; + } + catch (Exception ex) + { + Console.WriteLine($"创建补丁包失败：{ex.Message}"); + throw; + } + } + + // 解压并应用补丁 | Extract and apply patches + public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) + { + try + { + // 1. 解压补丁包 | Extract patch package + var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempExtractDir); + + Console.WriteLine($"正在解压补丁包..."); + ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); + + // 2. 应用补丁 | Apply patches + Console.WriteLine($"正在应用补丁..."); + await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); + + // 3. 清理临时文件 | Clean up temp files + Directory.Delete(tempExtractDir, true); + + Console.WriteLine($"补丁应用成功！"); + } + catch (Exception ex) + { + Console.WriteLine($"应用补丁包失败：{ex.Message}"); + throw; + } + } +} + +// 使用示例 | Usage example +var manager = new PatchManager(); + +// 创建补丁包 | Create patch package +var patchZip = await manager.CreatePatchPackageAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\releases" +); + +// 应用补丁包 | Apply patch package +await manager.ApplyPatchPackageAsync( + @"D:\MyApp\current", + patchZip +); +``` + +### 示例 4：带进度显示的补丁操作 | Example 4: Patch Operations with Progress Display + +```csharp +using GeneralUpdate.Differential; + +public class ProgressivePatchManager +{ + public async Task GeneratePatchWithProgressAsync( + string sourcePath, + string targetPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始扫描文件差异..."); + + // 在实际场景中，可以在 Clean 前后添加进度报告 + await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); + + progress?.Report("补丁生成完成！"); + + // 统计信息 | Statistics + var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); + progress?.Report($"共生成 {files.Length} 个补丁文件"); + } + catch (Exception ex) + { + progress?.Report($"错误：{ex.Message}"); + throw; + } + } + + public async Task ApplyPatchWithProgressAsync( + string appPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始应用补丁..."); + + await DifferentialCore.Instance.Dirty(appPath, patchPath); + + progress?.Report("补丁应用成功！"); + } + catch (Exception ex) + { + progress?.Report($"错误：{ex.Message}"); + throw; + } + } +} + +// 使用示例 | Usage example +var manager = new ProgressivePatchManager(); +var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); + +await manager.GeneratePatchWithProgressAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\patches\1.0.1", + progress +); ``` +--- -**参数** +## 注意事项与警告 | Notes and Warnings + +### ⚠️ 重要提示 | Important Notes + +1. **文件名限制 | File Name Restrictions** + - 不能包含同名但扩展名不同的文件（如 file.txt 和 file.log） + - 建议使用唯一的文件名命名规则 + - Cannot include files with the same name but different extensions (e.g., file.txt and file.log) + - Recommended to use unique file naming conventions + +2. **目录结构 | Directory Structure** + - 源目录和目标目录的相对结构应保持一致 + - 补丁生成时会保留目录层次关系 + - The relative structure of source and target directories should remain consistent + - Directory hierarchy is preserved during patch generation + +3. **磁盘空间 | Disk Space** + - 确保有足够的磁盘空间存储补丁文件 + - 二进制差异补丁通常比完整文件小，但仍需要临时空间 + - Ensure sufficient disk space for storing patch files + - Binary differential patches are usually smaller than complete files, but still require temporary space + +4. **文件占用 | File Locking** + - 应用补丁时，确保目标文件没有被其他进程占用 + - 建议在应用程序关闭后应用补丁 + - When applying patches, ensure target files are not locked by other processes + - Recommended to apply patches after the application is closed + +5. **备份建议 | Backup Recommendations** + - 在应用补丁前建议备份原始文件 + - 可以使用 ClientCore 的 BackUp 选项自动备份 + - Recommended to backup original files before applying patches + - Can use ClientCore's BackUp option for automatic backup + +### 💡 最佳实践 | Best Practices + +- **版本管理**：为每个版本维护独立的补丁包，便于版本追踪和回滚 +- **补丁验证**：生成补丁后进行验证测试，确保补丁可以正确应用 +- **增量更新**：优先使用差异更新而非全量更新，可节省 50%-90% 的下载量 +- **错误处理**：实现完整的异常捕获和错误恢复机制 +- **性能优化**：对于大文件，差异算法的性能优势更加明显 +- **Version Management**: Maintain separate patch packages for each version for easier version tracking and rollback +- **Patch Validation**: Perform validation testing after generating patches to ensure they can be applied correctly +- **Incremental Updates**: Prioritize differential updates over full updates, which can save 50%-90% of download size +- **Error Handling**: Implement complete exception capture and error recovery mechanisms +- **Performance Optimization**: For large files, the performance advantage of the differential algorithm is more pronounced + +### 🔍 工作原理 | How It Works + +**Clean 方法工作流程 | Clean Method Workflow:** +1. 扫描源目录和目标目录中的所有文件 +2. 比较文件的MD5哈希值以识别变化 +3. 对于修改的文件，使用二进制差异算法生成补丁 +4. 对于新增文件，直接复制到补丁目录 +5. 记录删除的文件列表 + +**Dirty 方法工作流程 | Dirty Method Workflow:** +1. 读取补丁目录中的所有文件 +2. 对于补丁文件，应用到对应的原文件上 +3. 对于新增文件，直接复制到应用目录 +4. 根据删除列表移除相应文件 +5. 验证更新完整性 -**appPath** 客户端应用程序目录。 +--- -**patchPath** 补丁文件路径。 +## 适用平台 | Applicable Platforms +| 产品 Product | 版本 Version | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +--- -### 适用于 +## 相关资源 | Related Resources -| 产品 | 版本 | -| -------------- | ------------- | -| .NET | 5、6、7、8、9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **打包工具**：GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 | The GeneralUpdate.PacketTool project depends on this component for differential packaging From f9ac7c787975311763c6075f44ac573d7134bec7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:37:38 +0000 Subject: [PATCH 5/7] Create Chinese-only i18n documentation files Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com> --- website/docs/doc/GeneralUpdate.Bowl.md | 199 +++--- .../doc/GeneralUpdate.ClientCore.zh-CN.md | 604 ++++++++++++++++++ website/docs/doc/GeneralUpdate.Core.zh-CN.md | 565 ++++++++++++++++ .../doc/GeneralUpdate.Differential.zh-CN.md | 448 +++++++++++++ .../current/doc/GeneralUpdate.Bowl.md | 191 +++--- 5 files changed, 1768 insertions(+), 239 deletions(-) create mode 100644 website/docs/doc/GeneralUpdate.ClientCore.zh-CN.md create mode 100644 website/docs/doc/GeneralUpdate.Core.zh-CN.md create mode 100644 website/docs/doc/GeneralUpdate.Differential.zh-CN.md diff --git a/website/docs/doc/GeneralUpdate.Bowl.md b/website/docs/doc/GeneralUpdate.Bowl.md index 5af0825..de44ec6 100644 --- a/website/docs/doc/GeneralUpdate.Bowl.md +++ b/website/docs/doc/GeneralUpdate.Bowl.md @@ -4,14 +4,12 @@ sidebar_position: 3 # GeneralUpdate.Bowl -## 组件概览 | Component Overview +## 组件概览 **GeneralUpdate.Bowl** 是一个独立的进程监控组件，在升级流程结束前启动，负责启动主客户端应用程序并监控其运行状态。该组件提供了完整的崩溃监控和诊断能力，当被监控的应用程序发生异常时，会自动导出Dump文件、驱动信息、系统信息和事件日志，帮助开发者快速定位问题。 -**GeneralUpdate.Bowl** is an independent process monitoring component that launches before the end of the upgrade process. It is responsible for starting the main client application and monitoring its running status. This component provides comprehensive crash monitoring and diagnostic capabilities. When the monitored application encounters an exception, it automatically exports Dump files, driver information, system information, and event logs to help developers quickly locate issues. - -**命名空间 | Namespace:** `GeneralUpdate.Bowl` -**程序集 | Assembly:** `GeneralUpdate.Bowl.dll` +**命名空间：** `GeneralUpdate.Bowl` +**程序集：** `GeneralUpdate.Bowl.dll` ```csharp public sealed class Bowl @@ -19,41 +17,37 @@ public sealed class Bowl --- -## 核心特性 | Core Features +## 核心特性 -### 1. 进程监控 | Process Monitoring -- 实时监控目标应用程序的运行状态 | Real-time monitoring of target application status -- 自动检测进程崩溃和异常退出 | Automatic detection of process crashes and abnormal exits +### 1. 进程监控 +- 实时监控目标应用程序的运行状态 +- 自动检测进程崩溃和异常退出 -### 2. 崩溃诊断 | Crash Diagnostics -- 自动生成Dump文件（.dmp）用于崩溃分析 | Automatic generation of Dump files (.dmp) for crash analysis -- 导出详细的系统和驱动信息 | Export detailed system and driver information -- 收集Windows系统事件日志 | Collect Windows system event logs +### 2. 崩溃诊断 +- 自动生成Dump文件（.dmp）用于崩溃分析 +- 导出详细的系统和驱动信息 +- 收集Windows系统事件日志 -### 3. 版本化管理 | Version Management -- 按版本号分类存储故障信息 | Store failure information categorized by version number -- 支持升级和正常两种工作模式 | Support both upgrade and normal working modes +### 3. 版本化管理 +- 按版本号分类存储故障信息 +- 支持升级和正常两种工作模式 --- -## 快速开始 | Quick Start +## 快速开始 -### 安装 | Installation +### 安装 通过 NuGet 安装 GeneralUpdate.Bowl： -Install GeneralUpdate.Bowl via NuGet: - ```bash dotnet add package GeneralUpdate.Bowl ``` -### 初始化与使用 | Initialization and Usage +### 初始化与使用 以下示例展示了如何使用 Bowl 组件监控应用程序： -The following example demonstrates how to use the Bowl component to monitor an application: - ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; @@ -68,67 +62,59 @@ var processInfo = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", lastVersion), BackupDirectory = Path.Combine(installPath, lastVersion), - WorkModel = "Normal" // 使用 Normal 模式独立监控 | Use Normal mode for standalone monitoring + WorkModel = "Normal" // 使用 Normal 模式独立监控 }; Bowl.Launch(processInfo); ``` --- -## 核心 API 参考 | Core API Reference +## 核心 API 参考 -### Launch 方法 | Launch Method +### Launch 方法 启动进程监控功能。 -Start the process monitoring functionality. - -**方法签名 | Method Signature:** +**方法签名：** ```csharp public static void Launch(MonitorParameter? monitorParameter = null) ``` -**参数 | Parameters:** +**参数：** -#### MonitorParameter 类 | MonitorParameter Class +#### MonitorParameter 类 ```csharp public class MonitorParameter { /// /// 被监控的目录 - /// Directory being monitored /// public string TargetPath { get; set; } /// /// 导出异常信息的目录 - /// Directory where captured exception information is exported /// public string FailDirectory { get; set; } /// /// 备份目录 - /// Backup directory /// public string BackupDirectory { get; set; } /// /// 被监控进程的名称或ID - /// Name or ID of the process being monitored /// public string ProcessNameOrId { get; set; } /// /// Dump 文件名 - /// Dump file name /// public string DumpFileName { get; set; } /// /// 升级包版本信息（.json）文件名 - /// Upgrade package version information (.json) file name /// public string FailFileName { get; set; } @@ -136,12 +122,6 @@ public class MonitorParameter /// 工作模式： /// - Upgrade: 升级模式，主要用于与 GeneralUpdate 配合使用，内部逻辑处理，默认模式启动时请勿随意修改 /// - Normal: 正常模式，可独立使用监控单个程序，程序崩溃时导出崩溃信息 - /// - /// Work Mode: - /// - Upgrade: Upgrade mode, primarily used in conjunction with GeneralUpdate for internal logic handling. - /// Do not modify arbitrarily when the default mode is activated. - /// - Normal: Normal mode, can be used independently to monitor a single program. - /// Exports crash information when the program crashes. /// public string WorkModel { get; set; } = "Upgrade"; } @@ -149,15 +129,15 @@ public class MonitorParameter --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：独立模式监控应用 | Example 1: Standalone Mode Application Monitoring +### 示例 1：独立模式监控应用 ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; -// 配置监控参数 | Configure monitoring parameters +// 配置监控参数 var installPath = AppDomain.CurrentDomain.BaseDirectory; var currentVersion = "1.0.0.5"; @@ -169,20 +149,20 @@ var monitorConfig = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "crash_reports", currentVersion), BackupDirectory = Path.Combine(installPath, "backups", currentVersion), - WorkModel = "Normal" // 独立监控模式 | Standalone monitoring mode + WorkModel = "Normal" // 独立监控模式 }; -// 启动监控 | Start monitoring +// 启动监控 Bowl.Launch(monitorConfig); ``` -### 示例 2：结合 GeneralUpdate 使用 | Example 2: Use with GeneralUpdate +### 示例 2：结合 GeneralUpdate 使用 ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; -// 在升级完成后启动 Bowl 监控 | Start Bowl monitoring after upgrade completion +// 在升级完成后启动 Bowl 监控 var installPath = AppDomain.CurrentDomain.BaseDirectory; var upgradedVersion = "2.0.0.1"; @@ -194,7 +174,7 @@ var upgradeMonitor = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", upgradedVersion), BackupDirectory = Path.Combine(installPath, upgradedVersion), - WorkModel = "Upgrade" // 升级模式 | Upgrade mode + WorkModel = "Upgrade" // 升级模式 }; Bowl.Launch(upgradeMonitor); @@ -202,51 +182,43 @@ Bowl.Launch(upgradeMonitor); --- -## 崩溃信息捕获 | Crash Information Capture +## 崩溃信息捕获 当检测到崩溃时，以下文件将在运行目录中生成： -When a crash is detected, the following files will be generated in the running directory: - -- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) | **Dump file** (`x.0.0.*_fail.dmp`) -- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) | **Upgrade package version information** (`x.0.0.*_fail.json`) -- 📒 **驱动信息** (`driverInfo.txt`) | **Driver information** (`driverInfo.txt`) -- 📒 **操作系统/硬件信息** (`systeminfo.txt`) | **Operating system/hardware information** (`systeminfo.txt`) -- 📒 **系统事件日志** (`systemlog.evtx`) | **System event log** (`systemlog.evtx`) +- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) +- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) +- 📒 **驱动信息** (`driverInfo.txt`) +- 📒 **操作系统/硬件信息** (`systeminfo.txt`) +- 📒 **系统事件日志** (`systemlog.evtx`) 这些文件将按版本号分类导出到 "fail" 目录中。 -These files will be exported to the "fail" directory, categorized by version number. - -![Crash Files](imgs/crash.jpg) +![崩溃文件](imgs/crash.jpg) -### 1. Dump 文件 | Dump File +### 1. Dump 文件 Dump 文件包含崩溃时刻的内存快照，可用于调试分析： -The Dump file contains a memory snapshot at the moment of crash, which can be used for debugging analysis: +![Dump文件](imgs/dump.png) -![Dump File](imgs/dump.png) - -### 2. 版本信息文件 | Version Information File +### 2. 版本信息文件 JSON 格式的详细崩溃报告，包含参数配置和 ProcDump 输出： -Detailed crash report in JSON format, including parameter configuration and ProcDump output: - ```json { - "Parameter": { - "TargetPath": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\", - "FailDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\fail\\1.0.0.3", - "BackupDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\1.0.0.3", - "ProcessNameOrId": "JsonTest.exe", - "DumpFileName": "1.0.0.3_fail.dmp", - "FailFileName": "1.0.0.3_fail.json", - "WorkModel": "Normal", - "ExtendedField": null - }, - "ProcdumpOutPutLines": [ +"Parameter": { +"TargetPath": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\", +"FailDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\fail\\1.0.0.3", +"BackupDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\1.0.0.3", +"ProcessNameOrId": "JsonTest.exe", +"DumpFileName": "1.0.0.3_fail.dmp", +"FailFileName": "1.0.0.3_fail.json", +"WorkModel": "Normal", +"ExtendedField": null +}, +"ProcdumpOutPutLines": [ "ProcDump v11.0 - Sysinternals process dump utility", "Copyright (C) 2009-2022 Mark Russinovich and Andrew Richards", "Sysinternals - www.sysinternals.com", @@ -274,26 +246,22 @@ Detailed crash report in JSON format, including parameter configuration and Proc } ``` -### 3. 驱动信息文件 | Driver Information File +### 3. 驱动信息文件 包含系统中所有驱动程序的详细信息： -Contains detailed information about all drivers in the system: - ```text Module Name Display Name Description Driver Type Start Mode State Status ============ ====================== ====================== ============= ========== ========== ========== 360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK 360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK -// ...更多驱动信息 | ...more driver information +// ...更多驱动信息 ``` -### 4. 系统信息文件 | System Information File +### 4. 系统信息文件 完整的操作系统和硬件配置信息： -Complete operating system and hardware configuration information: - ```text Host Name: **** OS Name: Microsoft Windows 11 Pro @@ -302,72 +270,59 @@ System Manufacturer: ASUS System Model: System Product Name Processor(s): Intel** Family * Model *** Total Physical Memory: 16,194 MB -// ...更多系统信息 | ...more system information +// ...更多系统信息 ``` -### 5. 系统事件日志 | System Event Log +### 5. 系统事件日志 Windows 事件查看器格式的系统日志（.evtx 文件）： -System log in Windows Event Viewer format (.evtx file): - -![System Event Log](imgs/evtx.png) +![系统事件日志](imgs/evtx.png) --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **工作模式选择 | Work Mode Selection** +1. **工作模式选择** - `Upgrade` 模式：专门用于与 GeneralUpdate 框架集成，包含内部逻辑处理 - `Normal` 模式：可独立使用，适合监控任何 .NET 应用程序 - - `Upgrade` mode: Specifically for integration with GeneralUpdate framework, includes internal logic processing - - `Normal` mode: Can be used independently, suitable for monitoring any .NET application -2. **权限要求 | Permission Requirements** +2. **权限要求** - Bowl 需要足够的权限来生成 Dump 文件和读取系统信息 - 建议以管理员权限运行需要监控的应用程序 - - Bowl requires sufficient permissions to generate Dump files and read system information - - It is recommended to run the monitored application with administrator privileges -3. **磁盘空间 | Disk Space** +3. **磁盘空间** - Dump 文件可能占用大量磁盘空间（通常 50-200 MB） - 确保 FailDirectory 所在磁盘有足够的可用空间 - - Dump files may consume significant disk space (typically 50-200 MB) - - Ensure sufficient available space on the disk where FailDirectory is located -4. **依赖项 | Dependencies** +4. **依赖项** - Bowl 使用 ProcDump 工具生成 Dump 文件，该工具已内置在组件中 - 无需额外安装依赖项 - - Bowl uses the ProcDump tool to generate Dump files, which is built into the component - - No additional dependencies need to be installed -### 💡 最佳实践 | Best Practices +### 💡 最佳实践 - **版本号管理**：为每个版本使用独立的故障目录，便于问题追踪 - **日志清理**：定期清理旧版本的故障信息，避免磁盘空间耗尽 - **测试验证**：在生产环境部署前，在测试环境验证监控功能 -- **Version Management**: Use separate failure directories for each version for easier issue tracking -- **Log Cleanup**: Regularly clean up failure information from old versions to avoid disk space exhaustion -- **Testing**: Verify monitoring functionality in a test environment before production deployment --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | -| ------------------ | ----------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | -| ASP.NET | Any | +| 产品 | 版本 | +| --------------- | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +| ASP.NET | Any | --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) -- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) | [Watch Bilibili Tutorial](https://www.bilibili.com/video/BV1c8iyYZE7P) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) +- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) diff --git a/website/docs/doc/GeneralUpdate.ClientCore.zh-CN.md b/website/docs/doc/GeneralUpdate.ClientCore.zh-CN.md new file mode 100644 index 0000000..deb4ec3 --- /dev/null +++ b/website/docs/doc/GeneralUpdate.ClientCore.zh-CN.md @@ -0,0 +1,604 @@ +--- +sidebar_position: 4 +--- + +# GeneralUpdate.ClientCore + +## 组件概览 + +**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一,提供了丰富的客户端更新功能。该组件运行在主应用程序中,负责检查更新、下载更新包、验证完整性,并在完成后启动升级助手(GeneralUpdate.Core)来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新,而不影响当前运行状态。 + +**命名空间:** `GeneralUpdate.ClientCore` +**程序集:** `GeneralUpdate.ClientCore.dll` + +```csharp +public class GeneralClientBootstrap : AbstractBootstrap +``` + +--- + +## 核心特性 + +### 1. 多版本下载管理 +- 支持同时下载多个版本的更新包 +- 断点续传和下载速度限制 +- 实时下载进度和统计信息 + +### 2. 灵活的配置选项 +- 黑名单机制(文件、格式、目录) +- 自定义更新策略和操作 +- 支持二进制差异更新和全量更新 + +### 3. 完整的事件通知 +- 下载进度、完成、错误事件 +- 支持用户自定义跳过更新选项 +- 异常和错误全程监控 + +### 4. 多平台支持 +- 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) +``` + +#### SetCustomSkipOption 方法 + +设置自定义跳过选项,允许用户决定是否继续更新。 + +```csharp +public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) +``` + +--- + +## 配置类详解 + +### 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; } +} +``` + +### UpdateOption 枚举 + +```csharp +public enum UpdateOption +{ + /// + /// 更新包文件格式(默认为 Zip) + /// + Format, + + /// + /// 压缩编码格式 + /// + Encoding, + + /// + /// 下载超时时间(秒)。如果不指定,默认超时时间为 30 秒 + /// + DownloadTimeOut, + + /// + /// 是否启用二进制差异更新功能,默认启用;设置为 false 则执行全量覆盖安装 + /// + Patch, + + /// + /// 是否在更新前启用备份功能,默认启用;设置为 false 则不进行备份 + /// + BackUp +} +``` + +--- + +## 实际使用示例 + +### 示例 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:自定义操作和跳过选项 + +```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) + // 添加自定义操作(更新前检查环境) + .AddCustomOption(async () => + { + Console.WriteLine("正在检查运行环境..."); + await Task.Delay(1000); + // 检查磁盘空间、依赖项等 + Console.WriteLine("环境检查完成"); + }) + // 设置用户跳过选项 + .SetCustomSkipOption(() => + { + Console.WriteLine("发现新版本,是否更新?(y/n)"); + var input = Console.ReadLine(); + return input?.ToLower() == "y"; + }) + .LaunchAsync(); +``` + +--- + +## 注意事项与警告 + +### ⚠️ 重要提示 + +1. **版本号格式** + - 版本号必须遵循语义化版本规范(如 1.0.0.0) + - 确保客户端和服务器端版本号格式一致 + +2. **网络连接** + - 确保更新服务器地址可访问 + - 建议实现重试机制处理网络波动 + +3. **进程管理** + - 更新过程会关闭主程序并启动升级助手 + - 确保保存所有用户数据后再执行更新 + +4. **权限要求** + - 在 Windows 上可能需要管理员权限来替换文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + +5. **黑名单使用** + - 黑名单中的文件和目录不会被更新 + - 常用于保护配置文件、用户数据等 + +### 💡 最佳实践 + +- **备份策略**:始终启用 BackUp 选项,以便更新失败时可以回滚 +- **差异更新**:启用 Patch 选项以减少下载量和更新时间 +- **错误处理**:实现完整的异常监听和错误处理逻辑 +- **用户体验**:在更新前提示用户并允许选择更新时机 +- **测试验证**:在生产环境部署前充分测试更新流程 + +--- + +## 适用平台 + +| 产品 | 版本 | +| ------------------ | -------------------- | +| .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.zh-CN.md b/website/docs/doc/GeneralUpdate.Core.zh-CN.md new file mode 100644 index 0000000..7e60681 --- /dev/null +++ b/website/docs/doc/GeneralUpdate.Core.zh-CN.md @@ -0,0 +1,565 @@ +--- +sidebar_position: 5 +--- + +# GeneralUpdate.Core + +## 组件概览 + +**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一,提供了完整的升级执行能力。与 ClientCore 不同,Core 组件作为独立的升级助手程序运行,负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式,Core 接收来自 ClientCore 的更新指令,并安全地完成主程序的升级任务。 + +**命名空间:** `GeneralUpdate.Core` +**程序集:** `GeneralUpdate.Core.dll` + +```csharp +public class GeneralUpdateBootstrap : AbstractBootstrap +``` + +--- + +## 核心特性 + +### 1. 文件替换与版本管理 +- 安全的文件替换机制,避免文件占用问题 +- 支持多版本增量升级 +- 自动处理文件依赖关系 + +### 2. 驱动升级支持 +- 可选的驱动程序升级功能 +- 字段映射表配置 +- 安全的驱动安装流程 + +### 3. 完整的事件通知 +- 下载进度实时监控 +- 多版本下载管理 +- 异常和错误完整捕获 + +### 4. 跨平台支持 +- Windows、Linux、macOS 平台全支持 +- 自动平台检测和策略适配 + +![Multi Download](imgs/muti_donwload.png) + +--- + +## 快速开始 + +### 安装 + +通过 NuGet 安装 GeneralUpdate.Core: + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 + +以下示例展示了如何在升级助手程序中配置和启动升级流程: + +```csharp +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Internal; +using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + +try +{ + Console.WriteLine($"升级程序初始化,{DateTime.Now}!"); + Console.WriteLine("当前运行目录:" + Thread.GetDomain().BaseDirectory); + + // 启动升级流程 + await new GeneralUpdateBootstrap() + // 监听下载统计信息 + .AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics) + // 监听单个下载完成 + .AddListenerMultiDownloadCompleted(OnMultiDownloadCompleted) + // 监听所有下载完成 + .AddListenerMultiAllDownloadCompleted(OnMultiAllDownloadCompleted) + // 监听下载错误 + .AddListenerMultiDownloadError(OnMultiDownloadError) + // 监听异常 + .AddListenerException(OnException) + // 启动异步升级 + .LaunchAsync(); + + Console.WriteLine($"升级程序已启动,{DateTime.Now}!"); + await Task.Delay(2000); +} +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 参考 + +### GeneralUpdateBootstrap 类方法 + +#### LaunchAsync 方法 + +异步启动升级流程。 + +```csharp +public async Task LaunchAsync() +``` + +**返回值:** +- 返回当前 GeneralUpdateBootstrap 实例,支持链式调用 + +#### Option 方法 + +设置升级选项。 + +```csharp +public GeneralUpdateBootstrap Option(UpdateOption option, object value) +``` + +**参数:** +- `option`: 升级选项枚举 +- `value`: 选项值 + +**示例:** +```csharp +.Option(UpdateOption.Drive, true) // 启用驱动升级 +``` + +#### AddListenerMultiDownloadStatistics 方法 + +监听下载统计信息(速度、进度、剩余时间等)。 + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( + Action callbackAction) +``` + +#### AddListenerMultiDownloadCompleted 方法 + +监听单个更新包下载完成事件。 + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiAllDownloadCompleted 方法 + +监听所有版本下载完成事件。 + +```csharp +public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( + Action callbackAction) +``` + +#### AddListenerMultiDownloadError 方法 + +监听每个版本下载错误事件。 + +```csharp +public GeneralUpdateBootstrap AddListenerMultiDownloadError( + Action callbackAction) +``` + +#### AddListenerException 方法 + +监听升级组件内部所有异常。 + +```csharp +public GeneralUpdateBootstrap AddListenerException( + Action callbackAction) +``` + +#### SetFieldMappings 方法 + +设置字段映射表,用于解析驱动包信息。 + +```csharp +public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) +``` + +**参数:** +- `fieldMappings`: 字段映射字典,键为英文字段名,值为本地化字段名 + +--- + +## 配置类详解 + +### UpdateOption 枚举 + +```csharp +public enum UpdateOption +{ + /// + /// 是否启用驱动升级功能 + /// + Drive +} +``` + +### Packet 类 + +升级包信息类,由 ClientCore 通过参数传递给 Core: + +```csharp +public class Packet +{ + /// + /// 主更新检查 API 地址 + /// + public string MainUpdateUrl { get; set; } + + /// + /// 应用类型:1=客户端应用,2=更新应用 + /// + public int AppType { get; set; } + + /// + /// 更新检查 API 地址 + /// + public string UpdateUrl { get; set; } + + /// + /// 需要启动的应用程序名称 + /// + public string AppName { get; set; } + + /// + /// 主应用程序名称 + /// + public string MainAppName { get; set; } + + /// + /// 更新包文件格式(默认为 Zip) + /// + public string Format { get; set; } + + /// + /// 是否需要升级更新应用 + /// + public bool IsUpgradeUpdate { get; set; } + + /// + /// 是否需要更新主应用 + /// + public bool IsMainUpdate { get; set; } + + /// + /// 更新日志网页 URL + /// + public string UpdateLogUrl { get; set; } + + /// + /// 需要更新的版本信息列表 + /// + public List UpdateVersions { get; set; } + + /// + /// 文件操作编码格式 + /// + public Encoding Encoding { get; set; } + + /// + /// 下载超时时间(秒) + /// + public int DownloadTimeOut { get; set; } + + /// + /// 应用密钥,与服务器约定 + /// + public string AppSecretKey { get; set; } + + /// + /// 当前客户端版本 + /// + public string ClientVersion { get; set; } + + /// + /// 最新版本 + /// + public string LastVersion { get; set; } + + /// + /// 安装路径(用于更新文件逻辑) + /// + public string InstallPath { get; set; } + + /// + /// 下载文件的临时存储路径 + /// + public string TempPath { get; set; } + + /// + /// 升级终端程序的配置参数(Base64 编码) + /// + public string ProcessBase64 { get; set; } + + /// + /// 当前策略所属平台(Windows/Linux/Mac) + /// + public string Platform { get; set; } + + /// + /// 黑名单文件列表 + /// + public List BlackFiles { get; set; } + + /// + /// 黑名单文件格式列表 + /// + public List BlackFormats { get; set; } + + /// + /// 是否启用驱动升级功能 + /// + public bool DriveEnabled { get; set; } +} +``` + +--- + +## 实际使用示例 + +### 示例 1:基本升级流程 + +```csharp +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Internal; +using GeneralUpdate.Common.Shared.Object; +using GeneralUpdate.Core; + +try +{ + Console.WriteLine("升级程序初始化..."); + + // 启动升级流程 + await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}] 下载进度: {args.ProgressPercentage}%"); + }) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); + + Console.WriteLine("升级完成!"); +} +catch (Exception e) +{ + Console.WriteLine($"升级失败: {e.Message}"); +} +``` + +### 示例 2:启用驱动升级 + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Internal.Bootstrap; + +// 中文字段映射表 +var fieldMappingsCN = new Dictionary +{ + { "DriverName", "驱动名称" }, + { "DriverVersion", "驱动版本" }, + { "DriverDescription", "驱动描述" }, + { "InstallPath", "安装路径" } +}; + +await new GeneralUpdateBootstrap() + // 设置字段映射表 + .SetFieldMappings(fieldMappingsCN) + // 启用驱动更新 + .Option(UpdateOption.Drive, true) + .AddListenerException((sender, args) => + { + Console.WriteLine($"升级异常: {args.Exception.Message}"); + }) + .LaunchAsync(); +``` + +### 示例 3:完整事件监听 + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; + +await new GeneralUpdateBootstrap() + // 下载统计 + .AddListenerMultiDownloadStatistics((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"[{version.Version}]"); + Console.WriteLine($" 速度: {args.Speed}"); + Console.WriteLine($" 进度: {args.ProgressPercentage}%"); + Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); + Console.WriteLine($" 剩余时间: {args.Remaining}"); + }) + // 单个下载完成 + .AddListenerMultiDownloadCompleted((sender, args) => + { + var version = args.Version as VersionInfo; + string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; + Console.WriteLine($"版本 {version.Version} 下载{status}"); + }) + // 所有下载完成 + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + Console.WriteLine("✓ 所有版本下载完成,开始安装..."); + } + else + { + Console.WriteLine($"✗ 下载失败,{args.FailedVersions.Count} 个版本失败:"); + foreach (var version in args.FailedVersions) + { + Console.WriteLine($" - {version}"); + } + } + }) + // 下载错误 + .AddListenerMultiDownloadError((sender, args) => + { + var version = args.Version as VersionInfo; + Console.WriteLine($"✗ 版本 {version.Version} 错误:"); + Console.WriteLine($" {args.Exception.Message}"); + }) + // 异常处理 + .AddListenerException((sender, args) => + { + Console.WriteLine("⚠ 升级过程异常:"); + Console.WriteLine($" 错误: {args.Exception.Message}"); + Console.WriteLine($" 堆栈: {args.Exception.StackTrace}"); + }) + .LaunchAsync(); +``` + +### 示例 4:自定义升级流程 + +```csharp +using GeneralUpdate.Core; +using GeneralUpdate.Common.Download; +using GeneralUpdate.Common.Shared.Object; + +// 记录升级开始时间 +var startTime = DateTime.Now; +var downloadedVersions = new List(); + +await new GeneralUpdateBootstrap() + .AddListenerMultiDownloadCompleted((sender, args) => + { + if (args.IsComplated) + { + var version = args.Version as VersionInfo; + downloadedVersions.Add(version.Version); + } + }) + .AddListenerMultiAllDownloadCompleted((sender, args) => + { + if (args.IsAllDownloadCompleted) + { + var duration = DateTime.Now - startTime; + Console.WriteLine($"升级完成!"); + Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); + Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); + } + }) + .AddListenerException((sender, args) => + { + // 记录日志到文件 + File.AppendAllText("upgrade_error.log", + $"[{DateTime.Now}] {args.Exception}\n"); + }) + .LaunchAsync(); +``` + +--- + +## 注意事项与警告 + +### ⚠️ 重要提示 + +1. **进程隔离** + - Core 必须作为独立进程运行,不能在主程序中直接调用 + - 升级时主程序必须完全关闭,否则文件替换会失败 + +2. **参数传递** + - ClientCore 通过 Base64 编码的参数传递配置给 Core + - 确保参数传递过程中不会被截断或损坏 + +3. **文件权限** + - 在 Windows 上可能需要管理员权限替换系统目录中的文件 + - 在 Linux/macOS 上需要适当的文件系统权限 + +4. **驱动升级** + - 驱动升级功能需要系统级权限 + - 建议在测试环境充分验证后再使用 + +5. **回滚机制** + - Core 不直接提供回滚功能,但保留了备份文件 + - 如需回滚,可使用 ClientCore 的备份功能 + +### 💡 最佳实践 + +- **日志记录**:实现完整的异常监听,记录升级过程中的所有问题 +- **超时设置**:根据网络环境合理设置下载超时时间 +- **进度反馈**:向用户显示升级进度,提升用户体验 +- **错误处理**:升级失败时提供清晰的错误信息和解决方案 +- **测试验证**:在各种网络条件下测试升级流程的稳定性 + +--- + +## 适用平台 + +| 产品 | 版本 | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | + +--- + +## 相关资源 + +- **示例代码**:[查看 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) diff --git a/website/docs/doc/GeneralUpdate.Differential.zh-CN.md b/website/docs/doc/GeneralUpdate.Differential.zh-CN.md new file mode 100644 index 0000000..edb101a --- /dev/null +++ b/website/docs/doc/GeneralUpdate.Differential.zh-CN.md @@ -0,0 +1,448 @@ +--- +sidebar_position: 6 +--- + +# GeneralUpdate.Differential + +## 组件概览 + +**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法,可以精确识别两个版本之间的文件变化,生成高效的增量补丁包,并支持补丁还原操作。通过使用差异更新,可以显著减少更新包的大小和下载时间,特别适合频繁发布更新的应用场景。 + +**命名空间:** `GeneralUpdate.Differential` +**程序集:** `GeneralUpdate.Core.dll` + +```csharp +public sealed class DifferentialCore +``` + +--- + +## 核心特性 + +### 1. 增量识别 +- 精确识别新增、修改、删除的文件 +- 智能文件版本对比 +- 支持跳过指定文件和格式 + +### 2. 二进制补丁生成 +- 高效的二进制差异算法 +- 最小化补丁文件大小 +- 快速补丁生成速度 + +### 3. 补丁还原 +- 安全的补丁应用流程 +- 自动处理文件依赖关系 +- 完整性验证机制 + +### 4. 黑名单支持 +- 文件级黑名单 +- 格式级黑名单 +- 灵活的过滤规则 + +--- + +## 快速开始 + +### 安装 + +通过 NuGet 安装 GeneralUpdate.Differential(包含在 Core 包中): + +```bash +dotnet add package GeneralUpdate.Core +``` + +### 初始化与使用 + +以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作: + +```csharp +using GeneralUpdate.Differential; + +// 增量识别并生成二进制补丁 +var sourcePath = @"D:\packet\app"; // 旧版本路径 +var targetPath = @"D:\packet\release"; // 新版本路径 +var patchPath = @"D:\packet\patch"; // 补丁输出路径 + +await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); + +// 应用补丁(还原) +await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); +``` + +--- + +## 核心 API 参考 + +### DifferentialCore 类 + +#### Instance 属性 + +获取 DifferentialCore 的单例实例。 + +```csharp +public static DifferentialCore Instance { get; } +``` + +#### Clean 方法 + +执行增量识别、删除文件识别,并生成二进制补丁文件。 + +**方法签名:** + +```csharp +public async Task Clean(string sourcePath, string targetPath, string patchPath = null) +``` + +**参数:** +- `sourcePath`: 旧版本文件夹路径 +- `targetPath`: 新版本文件夹路径 +- `patchPath`: 补丁文件输出目录(可选) + +**功能说明:** +1. 对比 sourcePath 和 targetPath 两个目录 +2. 识别新增、修改、删除的文件 +3. 为修改的文件生成二进制差异补丁 +4. 将补丁和新增文件保存到 patchPath + +**示例:** +```csharp +// 生成从 v1.0.0 到 v1.1.0 的补丁包 +var source = @"D:\MyApp\v1.0.0"; +var target = @"D:\MyApp\v1.1.0"; +var patch = @"D:\MyApp\patches\v1.1.0"; + +await DifferentialCore.Instance.Clean(source, target, patch); +// 结果:patch 目录包含所有必要的增量更新文件 +``` + +#### Dirty 方法 + +应用补丁,将旧版本文件更新到新版本。 + +**方法签名:** + +```csharp +public async Task Dirty(string appPath, string patchPath) +``` + +**参数:** +- `appPath`: 客户端应用程序目录(当前版本) +- `patchPath`: 补丁文件路径 + +**功能说明:** +1. 读取 patchPath 中的补丁文件 +2. 将补丁应用到 appPath 中的对应文件 +3. 处理新增文件的复制 +4. 处理删除文件的移除 + +**示例:** +```csharp +// 将补丁应用到当前应用程序 +var appDir = AppDomain.CurrentDomain.BaseDirectory; +var patchDir = Path.Combine(appDir, "temp", "patches"); + +await DifferentialCore.Instance.Dirty(appDir, patchDir); +// 结果:应用程序更新到新版本 +``` + +--- + +## 实际使用示例 + +### 示例 1:基本补丁生成 + +```csharp +using GeneralUpdate.Differential; + +public async Task GeneratePatchAsync() +{ + try + { + // 版本路径 + var oldVersion = @"D:\MyApp\1.0.0"; + var newVersion = @"D:\MyApp\1.0.1"; + var patchOutput = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始生成补丁..."); + + // 生成补丁 + await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); + + Console.WriteLine($"补丁生成完成!输出目录:{patchOutput}"); + + // 显示补丁信息 + var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); + Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); + + long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); + Console.WriteLine($"总补丁大小:{totalSize / 1024.0:F2} KB"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁生成失败:{ex.Message}"); + } +} +``` + +### 示例 2:应用补丁 + +```csharp +using GeneralUpdate.Differential; + +public async Task ApplyPatchAsync() +{ + try + { + // 应用程序目录 + var appDirectory = @"D:\MyApp\current"; + // 补丁目录 + var patchDirectory = @"D:\MyApp\patches\1.0.1"; + + Console.WriteLine("开始应用补丁..."); + + // 验证补丁存在 + if (!Directory.Exists(patchDirectory)) + { + throw new DirectoryNotFoundException($"补丁目录不存在:{patchDirectory}"); + } + + // 应用补丁 + await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); + + Console.WriteLine("补丁应用成功!应用程序已更新到新版本。"); + } + catch (Exception ex) + { + Console.WriteLine($"补丁应用失败:{ex.Message}"); + } +} +``` + +### 示例 3:完整的补丁流程 + +```csharp +using GeneralUpdate.Differential; +using System.IO.Compression; + +public class PatchManager +{ + // 生成并打包补丁 + public async Task CreatePatchPackageAsync( + string oldVersionPath, + string newVersionPath, + string outputPath) + { + try + { + // 1. 生成补丁文件 + var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempPatchDir); + + Console.WriteLine($"正在生成补丁..."); + await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); + + // 2. 压缩补丁文件 + var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); + Console.WriteLine($"正在打包补丁..."); + + if (File.Exists(patchZipPath)) + File.Delete(patchZipPath); + + ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, + CompressionLevel.Optimal, false); + + // 3. 清理临时文件 + Directory.Delete(tempPatchDir, true); + + var patchSize = new FileInfo(patchZipPath).Length; + Console.WriteLine($"补丁包创建成功:{patchZipPath}"); + Console.WriteLine($"补丁包大小:{patchSize / 1024.0:F2} KB"); + + return patchZipPath; + } + catch (Exception ex) + { + Console.WriteLine($"创建补丁包失败:{ex.Message}"); + throw; + } + } + + // 解压并应用补丁 + public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) + { + try + { + // 1. 解压补丁包 + var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); + Directory.CreateDirectory(tempExtractDir); + + Console.WriteLine($"正在解压补丁包..."); + ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); + + // 2. 应用补丁 + Console.WriteLine($"正在应用补丁..."); + await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); + + // 3. 清理临时文件 + Directory.Delete(tempExtractDir, true); + + Console.WriteLine($"补丁应用成功!"); + } + catch (Exception ex) + { + Console.WriteLine($"应用补丁包失败:{ex.Message}"); + throw; + } + } +} + +// 使用示例 +var manager = new PatchManager(); + +// 创建补丁包 +var patchZip = await manager.CreatePatchPackageAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\releases" +); + +// 应用补丁包 +await manager.ApplyPatchPackageAsync( + @"D:\MyApp\current", + patchZip +); +``` + +### 示例 4:带进度显示的补丁操作 + +```csharp +using GeneralUpdate.Differential; + +public class ProgressivePatchManager +{ + public async Task GeneratePatchWithProgressAsync( + string sourcePath, + string targetPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始扫描文件差异..."); + + // 在实际场景中,可以在 Clean 前后添加进度报告 + await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); + + progress?.Report("补丁生成完成!"); + + // 统计信息 + var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); + progress?.Report($"共生成 {files.Length} 个补丁文件"); + } + catch (Exception ex) + { + progress?.Report($"错误:{ex.Message}"); + throw; + } + } + + public async Task ApplyPatchWithProgressAsync( + string appPath, + string patchPath, + IProgress progress) + { + try + { + progress?.Report("开始应用补丁..."); + + await DifferentialCore.Instance.Dirty(appPath, patchPath); + + progress?.Report("补丁应用成功!"); + } + catch (Exception ex) + { + progress?.Report($"错误:{ex.Message}"); + throw; + } + } +} + +// 使用示例 +var manager = new ProgressivePatchManager(); +var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); + +await manager.GeneratePatchWithProgressAsync( + @"D:\MyApp\1.0.0", + @"D:\MyApp\1.0.1", + @"D:\MyApp\patches\1.0.1", + progress +); +``` +--- + +## 注意事项与警告 + +### ⚠️ 重要提示 + +1. **文件名限制** + - 不能包含同名但扩展名不同的文件(如 file.txt 和 file.log) + - 建议使用唯一的文件名命名规则 + +2. **目录结构** + - 源目录和目标目录的相对结构应保持一致 + - 补丁生成时会保留目录层次关系 + +3. **磁盘空间** + - 确保有足够的磁盘空间存储补丁文件 + - 二进制差异补丁通常比完整文件小,但仍需要临时空间 + +4. **文件占用** + - 应用补丁时,确保目标文件没有被其他进程占用 + - 建议在应用程序关闭后应用补丁 + +5. **备份建议** + - 在应用补丁前建议备份原始文件 + - 可以使用 ClientCore 的 BackUp 选项自动备份 + +### 💡 最佳实践 + +- **版本管理**:为每个版本维护独立的补丁包,便于版本追踪和回滚 +- **补丁验证**:生成补丁后进行验证测试,确保补丁可以正确应用 +- **增量更新**:优先使用差异更新而非全量更新,可节省 50%-90% 的下载量 +- **错误处理**:实现完整的异常捕获和错误恢复机制 +- **性能优化**:对于大文件,差异算法的性能优势更加明显 + +### 🔍 工作原理 + +**Clean 方法工作流程:** +1. 扫描源目录和目标目录中的所有文件 +2. 比较文件的MD5哈希值以识别变化 +3. 对于修改的文件,使用二进制差异算法生成补丁 +4. 对于新增文件,直接复制到补丁目录 +5. 记录删除的文件列表 + +**Dirty 方法工作流程:** +1. 读取补丁目录中的所有文件 +2. 对于补丁文件,应用到对应的原文件上 +3. 对于新增文件,直接复制到应用目录 +4. 根据删除列表移除相应文件 +5. 验证更新完整性 + +--- + +## 适用平台 + +| 产品 | 版本 | +| ------------------ | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | + +--- + +## 相关资源 + +- **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) +- **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) +- **打包工具**:GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md index 5af0825..1fb57e4 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md +++ b/website/i18n/en/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md @@ -4,14 +4,12 @@ sidebar_position: 3 # GeneralUpdate.Bowl -## 组件概览 | Component Overview - -**GeneralUpdate.Bowl** 是一个独立的进程监控组件，在升级流程结束前启动，负责启动主客户端应用程序并监控其运行状态。该组件提供了完整的崩溃监控和诊断能力，当被监控的应用程序发生异常时，会自动导出Dump文件、驱动信息、系统信息和事件日志，帮助开发者快速定位问题。 +## Component Overview **GeneralUpdate.Bowl** is an independent process monitoring component that launches before the end of the upgrade process. It is responsible for starting the main client application and monitoring its running status. This component provides comprehensive crash monitoring and diagnostic capabilities. When the monitored application encounters an exception, it automatically exports Dump files, driver information, system information, and event logs to help developers quickly locate issues. -**命名空间 | Namespace:** `GeneralUpdate.Bowl` -**程序集 | Assembly:** `GeneralUpdate.Bowl.dll` +**Namespace:** `GeneralUpdate.Bowl` +**Assembly:** `GeneralUpdate.Bowl.dll` ```csharp public sealed class Bowl @@ -19,28 +17,26 @@ public sealed class Bowl --- -## 核心特性 | Core Features +## Core Features -### 1. 进程监控 | Process Monitoring -- 实时监控目标应用程序的运行状态 | Real-time monitoring of target application status -- 自动检测进程崩溃和异常退出 | Automatic detection of process crashes and abnormal exits +### 1. Process Monitoring +- Real-time monitoring of target application status +- Automatic detection of process crashes and abnormal exits -### 2. 崩溃诊断 | Crash Diagnostics -- 自动生成Dump文件（.dmp）用于崩溃分析 | Automatic generation of Dump files (.dmp) for crash analysis -- 导出详细的系统和驱动信息 | Export detailed system and driver information -- 收集Windows系统事件日志 | Collect Windows system event logs +### 2. Crash Diagnostics +- Automatic generation of Dump files (.dmp) for crash analysis +- Export detailed system and driver information +- Collect Windows system event logs -### 3. 版本化管理 | Version Management -- 按版本号分类存储故障信息 | Store failure information categorized by version number -- 支持升级和正常两种工作模式 | Support both upgrade and normal working modes +### 3. Version Management +- Store failure information categorized by version number +- Support both upgrade and normal working modes --- -## 快速开始 | Quick Start - -### 安装 | Installation +## Quick Start -通过 NuGet 安装 GeneralUpdate.Bowl： +### Installation Install GeneralUpdate.Bowl via NuGet: @@ -48,9 +44,7 @@ Install GeneralUpdate.Bowl via NuGet: dotnet add package GeneralUpdate.Bowl ``` -### 初始化与使用 | Initialization and Usage - -以下示例展示了如何使用 Bowl 组件监控应用程序： +### Initialization and Usage The following example demonstrates how to use the Bowl component to monitor an application: @@ -68,75 +62,63 @@ var processInfo = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", lastVersion), BackupDirectory = Path.Combine(installPath, lastVersion), - WorkModel = "Normal" // 使用 Normal 模式独立监控 | Use Normal mode for standalone monitoring + WorkModel = "Normal" // Use Normal mode for standalone monitoring }; Bowl.Launch(processInfo); ``` --- -## 核心 API 参考 | Core API Reference +## Core API Reference -### Launch 方法 | Launch Method - -启动进程监控功能。 +### Launch Method Start the process monitoring functionality. -**方法签名 | Method Signature:** +**Method Signature:** ```csharp public static void Launch(MonitorParameter? monitorParameter = null) ``` -**参数 | Parameters:** +**Parameters:** -#### MonitorParameter 类 | MonitorParameter Class +#### MonitorParameter Class ```csharp public class MonitorParameter { /// - /// 被监控的目录 /// Directory being monitored /// public string TargetPath { get; set; } /// - /// 导出异常信息的目录 /// Directory where captured exception information is exported /// public string FailDirectory { get; set; } /// - /// 备份目录 /// Backup directory /// public string BackupDirectory { get; set; } /// - /// 被监控进程的名称或ID /// Name or ID of the process being monitored /// public string ProcessNameOrId { get; set; } /// - /// Dump 文件名 /// Dump file name /// public string DumpFileName { get; set; } /// - /// 升级包版本信息（.json）文件名 /// Upgrade package version information (.json) file name /// public string FailFileName { get; set; } /// - /// 工作模式： - /// - Upgrade: 升级模式，主要用于与 GeneralUpdate 配合使用，内部逻辑处理，默认模式启动时请勿随意修改 - /// - Normal: 正常模式，可独立使用监控单个程序，程序崩溃时导出崩溃信息 - /// /// Work Mode: /// - Upgrade: Upgrade mode, primarily used in conjunction with GeneralUpdate for internal logic handling. /// Do not modify arbitrarily when the default mode is activated. @@ -149,15 +131,15 @@ public class MonitorParameter --- -## 实际使用示例 | Practical Usage Examples +## Practical Usage Examples -### 示例 1：独立模式监控应用 | Example 1: Standalone Mode Application Monitoring +### Example 1: Standalone Mode Application Monitoring ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; -// 配置监控参数 | Configure monitoring parameters +// Configure monitoring parameters var installPath = AppDomain.CurrentDomain.BaseDirectory; var currentVersion = "1.0.0.5"; @@ -169,20 +151,20 @@ var monitorConfig = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "crash_reports", currentVersion), BackupDirectory = Path.Combine(installPath, "backups", currentVersion), - WorkModel = "Normal" // 独立监控模式 | Standalone monitoring mode + WorkModel = "Normal" // Standalone monitoring mode }; -// 启动监控 | Start monitoring +// Start monitoring Bowl.Launch(monitorConfig); ``` -### 示例 2：结合 GeneralUpdate 使用 | Example 2: Use with GeneralUpdate +### Example 2: Use with GeneralUpdate ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; -// 在升级完成后启动 Bowl 监控 | Start Bowl monitoring after upgrade completion +// Start Bowl monitoring after upgrade completion var installPath = AppDomain.CurrentDomain.BaseDirectory; var upgradedVersion = "2.0.0.1"; @@ -194,7 +176,7 @@ var upgradeMonitor = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", upgradedVersion), BackupDirectory = Path.Combine(installPath, upgradedVersion), - WorkModel = "Upgrade" // 升级模式 | Upgrade mode + WorkModel = "Upgrade" // Upgrade mode }; Bowl.Launch(upgradeMonitor); @@ -202,51 +184,43 @@ Bowl.Launch(upgradeMonitor); --- -## 崩溃信息捕获 | Crash Information Capture - -当检测到崩溃时，以下文件将在运行目录中生成： +## Crash Information Capture When a crash is detected, the following files will be generated in the running directory: -- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) | **Dump file** (`x.0.0.*_fail.dmp`) -- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) | **Upgrade package version information** (`x.0.0.*_fail.json`) -- 📒 **驱动信息** (`driverInfo.txt`) | **Driver information** (`driverInfo.txt`) -- 📒 **操作系统/硬件信息** (`systeminfo.txt`) | **Operating system/hardware information** (`systeminfo.txt`) -- 📒 **系统事件日志** (`systemlog.evtx`) | **System event log** (`systemlog.evtx`) - -这些文件将按版本号分类导出到 "fail" 目录中。 +- 📒 **Dump file** (`x.0.0.*_fail.dmp`) +- 📒 **Upgrade package version information** (`x.0.0.*_fail.json`) +- 📒 **Driver information** (`driverInfo.txt`) +- 📒 **Operating system/hardware information** (`systeminfo.txt`) +- 📒 **System event log** (`systemlog.evtx`) These files will be exported to the "fail" directory, categorized by version number. ![Crash Files](imgs/crash.jpg) -### 1. Dump 文件 | Dump File - -Dump 文件包含崩溃时刻的内存快照，可用于调试分析： +### 1. Dump File The Dump file contains a memory snapshot at the moment of crash, which can be used for debugging analysis: ![Dump File](imgs/dump.png) -### 2. 版本信息文件 | Version Information File - -JSON 格式的详细崩溃报告，包含参数配置和 ProcDump 输出： +### 2. Version Information File Detailed crash report in JSON format, including parameter configuration and ProcDump output: ```json { - "Parameter": { - "TargetPath": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\", - "FailDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\fail\\1.0.0.3", - "BackupDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\1.0.0.3", - "ProcessNameOrId": "JsonTest.exe", - "DumpFileName": "1.0.0.3_fail.dmp", - "FailFileName": "1.0.0.3_fail.json", - "WorkModel": "Normal", - "ExtendedField": null - }, - "ProcdumpOutPutLines": [ +"Parameter": { +"TargetPath": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\", +"FailDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\fail\\1.0.0.3", +"BackupDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\1.0.0.3", +"ProcessNameOrId": "JsonTest.exe", +"DumpFileName": "1.0.0.3_fail.dmp", +"FailFileName": "1.0.0.3_fail.json", +"WorkModel": "Normal", +"ExtendedField": null +}, +"ProcdumpOutPutLines": [ "ProcDump v11.0 - Sysinternals process dump utility", "Copyright (C) 2009-2022 Mark Russinovich and Andrew Richards", "Sysinternals - www.sysinternals.com", @@ -274,9 +248,7 @@ Detailed crash report in JSON format, including parameter configuration and Proc } ``` -### 3. 驱动信息文件 | Driver Information File - -包含系统中所有驱动程序的详细信息： +### 3. Driver Information File Contains detailed information about all drivers in the system: @@ -285,12 +257,10 @@ Module Name Display Name Description Driver Type Sta ============ ====================== ====================== ============= ========== ========== ========== 360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK 360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK -// ...更多驱动信息 | ...more driver information +// ...more driver information ``` -### 4. 系统信息文件 | System Information File - -完整的操作系统和硬件配置信息： +### 4. System Information File Complete operating system and hardware configuration information: @@ -302,12 +272,10 @@ System Manufacturer: ASUS System Model: System Product Name Processor(s): Intel** Family * Model *** Total Physical Memory: 16,194 MB -// ...更多系统信息 | ...more system information +// ...more system information ``` -### 5. 系统事件日志 | System Event Log - -Windows 事件查看器格式的系统日志（.evtx 文件）： +### 5. System Event Log System log in Windows Event Viewer format (.evtx file): @@ -315,59 +283,48 @@ System log in Windows Event Viewer format (.evtx file): --- -## 注意事项与警告 | Notes and Warnings +## Notes and Warnings -### ⚠️ 重要提示 | Important Notes +### ⚠️ Important Notes -1. **工作模式选择 | Work Mode Selection** - - `Upgrade` 模式：专门用于与 GeneralUpdate 框架集成，包含内部逻辑处理 - - `Normal` 模式：可独立使用，适合监控任何 .NET 应用程序 +1. **Work Mode Selection** - `Upgrade` mode: Specifically for integration with GeneralUpdate framework, includes internal logic processing - `Normal` mode: Can be used independently, suitable for monitoring any .NET application -2. **权限要求 | Permission Requirements** - - Bowl 需要足够的权限来生成 Dump 文件和读取系统信息 - - 建议以管理员权限运行需要监控的应用程序 +2. **Permission Requirements** - Bowl requires sufficient permissions to generate Dump files and read system information - It is recommended to run the monitored application with administrator privileges -3. **磁盘空间 | Disk Space** - - Dump 文件可能占用大量磁盘空间（通常 50-200 MB） - - 确保 FailDirectory 所在磁盘有足够的可用空间 +3. **Disk Space** - Dump files may consume significant disk space (typically 50-200 MB) - Ensure sufficient available space on the disk where FailDirectory is located -4. **依赖项 | Dependencies** - - Bowl 使用 ProcDump 工具生成 Dump 文件，该工具已内置在组件中 - - 无需额外安装依赖项 +4. **Dependencies** - Bowl uses the ProcDump tool to generate Dump files, which is built into the component - No additional dependencies need to be installed -### 💡 最佳实践 | Best Practices +### 💡 Best Practices -- **版本号管理**：为每个版本使用独立的故障目录，便于问题追踪 -- **日志清理**：定期清理旧版本的故障信息，避免磁盘空间耗尽 -- **测试验证**：在生产环境部署前，在测试环境验证监控功能 - **Version Management**: Use separate failure directories for each version for easier issue tracking - **Log Cleanup**: Regularly clean up failure information from old versions to avoid disk space exhaustion - **Testing**: Verify monitoring functionality in a test environment before production deployment --- -## 适用平台 | Applicable Platforms +## Applicable Platforms -| 产品 Product | 版本 Version | -| ------------------ | ----------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | -| ASP.NET | Any | +| Product | Version | +| --------------- | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +| ASP.NET | Any | --- -## 相关资源 | Related Resources +## Related Resources -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) -- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) | [Watch Bilibili Tutorial](https://www.bilibili.com/video/BV1c8iyYZE7P) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) \ No newline at end of file +- **Example Code**: [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) +- **Video Tutorial**: [Watch Bilibili Tutorial](https://www.bilibili.com/video/BV1c8iyYZE7P) +- **Main Repository**: [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) From fc0f6fe3b73acb66852d5573c0df9574e98f3199 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:42:50 +0000 Subject: [PATCH 6/7] Create English-only documentation for ClientCore, Core, and Differential components Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com> --- website/docs/doc/GeneralUpdate.ClientCore.md | 329 ++++------ .../doc/GeneralUpdate.ClientCore.zh-CN.md | 604 ------------------ website/docs/doc/GeneralUpdate.Core.md | 308 ++++----- website/docs/doc/GeneralUpdate.Core.zh-CN.md | 565 ---------------- .../docs/doc/GeneralUpdate.Differential.md | 273 ++++---- .../doc/GeneralUpdate.Differential.zh-CN.md | 448 ------------- .../current/doc/GeneralUpdate.ClientCore.md | 291 ++++----- .../current/doc/GeneralUpdate.Core.md | 292 ++++----- .../current/doc/GeneralUpdate.Differential.md | 302 ++++----- 9 files changed, 741 insertions(+), 2671 deletions(-) delete mode 100644 website/docs/doc/GeneralUpdate.ClientCore.zh-CN.md delete mode 100644 website/docs/doc/GeneralUpdate.Core.zh-CN.md delete mode 100644 website/docs/doc/GeneralUpdate.Differential.zh-CN.md diff --git a/website/docs/doc/GeneralUpdate.ClientCore.md b/website/docs/doc/GeneralUpdate.ClientCore.md index 005337f..deb4ec3 100644 --- a/website/docs/doc/GeneralUpdate.ClientCore.md +++ b/website/docs/doc/GeneralUpdate.ClientCore.md @@ -4,14 +4,12 @@ sidebar_position: 4 # GeneralUpdate.ClientCore -## 组件概览 | Component Overview +## 组件概览 -**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一，提供了丰富的客户端更新功能。该组件运行在主应用程序中，负责检查更新、下载更新包、验证完整性，并在完成后启动升级助手（GeneralUpdate.Core）来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新，而不影响当前运行状态。 +**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一,提供了丰富的客户端更新功能。该组件运行在主应用程序中,负责检查更新、下载更新包、验证完整性,并在完成后启动升级助手(GeneralUpdate.Core)来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新,而不影响当前运行状态。 -**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` +**命名空间:** `GeneralUpdate.ClientCore` +**程序集:** `GeneralUpdate.ClientCore.dll` ```csharp public class GeneralClientBootstrap : AbstractBootstrap @@ -19,48 +17,44 @@ public class GeneralClientBootstrap : AbstractBootstrap LaunchAsync() ``` -#### SetConfig 方法 | SetConfig Method +#### SetConfig 方法 设置更新配置信息。 -Set update configuration information. - ```csharp public GeneralClientBootstrap SetConfig(Configinfo configinfo) ``` -#### Option 方法 | Option Method +#### Option 方法 设置更新选项。 -Set update options. - ```csharp public GeneralClientBootstrap Option(UpdateOption option, object value) ``` -#### SetBlacklist 方法 | SetBlacklist Method +#### SetBlacklist 方法 -设置更新黑名单，指定不需要更新的文件。 - -Set update blacklist to specify files that should not be updated. +设置更新黑名单,指定不需要更新的文件。 ```csharp public GeneralClientBootstrap SetBlacklist(List blackFiles = null, List blackFormats = null) ``` -#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method - -监听下载统计信息（速度、进度、剩余时间等）。 +#### AddListenerMultiDownloadStatistics 方法 -Listen for download statistics (speed, progress, remaining time, etc.). +监听下载统计信息(速度、进度、剩余时间等)。 ```csharp public GeneralClientBootstrap AddListenerMultiDownloadStatistics( Action callbackAction) ``` -#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method +#### AddListenerMultiDownloadCompleted 方法 监听单个更新包下载完成事件。 -Listen for single update package download completion event. - ```csharp public GeneralClientBootstrap AddListenerMultiDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method +#### AddListenerMultiAllDownloadCompleted 方法 监听所有下载任务完成事件。 -Listen for all download tasks completion event. - ```csharp public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method +#### AddListenerMultiDownloadError 方法 监听下载错误事件。 -Listen for download error events. - ```csharp public GeneralClientBootstrap AddListenerMultiDownloadError( Action callbackAction) ``` -#### AddListenerException 方法 | AddListenerException Method +#### AddListenerException 方法 监听更新过程中的所有异常。 -Listen for all exceptions during the update process. - ```csharp public GeneralClientBootstrap AddListenerException( Action callbackAction) ``` -#### AddCustomOption 方法 | AddCustomOption Method +#### AddCustomOption 方法 -添加自定义异步操作，可在更新前后执行自定义逻辑。 - -Add custom asynchronous operations that can execute custom logic before or after updates. +添加自定义异步操作,可在更新前后执行自定义逻辑。 ```csharp public GeneralClientBootstrap AddCustomOption(Func customFunc) ``` -#### SetCustomSkipOption 方法 | SetCustomSkipOption Method - -设置自定义跳过选项，允许用户决定是否继续更新。 +#### SetCustomSkipOption 方法 -Set custom skip options, allowing users to decide whether to continue with the update. +设置自定义跳过选项,允许用户决定是否继续更新。 ```csharp public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) @@ -283,151 +255,127 @@ public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) --- -## 配置类详解 | Configuration Class Details +## 配置类详解 -### Configinfo 类 | Configinfo Class +### Configinfo 类 ```csharp public class Configinfo { /// /// 更新检查 API 地址 - /// Update check API address /// public string UpdateUrl { get; set; } /// /// 更新状态报告 API 地址 - /// 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; } /// /// 当前产品分支的唯一 ID - /// Unique ID of the current product branch /// public string ProductId { get; set; } /// - /// Bowl 监控进程路径，更新完成后启动 Bowl 检查客户端是否正常启动 - /// Bowl monitoring process path, starts after updates to check if the client starts normally + /// Bowl 监控进程路径,更新完成后启动 Bowl 检查客户端是否正常启动 /// public string Bowl { get; set; } /// - /// HTTP 请求中用于传递 token 的 Scheme（如 Bearer） - /// Scheme used for passing token in HTTP requests (e.g., Bearer) + /// HTTP 请求中用于传递 token 的 Scheme(如 Bearer) /// public string Scheme { get; set; } /// /// HTTP 请求中用于身份验证的 Token - /// Token used for authentication in HTTP requests /// public string Token { get; set; } /// - /// Linux 平台下的脚本，用于在更新完成后为文件分配权限 - /// Script for Linux platform to assign permissions to files after update completion + /// Linux 平台下的脚本,用于在更新完成后为文件分配权限 /// public string Script { get; set; } } ``` -### UpdateOption 枚举 | UpdateOption Enum +### UpdateOption 枚举 ```csharp public enum UpdateOption { /// - /// 更新包文件格式（默认为 Zip） - /// Update package file format (default is Zip) + /// 更新包文件格式(默认为 Zip) /// Format, /// /// 压缩编码格式 - /// Compression encoding format /// Encoding, /// - /// 下载超时时间（秒）。如果不指定，默认超时时间为 30 秒 - /// Download timeout duration (seconds). Default is 30 seconds if not specified + /// 下载超时时间(秒)。如果不指定,默认超时时间为 30 秒 /// DownloadTimeOut, /// - /// 是否启用二进制差异更新功能，默认启用；设置为 false 则执行全量覆盖安装 - /// Whether to enable binary differential update function, enabled by default; - /// if set to false, full overwrite installation will be performed + /// 是否启用二进制差异更新功能,默认启用;设置为 false 则执行全量覆盖安装 /// Patch, /// - /// 是否在更新前启用备份功能，默认启用；设置为 false 则不进行备份 - /// Whether to enable backup function before update, enabled by default; - /// if set to false, no backup will be performed + /// 是否在更新前启用备份功能,默认启用;设置为 false 则不进行备份 /// BackUp } @@ -435,9 +383,9 @@ public enum UpdateOption --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：基本更新流程 | Example 1: Basic Update Process +### 示例 1:基本更新流程 ```csharp using GeneralUpdate.ClientCore; @@ -465,7 +413,7 @@ await new GeneralClientBootstrap() .LaunchAsync(); ``` -### 示例 2：带黑名单的更新 | Example 2: Update with Blacklist +### 示例 2:带黑名单的更新 ```csharp using GeneralUpdate.ClientCore; @@ -476,7 +424,7 @@ 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" } @@ -487,7 +435,7 @@ await new GeneralClientBootstrap() .LaunchAsync(); ``` -### 示例 3：自定义更新选项 | Example 3: Custom Update Options +### 示例 3:自定义更新选项 ```csharp using System.Text; @@ -504,18 +452,18 @@ var config = new Configinfo 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(); ``` -### 示例 4：完整的事件监听 | Example 4: Complete Event Listening +### 示例 4:完整的事件监听 ```csharp using GeneralUpdate.ClientCore; @@ -532,14 +480,14 @@ var config = new Configinfo await new GeneralClientBootstrap() .SetConfig(config) - // 下载统计 | Download statistics + // 下载统计 .AddListenerMultiDownloadStatistics((sender, args) => { var version = args.Version as VersionInfo; Console.WriteLine($"[{version.Version}] 进度: {args.ProgressPercentage}% | " + $"速度: {args.Speed} | 剩余: {args.Remaining}"); }) - // 单个下载完成 | Single download completed + // 单个下载完成 .AddListenerMultiDownloadCompleted((sender, args) => { var version = args.Version as VersionInfo; @@ -548,21 +496,21 @@ await new GeneralClientBootstrap() else Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); }) - // 所有下载完成 | All downloads completed + // 所有下载完成 .AddListenerMultiAllDownloadCompleted((sender, args) => { if (args.IsAllDownloadCompleted) - Console.WriteLine("✓ 所有更新包下载完成，准备安装..."); + Console.WriteLine("✓ 所有更新包下载完成,准备安装..."); else - Console.WriteLine($"✗ 下载失败，共 {args.FailedVersions.Count} 个版本失败"); + Console.WriteLine($"✗ 下载失败,共 {args.FailedVersions.Count} 个版本失败"); }) - // 下载错误 | Download error + // 下载错误 .AddListenerMultiDownloadError((sender, args) => { var version = args.Version as VersionInfo; Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); }) - // 异常处理 | Exception handling + // 异常处理 .AddListenerException((sender, args) => { Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); @@ -570,7 +518,7 @@ await new GeneralClientBootstrap() .LaunchAsync(); ``` -### 示例 5：自定义操作和跳过选项 | Example 5: Custom Operations and Skip Options +### 示例 5:自定义操作和跳过选项 ```csharp using GeneralUpdate.ClientCore; @@ -585,18 +533,18 @@ var config = new Configinfo await new GeneralClientBootstrap() .SetConfig(config) - // 添加自定义操作（更新前检查环境）| Add custom operation (check environment before update) + // 添加自定义操作(更新前检查环境) .AddCustomOption(async () => { Console.WriteLine("正在检查运行环境..."); await Task.Delay(1000); - // 检查磁盘空间、依赖项等 | Check disk space, dependencies, etc. + // 检查磁盘空间、依赖项等 Console.WriteLine("环境检查完成"); }) - // 设置用户跳过选项 | Set user skip option + // 设置用户跳过选项 .SetCustomSkipOption(() => { - Console.WriteLine("发现新版本，是否更新？(y/n)"); + Console.WriteLine("发现新版本,是否更新?(y/n)"); var input = Console.ReadLine(); return input?.ToLower() == "y"; }) @@ -605,58 +553,43 @@ await new GeneralClientBootstrap() --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **版本号格式 | Version Number Format** - - 版本号必须遵循语义化版本规范（如 1.0.0.0） +1. **版本号格式** + - 版本号必须遵循语义化版本规范(如 1.0.0.0) - 确保客户端和服务器端版本号格式一致 - - 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** +2. **网络连接** - 确保更新服务器地址可访问 - 建议实现重试机制处理网络波动 - - Ensure update server address is accessible - - Recommend implementing retry mechanism to handle network fluctuations -3. **进程管理 | Process Management** +3. **进程管理** - 更新过程会关闭主程序并启动升级助手 - 确保保存所有用户数据后再执行更新 - - 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** +4. **权限要求** - 在 Windows 上可能需要管理员权限来替换文件 - 在 Linux/macOS 上需要适当的文件系统权限 - - Administrator privileges may be required on Windows to replace files - - Appropriate file system permissions are required on Linux/macOS -5. **黑名单使用 | Blacklist Usage** +5. **黑名单使用** - 黑名单中的文件和目录不会被更新 - 常用于保护配置文件、用户数据等 - - Files and directories in the blacklist will not be updated - - Commonly used to protect configuration files, user data, etc. - -### 💡 最佳实践 | Best Practices - -- **备份策略**：始终启用 BackUp 选项，以便更新失败时可以回滚 -- **差异更新**：启用 Patch 选项以减少下载量和更新时间 -- **错误处理**：实现完整的异常监听和错误处理逻辑 -- **用户体验**：在更新前提示用户并允许选择更新时机 -- **测试验证**：在生产环境部署前充分测试更新流程 -- **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**: Prompt users before updating and allow them to choose update timing -- **Testing**: Thoroughly test the update process before production deployment + +### 💡 最佳实践 + +- **备份策略**:始终启用 BackUp 选项,以便更新失败时可以回滚 +- **差异更新**:启用 Patch 选项以减少下载量和更新时间 +- **错误处理**:实现完整的异常监听和错误处理逻辑 +- **用户体验**:在更新前提示用户并允许选择更新时机 +- **测试验证**:在生产环境部署前充分测试更新流程 --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | +| 产品 | 版本 | | ------------------ | -------------------- | | .NET | 5, 6, 7, 8, 9, 10 | | .NET Framework | 4.6.1 | @@ -665,7 +598,7 @@ await new GeneralClientBootstrap() --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **示例代码**:[查看 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.ClientCore.zh-CN.md b/website/docs/doc/GeneralUpdate.ClientCore.zh-CN.md deleted file mode 100644 index deb4ec3..0000000 --- a/website/docs/doc/GeneralUpdate.ClientCore.zh-CN.md +++ /dev/null @@ -1,604 +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. 灵活的配置选项 -- 黑名单机制(文件、格式、目录) -- 自定义更新策略和操作 -- 支持二进制差异更新和全量更新 - -### 3. 完整的事件通知 -- 下载进度、完成、错误事件 -- 支持用户自定义跳过更新选项 -- 异常和错误全程监控 - -### 4. 多平台支持 -- 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) -``` - -#### SetCustomSkipOption 方法 - -设置自定义跳过选项,允许用户决定是否继续更新。 - -```csharp -public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) -``` - ---- - -## 配置类详解 - -### 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; } -} -``` - -### UpdateOption 枚举 - -```csharp -public enum UpdateOption -{ - /// - /// 更新包文件格式(默认为 Zip) - /// - Format, - - /// - /// 压缩编码格式 - /// - Encoding, - - /// - /// 下载超时时间(秒)。如果不指定,默认超时时间为 30 秒 - /// - DownloadTimeOut, - - /// - /// 是否启用二进制差异更新功能,默认启用;设置为 false 则执行全量覆盖安装 - /// - Patch, - - /// - /// 是否在更新前启用备份功能,默认启用;设置为 false 则不进行备份 - /// - BackUp -} -``` - ---- - -## 实际使用示例 - -### 示例 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:自定义操作和跳过选项 - -```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) - // 添加自定义操作(更新前检查环境) - .AddCustomOption(async () => - { - Console.WriteLine("正在检查运行环境..."); - await Task.Delay(1000); - // 检查磁盘空间、依赖项等 - Console.WriteLine("环境检查完成"); - }) - // 设置用户跳过选项 - .SetCustomSkipOption(() => - { - Console.WriteLine("发现新版本,是否更新?(y/n)"); - var input = Console.ReadLine(); - return input?.ToLower() == "y"; - }) - .LaunchAsync(); -``` - ---- - -## 注意事项与警告 - -### ⚠️ 重要提示 - -1. **版本号格式** - - 版本号必须遵循语义化版本规范(如 1.0.0.0) - - 确保客户端和服务器端版本号格式一致 - -2. **网络连接** - - 确保更新服务器地址可访问 - - 建议实现重试机制处理网络波动 - -3. **进程管理** - - 更新过程会关闭主程序并启动升级助手 - - 确保保存所有用户数据后再执行更新 - -4. **权限要求** - - 在 Windows 上可能需要管理员权限来替换文件 - - 在 Linux/macOS 上需要适当的文件系统权限 - -5. **黑名单使用** - - 黑名单中的文件和目录不会被更新 - - 常用于保护配置文件、用户数据等 - -### 💡 最佳实践 - -- **备份策略**:始终启用 BackUp 选项,以便更新失败时可以回滚 -- **差异更新**:启用 Patch 选项以减少下载量和更新时间 -- **错误处理**:实现完整的异常监听和错误处理逻辑 -- **用户体验**:在更新前提示用户并允许选择更新时机 -- **测试验证**:在生产环境部署前充分测试更新流程 - ---- - -## 适用平台 - -| 产品 | 版本 | -| ------------------ | -------------------- | -| .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 09ce675..7e60681 100644 --- a/website/docs/doc/GeneralUpdate.Core.md +++ b/website/docs/doc/GeneralUpdate.Core.md @@ -4,14 +4,12 @@ sidebar_position: 5 # GeneralUpdate.Core -## 组件概览 | Component Overview +## 组件概览 -**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一，提供了完整的升级执行能力。与 ClientCore 不同，Core 组件作为独立的升级助手程序运行，负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式，Core 接收来自 ClientCore 的更新指令，并安全地完成主程序的升级任务。 +**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一,提供了完整的升级执行能力。与 ClientCore 不同,Core 组件作为独立的升级助手程序运行,负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式,Core 接收来自 ClientCore 的更新指令,并安全地完成主程序的升级任务。 -**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. - -**命名空间 | Namespace:** `GeneralUpdate.Core` -**程序集 | Assembly:** `GeneralUpdate.Core.dll` +**命名空间:** `GeneralUpdate.Core` +**程序集:** `GeneralUpdate.Core.dll` ```csharp public class GeneralUpdateBootstrap : AbstractBootstrap @@ -19,48 +17,44 @@ public class GeneralUpdateBootstrap : AbstractBootstrap LaunchAsync() ``` -**返回值 | Return Value:** -- 返回当前 GeneralUpdateBootstrap 实例，支持链式调用 -- Returns the current GeneralUpdateBootstrap instance, supporting method chaining +**返回值:** +- 返回当前 GeneralUpdateBootstrap 实例,支持链式调用 -#### Option 方法 | Option Method +#### Option 方法 设置升级选项。 -Set upgrade options. - ```csharp public GeneralUpdateBootstrap Option(UpdateOption option, object value) ``` -**参数 | Parameters:** -- `option`: 升级选项枚举 | Upgrade option enum -- `value`: 选项值 | Option value +**参数:** +- `option`: 升级选项枚举 +- `value`: 选项值 -**示例 | Example:** +**示例:** ```csharp -.Option(UpdateOption.Drive, true) // 启用驱动升级 | Enable driver upgrade +.Option(UpdateOption.Drive, true) // 启用驱动升级 ``` -#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method - -监听下载统计信息（速度、进度、剩余时间等）。 +#### AddListenerMultiDownloadStatistics 方法 -Listen for download statistics (speed, progress, remaining time, etc.). +监听下载统计信息(速度、进度、剩余时间等)。 ```csharp public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( Action callbackAction) ``` -#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method +#### AddListenerMultiDownloadCompleted 方法 监听单个更新包下载完成事件。 -Listen for single update package download completion event. - ```csharp public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method +#### AddListenerMultiAllDownloadCompleted 方法 监听所有版本下载完成事件。 -Listen for all version downloads completion event. - ```csharp public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method +#### AddListenerMultiDownloadError 方法 监听每个版本下载错误事件。 -Listen for download error events for each version. - ```csharp public GeneralUpdateBootstrap AddListenerMultiDownloadError( Action callbackAction) ``` -#### AddListenerException 方法 | AddListenerException Method +#### AddListenerException 方法 监听升级组件内部所有异常。 -Listen for all internal exceptions in the upgrade component. - ```csharp public GeneralUpdateBootstrap AddListenerException( Action callbackAction) ``` -#### SetFieldMappings 方法 | SetFieldMappings Method +#### SetFieldMappings 方法 -设置字段映射表，用于解析驱动包信息。 - -Set field mapping table for parsing driver package information. +设置字段映射表,用于解析驱动包信息。 ```csharp public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) ``` -**参数 | Parameters:** -- `fieldMappings`: 字段映射字典，键为英文字段名，值为本地化字段名 -- Field mapping dictionary, key is English field name, value is localized field name +**参数:** +- `fieldMappings`: 字段映射字典,键为英文字段名,值为本地化字段名 --- -## 配置类详解 | Configuration Class Details +## 配置类详解 -### UpdateOption 枚举 | UpdateOption Enum +### UpdateOption 枚举 ```csharp public enum UpdateOption { /// /// 是否启用驱动升级功能 - /// Whether to enable driver upgrade functionality /// Drive } ``` -### Packet 类 | Packet Class - -升级包信息类，由 ClientCore 通过参数传递给 Core： +### Packet 类 -Upgrade package information class, passed from ClientCore to Core via parameters: +升级包信息类,由 ClientCore 通过参数传递给 Core: ```csharp public class Packet { /// /// 主更新检查 API 地址 - /// Main update check API address /// public string MainUpdateUrl { get; set; } /// - /// 应用类型：1=客户端应用，2=更新应用 - /// Application type: 1=ClientApp, 2=UpdateApp + /// 应用类型:1=客户端应用,2=更新应用 /// public int AppType { get; set; } /// /// 更新检查 API 地址 - /// Update check API address /// public string UpdateUrl { get; set; } /// /// 需要启动的应用程序名称 - /// Name of the application to be launched /// public string AppName { get; set; } /// /// 主应用程序名称 - /// Main application name /// public string MainAppName { get; set; } /// - /// 更新包文件格式（默认为 Zip） - /// Update package file format (default is Zip) + /// 更新包文件格式(默认为 Zip) /// public string Format { get; set; } /// /// 是否需要升级更新应用 - /// Indicates if the update application needs to be upgraded /// public bool IsUpgradeUpdate { get; set; } /// /// 是否需要更新主应用 - /// Indicates if the main application needs to be updated /// public bool IsMainUpdate { get; set; } /// /// 更新日志网页 URL - /// Update log webpage URL /// public string UpdateLogUrl { get; set; } /// /// 需要更新的版本信息列表 - /// List of version information that needs updating /// public List UpdateVersions { get; set; } /// /// 文件操作编码格式 - /// File operation encoding format /// public Encoding Encoding { get; set; } /// - /// 下载超时时间（秒） - /// Download timeout duration (seconds) + /// 下载超时时间(秒) /// public int DownloadTimeOut { get; set; } /// - /// 应用密钥，与服务器约定 - /// Application secret key, agreed upon with the server + /// 应用密钥,与服务器约定 /// public string AppSecretKey { get; set; } /// /// 当前客户端版本 - /// Current client version /// public string ClientVersion { get; set; } /// /// 最新版本 - /// Latest version /// public string LastVersion { get; set; } /// - /// 安装路径（用于更新文件逻辑） - /// Installation path (used for update file logic) + /// 安装路径(用于更新文件逻辑) /// public string InstallPath { get; set; } /// /// 下载文件的临时存储路径 - /// Temporary storage path for downloaded files /// public string TempPath { get; set; } /// - /// 升级终端程序的配置参数（Base64 编码） - /// Configuration parameters for the upgrade terminal program (Base64 encoded) + /// 升级终端程序的配置参数(Base64 编码) /// public string ProcessBase64 { get; set; } /// - /// 当前策略所属平台（Windows/Linux/Mac） - /// Platform to which the current strategy belongs (Windows/Linux/Mac) + /// 当前策略所属平台(Windows/Linux/Mac) /// public string Platform { get; set; } /// /// 黑名单文件列表 - /// Files in the blacklist /// public List BlackFiles { get; set; } /// /// 黑名单文件格式列表 - /// File formats in the blacklist /// public List BlackFormats { get; set; } /// /// 是否启用驱动升级功能 - /// Indicates if the driver upgrade feature is enabled /// public bool DriveEnabled { get; set; } } @@ -401,9 +352,9 @@ public class Packet --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：基本升级流程 | Example 1: Basic Upgrade Process +### 示例 1:基本升级流程 ```csharp using GeneralUpdate.Common.Download; @@ -415,7 +366,7 @@ try { Console.WriteLine("升级程序初始化..."); - // 启动升级流程 | Launch upgrade process + // 启动升级流程 await new GeneralUpdateBootstrap() .AddListenerMultiDownloadStatistics((sender, args) => { @@ -428,7 +379,7 @@ try }) .LaunchAsync(); - Console.WriteLine("升级完成！"); + Console.WriteLine("升级完成!"); } catch (Exception e) { @@ -436,13 +387,13 @@ catch (Exception e) } ``` -### 示例 2：启用驱动升级 | Example 2: Enable Driver Upgrade +### 示例 2:启用驱动升级 ```csharp using GeneralUpdate.Core; using GeneralUpdate.Common.Internal.Bootstrap; -// 中文字段映射表 | Chinese field mapping table +// 中文字段映射表 var fieldMappingsCN = new Dictionary { { "DriverName", "驱动名称" }, @@ -452,9 +403,9 @@ var fieldMappingsCN = new Dictionary }; await new GeneralUpdateBootstrap() - // 设置字段映射表 | Set field mappings + // 设置字段映射表 .SetFieldMappings(fieldMappingsCN) - // 启用驱动更新 | Enable driver update + // 启用驱动更新 .Option(UpdateOption.Drive, true) .AddListenerException((sender, args) => { @@ -463,7 +414,7 @@ await new GeneralUpdateBootstrap() .LaunchAsync(); ``` -### 示例 3：完整事件监听 | Example 3: Complete Event Listening +### 示例 3:完整事件监听 ```csharp using GeneralUpdate.Core; @@ -471,7 +422,7 @@ using GeneralUpdate.Common.Download; using GeneralUpdate.Common.Shared.Object; await new GeneralUpdateBootstrap() - // 下载统计 | Download statistics + // 下载统计 .AddListenerMultiDownloadStatistics((sender, args) => { var version = args.Version as VersionInfo; @@ -481,37 +432,37 @@ await new GeneralUpdateBootstrap() Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); Console.WriteLine($" 剩余时间: {args.Remaining}"); }) - // 单个下载完成 | Single download completed + // 单个下载完成 .AddListenerMultiDownloadCompleted((sender, args) => { var version = args.Version as VersionInfo; string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; Console.WriteLine($"版本 {version.Version} 下载{status}"); }) - // 所有下载完成 | All downloads completed + // 所有下载完成 .AddListenerMultiAllDownloadCompleted((sender, args) => { if (args.IsAllDownloadCompleted) { - Console.WriteLine("✓ 所有版本下载完成，开始安装..."); + Console.WriteLine("✓ 所有版本下载完成,开始安装..."); } else { - Console.WriteLine($"✗ 下载失败，{args.FailedVersions.Count} 个版本失败："); + Console.WriteLine($"✗ 下载失败,{args.FailedVersions.Count} 个版本失败:"); foreach (var version in args.FailedVersions) { Console.WriteLine($" - {version}"); } } }) - // 下载错误 | Download error + // 下载错误 .AddListenerMultiDownloadError((sender, args) => { var version = args.Version as VersionInfo; Console.WriteLine($"✗ 版本 {version.Version} 错误:"); Console.WriteLine($" {args.Exception.Message}"); }) - // 异常处理 | Exception handling + // 异常处理 .AddListenerException((sender, args) => { Console.WriteLine("⚠ 升级过程异常:"); @@ -521,14 +472,14 @@ await new GeneralUpdateBootstrap() .LaunchAsync(); ``` -### 示例 4：自定义升级流程 | Example 4: Custom Upgrade Process +### 示例 4:自定义升级流程 ```csharp using GeneralUpdate.Core; using GeneralUpdate.Common.Download; using GeneralUpdate.Common.Shared.Object; -// 记录升级开始时间 | Record upgrade start time +// 记录升级开始时间 var startTime = DateTime.Now; var downloadedVersions = new List(); @@ -546,14 +497,14 @@ await new GeneralUpdateBootstrap() if (args.IsAllDownloadCompleted) { var duration = DateTime.Now - startTime; - Console.WriteLine($"升级完成！"); + Console.WriteLine($"升级完成!"); Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); } }) .AddListenerException((sender, args) => { - // 记录日志到文件 | Log to file + // 记录日志到文件 File.AppendAllText("upgrade_error.log", $"[{DateTime.Now}] {args.Exception}\n"); }) @@ -562,58 +513,43 @@ await new GeneralUpdateBootstrap() --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **进程隔离 | Process Isolation** - - Core 必须作为独立进程运行，不能在主程序中直接调用 - - 升级时主程序必须完全关闭，否则文件替换会失败 - - Core must run as an independent process, cannot be called directly in the main program - - The main program must be completely closed during upgrade, otherwise file replacement will fail +1. **进程隔离** + - Core 必须作为独立进程运行,不能在主程序中直接调用 + - 升级时主程序必须完全关闭,否则文件替换会失败 -2. **参数传递 | Parameter Passing** +2. **参数传递** - ClientCore 通过 Base64 编码的参数传递配置给 Core - 确保参数传递过程中不会被截断或损坏 - - ClientCore passes configuration to Core via Base64 encoded parameters - - Ensure parameters are not truncated or corrupted during passing -3. **文件权限 | File Permissions** +3. **文件权限** - 在 Windows 上可能需要管理员权限替换系统目录中的文件 - 在 Linux/macOS 上需要适当的文件系统权限 - - Administrator privileges may be required on Windows to replace files in system directories - - Appropriate file system permissions are required on Linux/macOS -4. **驱动升级 | Driver Upgrade** +4. **驱动升级** - 驱动升级功能需要系统级权限 - 建议在测试环境充分验证后再使用 - - Driver upgrade functionality requires system-level permissions - - Recommended to thoroughly validate in test environment before use - -5. **回滚机制 | Rollback Mechanism** - - Core 不直接提供回滚功能，但保留了备份文件 - - 如需回滚，可使用 ClientCore 的备份功能 - - Core does not directly provide rollback functionality, but backup files are preserved - - For rollback, use ClientCore's backup functionality - -### 💡 最佳实践 | Best Practices - -- **日志记录**：实现完整的异常监听，记录升级过程中的所有问题 -- **超时设置**：根据网络环境合理设置下载超时时间 -- **进度反馈**：向用户显示升级进度，提升用户体验 -- **错误处理**：升级失败时提供清晰的错误信息和解决方案 -- **测试验证**：在各种网络条件下测试升级流程的稳定性 -- **Logging**: Implement complete exception listening to record all issues during the upgrade process -- **Timeout Settings**: Set download timeout appropriately based on network environment -- **Progress Feedback**: Display upgrade progress to users to improve user experience -- **Error Handling**: Provide clear error messages and solutions when upgrade fails -- **Testing**: Test upgrade process stability under various network conditions + +5. **回滚机制** + - Core 不直接提供回滚功能,但保留了备份文件 + - 如需回滚,可使用 ClientCore 的备份功能 + +### 💡 最佳实践 + +- **日志记录**:实现完整的异常监听,记录升级过程中的所有问题 +- **超时设置**:根据网络环境合理设置下载超时时间 +- **进度反馈**:向用户显示升级进度,提升用户体验 +- **错误处理**:升级失败时提供清晰的错误信息和解决方案 +- **测试验证**:在各种网络条件下测试升级流程的稳定性 --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | +| 产品 | 版本 | | ------------------ | ----------------- | | .NET | 5, 6, 7, 8, 9 | | .NET Framework | 4.6.1 | @@ -622,8 +558,8 @@ await new GeneralUpdateBootstrap() --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) -- **相关组件**：[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) +- **示例代码**:[查看 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) diff --git a/website/docs/doc/GeneralUpdate.Core.zh-CN.md b/website/docs/doc/GeneralUpdate.Core.zh-CN.md deleted file mode 100644 index 7e60681..0000000 --- a/website/docs/doc/GeneralUpdate.Core.zh-CN.md +++ /dev/null @@ -1,565 +0,0 @@ ---- -sidebar_position: 5 ---- - -# GeneralUpdate.Core - -## 组件概览 - -**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一,提供了完整的升级执行能力。与 ClientCore 不同,Core 组件作为独立的升级助手程序运行,负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式,Core 接收来自 ClientCore 的更新指令,并安全地完成主程序的升级任务。 - -**命名空间:** `GeneralUpdate.Core` -**程序集:** `GeneralUpdate.Core.dll` - -```csharp -public class GeneralUpdateBootstrap : AbstractBootstrap -``` - ---- - -## 核心特性 - -### 1. 文件替换与版本管理 -- 安全的文件替换机制,避免文件占用问题 -- 支持多版本增量升级 -- 自动处理文件依赖关系 - -### 2. 驱动升级支持 -- 可选的驱动程序升级功能 -- 字段映射表配置 -- 安全的驱动安装流程 - -### 3. 完整的事件通知 -- 下载进度实时监控 -- 多版本下载管理 -- 异常和错误完整捕获 - -### 4. 跨平台支持 -- Windows、Linux、macOS 平台全支持 -- 自动平台检测和策略适配 - -![Multi Download](imgs/muti_donwload.png) - ---- - -## 快速开始 - -### 安装 - -通过 NuGet 安装 GeneralUpdate.Core: - -```bash -dotnet add package GeneralUpdate.Core -``` - -### 初始化与使用 - -以下示例展示了如何在升级助手程序中配置和启动升级流程: - -```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; -using GeneralUpdate.Core; - -try -{ - Console.WriteLine($"升级程序初始化,{DateTime.Now}!"); - Console.WriteLine("当前运行目录:" + Thread.GetDomain().BaseDirectory); - - // 启动升级流程 - await new GeneralUpdateBootstrap() - // 监听下载统计信息 - .AddListenerMultiDownloadStatistics(OnMultiDownloadStatistics) - // 监听单个下载完成 - .AddListenerMultiDownloadCompleted(OnMultiDownloadCompleted) - // 监听所有下载完成 - .AddListenerMultiAllDownloadCompleted(OnMultiAllDownloadCompleted) - // 监听下载错误 - .AddListenerMultiDownloadError(OnMultiDownloadError) - // 监听异常 - .AddListenerException(OnException) - // 启动异步升级 - .LaunchAsync(); - - Console.WriteLine($"升级程序已启动,{DateTime.Now}!"); - await Task.Delay(2000); -} -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 参考 - -### GeneralUpdateBootstrap 类方法 - -#### LaunchAsync 方法 - -异步启动升级流程。 - -```csharp -public async Task LaunchAsync() -``` - -**返回值:** -- 返回当前 GeneralUpdateBootstrap 实例,支持链式调用 - -#### Option 方法 - -设置升级选项。 - -```csharp -public GeneralUpdateBootstrap Option(UpdateOption option, object value) -``` - -**参数:** -- `option`: 升级选项枚举 -- `value`: 选项值 - -**示例:** -```csharp -.Option(UpdateOption.Drive, true) // 启用驱动升级 -``` - -#### AddListenerMultiDownloadStatistics 方法 - -监听下载统计信息(速度、进度、剩余时间等)。 - -```csharp -public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( - Action callbackAction) -``` - -#### AddListenerMultiDownloadCompleted 方法 - -监听单个更新包下载完成事件。 - -```csharp -public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiAllDownloadCompleted 方法 - -监听所有版本下载完成事件。 - -```csharp -public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( - Action callbackAction) -``` - -#### AddListenerMultiDownloadError 方法 - -监听每个版本下载错误事件。 - -```csharp -public GeneralUpdateBootstrap AddListenerMultiDownloadError( - Action callbackAction) -``` - -#### AddListenerException 方法 - -监听升级组件内部所有异常。 - -```csharp -public GeneralUpdateBootstrap AddListenerException( - Action callbackAction) -``` - -#### SetFieldMappings 方法 - -设置字段映射表,用于解析驱动包信息。 - -```csharp -public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) -``` - -**参数:** -- `fieldMappings`: 字段映射字典,键为英文字段名,值为本地化字段名 - ---- - -## 配置类详解 - -### UpdateOption 枚举 - -```csharp -public enum UpdateOption -{ - /// - /// 是否启用驱动升级功能 - /// - Drive -} -``` - -### Packet 类 - -升级包信息类,由 ClientCore 通过参数传递给 Core: - -```csharp -public class Packet -{ - /// - /// 主更新检查 API 地址 - /// - public string MainUpdateUrl { get; set; } - - /// - /// 应用类型:1=客户端应用,2=更新应用 - /// - public int AppType { get; set; } - - /// - /// 更新检查 API 地址 - /// - public string UpdateUrl { get; set; } - - /// - /// 需要启动的应用程序名称 - /// - public string AppName { get; set; } - - /// - /// 主应用程序名称 - /// - public string MainAppName { get; set; } - - /// - /// 更新包文件格式(默认为 Zip) - /// - public string Format { get; set; } - - /// - /// 是否需要升级更新应用 - /// - public bool IsUpgradeUpdate { get; set; } - - /// - /// 是否需要更新主应用 - /// - public bool IsMainUpdate { get; set; } - - /// - /// 更新日志网页 URL - /// - public string UpdateLogUrl { get; set; } - - /// - /// 需要更新的版本信息列表 - /// - public List UpdateVersions { get; set; } - - /// - /// 文件操作编码格式 - /// - public Encoding Encoding { get; set; } - - /// - /// 下载超时时间(秒) - /// - public int DownloadTimeOut { get; set; } - - /// - /// 应用密钥,与服务器约定 - /// - public string AppSecretKey { get; set; } - - /// - /// 当前客户端版本 - /// - public string ClientVersion { get; set; } - - /// - /// 最新版本 - /// - public string LastVersion { get; set; } - - /// - /// 安装路径(用于更新文件逻辑) - /// - public string InstallPath { get; set; } - - /// - /// 下载文件的临时存储路径 - /// - public string TempPath { get; set; } - - /// - /// 升级终端程序的配置参数(Base64 编码) - /// - public string ProcessBase64 { get; set; } - - /// - /// 当前策略所属平台(Windows/Linux/Mac) - /// - public string Platform { get; set; } - - /// - /// 黑名单文件列表 - /// - public List BlackFiles { get; set; } - - /// - /// 黑名单文件格式列表 - /// - public List BlackFormats { get; set; } - - /// - /// 是否启用驱动升级功能 - /// - public bool DriveEnabled { get; set; } -} -``` - ---- - -## 实际使用示例 - -### 示例 1:基本升级流程 - -```csharp -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Internal; -using GeneralUpdate.Common.Shared.Object; -using GeneralUpdate.Core; - -try -{ - Console.WriteLine("升级程序初始化..."); - - // 启动升级流程 - await new GeneralUpdateBootstrap() - .AddListenerMultiDownloadStatistics((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"[{version.Version}] 下载进度: {args.ProgressPercentage}%"); - }) - .AddListenerException((sender, args) => - { - Console.WriteLine($"升级异常: {args.Exception.Message}"); - }) - .LaunchAsync(); - - Console.WriteLine("升级完成!"); -} -catch (Exception e) -{ - Console.WriteLine($"升级失败: {e.Message}"); -} -``` - -### 示例 2:启用驱动升级 - -```csharp -using GeneralUpdate.Core; -using GeneralUpdate.Common.Internal.Bootstrap; - -// 中文字段映射表 -var fieldMappingsCN = new Dictionary -{ - { "DriverName", "驱动名称" }, - { "DriverVersion", "驱动版本" }, - { "DriverDescription", "驱动描述" }, - { "InstallPath", "安装路径" } -}; - -await new GeneralUpdateBootstrap() - // 设置字段映射表 - .SetFieldMappings(fieldMappingsCN) - // 启用驱动更新 - .Option(UpdateOption.Drive, true) - .AddListenerException((sender, args) => - { - Console.WriteLine($"升级异常: {args.Exception.Message}"); - }) - .LaunchAsync(); -``` - -### 示例 3:完整事件监听 - -```csharp -using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; - -await new GeneralUpdateBootstrap() - // 下载统计 - .AddListenerMultiDownloadStatistics((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"[{version.Version}]"); - Console.WriteLine($" 速度: {args.Speed}"); - Console.WriteLine($" 进度: {args.ProgressPercentage}%"); - Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); - Console.WriteLine($" 剩余时间: {args.Remaining}"); - }) - // 单个下载完成 - .AddListenerMultiDownloadCompleted((sender, args) => - { - var version = args.Version as VersionInfo; - string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; - Console.WriteLine($"版本 {version.Version} 下载{status}"); - }) - // 所有下载完成 - .AddListenerMultiAllDownloadCompleted((sender, args) => - { - if (args.IsAllDownloadCompleted) - { - Console.WriteLine("✓ 所有版本下载完成,开始安装..."); - } - else - { - Console.WriteLine($"✗ 下载失败,{args.FailedVersions.Count} 个版本失败:"); - foreach (var version in args.FailedVersions) - { - Console.WriteLine($" - {version}"); - } - } - }) - // 下载错误 - .AddListenerMultiDownloadError((sender, args) => - { - var version = args.Version as VersionInfo; - Console.WriteLine($"✗ 版本 {version.Version} 错误:"); - Console.WriteLine($" {args.Exception.Message}"); - }) - // 异常处理 - .AddListenerException((sender, args) => - { - Console.WriteLine("⚠ 升级过程异常:"); - Console.WriteLine($" 错误: {args.Exception.Message}"); - Console.WriteLine($" 堆栈: {args.Exception.StackTrace}"); - }) - .LaunchAsync(); -``` - -### 示例 4:自定义升级流程 - -```csharp -using GeneralUpdate.Core; -using GeneralUpdate.Common.Download; -using GeneralUpdate.Common.Shared.Object; - -// 记录升级开始时间 -var startTime = DateTime.Now; -var downloadedVersions = new List(); - -await new GeneralUpdateBootstrap() - .AddListenerMultiDownloadCompleted((sender, args) => - { - if (args.IsComplated) - { - var version = args.Version as VersionInfo; - downloadedVersions.Add(version.Version); - } - }) - .AddListenerMultiAllDownloadCompleted((sender, args) => - { - if (args.IsAllDownloadCompleted) - { - var duration = DateTime.Now - startTime; - Console.WriteLine($"升级完成!"); - Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); - Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); - } - }) - .AddListenerException((sender, args) => - { - // 记录日志到文件 - File.AppendAllText("upgrade_error.log", - $"[{DateTime.Now}] {args.Exception}\n"); - }) - .LaunchAsync(); -``` - ---- - -## 注意事项与警告 - -### ⚠️ 重要提示 - -1. **进程隔离** - - Core 必须作为独立进程运行,不能在主程序中直接调用 - - 升级时主程序必须完全关闭,否则文件替换会失败 - -2. **参数传递** - - ClientCore 通过 Base64 编码的参数传递配置给 Core - - 确保参数传递过程中不会被截断或损坏 - -3. **文件权限** - - 在 Windows 上可能需要管理员权限替换系统目录中的文件 - - 在 Linux/macOS 上需要适当的文件系统权限 - -4. **驱动升级** - - 驱动升级功能需要系统级权限 - - 建议在测试环境充分验证后再使用 - -5. **回滚机制** - - Core 不直接提供回滚功能,但保留了备份文件 - - 如需回滚,可使用 ClientCore 的备份功能 - -### 💡 最佳实践 - -- **日志记录**:实现完整的异常监听,记录升级过程中的所有问题 -- **超时设置**:根据网络环境合理设置下载超时时间 -- **进度反馈**:向用户显示升级进度,提升用户体验 -- **错误处理**:升级失败时提供清晰的错误信息和解决方案 -- **测试验证**:在各种网络条件下测试升级流程的稳定性 - ---- - -## 适用平台 - -| 产品 | 版本 | -| ------------------ | ----------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - ---- - -## 相关资源 - -- **示例代码**:[查看 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) diff --git a/website/docs/doc/GeneralUpdate.Differential.md b/website/docs/doc/GeneralUpdate.Differential.md index 7bf5a80..edb101a 100644 --- a/website/docs/doc/GeneralUpdate.Differential.md +++ b/website/docs/doc/GeneralUpdate.Differential.md @@ -4,14 +4,12 @@ sidebar_position: 6 # GeneralUpdate.Differential -## 组件概览 | Component Overview +## 组件概览 -**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法，可以精确识别两个版本之间的文件变化，生成高效的增量补丁包，并支持补丁还原操作。通过使用差异更新，可以显著减少更新包的大小和下载时间，特别适合频繁发布更新的应用场景。 +**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法,可以精确识别两个版本之间的文件变化,生成高效的增量补丁包,并支持补丁还原操作。通过使用差异更新,可以显著减少更新包的大小和下载时间,特别适合频繁发布更新的应用场景。 -**GeneralUpdate.Differential** is the core component responsible for binary differential updates in the GeneralUpdate framework. This component provides powerful differential algorithms that can accurately identify file changes between two versions, generate efficient incremental patch packages, and support patch restoration operations. By using differential updates, you can significantly reduce update package size and download time, making it particularly suitable for scenarios with frequent update releases. - -**命名空间 | Namespace:** `GeneralUpdate.Differential` -**程序集 | Assembly:** `GeneralUpdate.Core.dll` +**命名空间:** `GeneralUpdate.Differential` +**程序集:** `GeneralUpdate.Core.dll` ```csharp public sealed class DifferentialCore @@ -19,102 +17,94 @@ public sealed class DifferentialCore --- -## 核心特性 | Core Features +## 核心特性 -### 1. 增量识别 | Incremental Identification -- 精确识别新增、修改、删除的文件 | Accurately identify added, modified, and deleted files -- 智能文件版本对比 | Intelligent file version comparison -- 支持跳过指定文件和格式 | Support skipping specified files and formats +### 1. 增量识别 +- 精确识别新增、修改、删除的文件 +- 智能文件版本对比 +- 支持跳过指定文件和格式 -### 2. 二进制补丁生成 | Binary Patch Generation -- 高效的二进制差异算法 | Efficient binary differential algorithm -- 最小化补丁文件大小 | Minimize patch file size -- 快速补丁生成速度 | Fast patch generation speed +### 2. 二进制补丁生成 +- 高效的二进制差异算法 +- 最小化补丁文件大小 +- 快速补丁生成速度 -### 3. 补丁还原 | Patch Restoration -- 安全的补丁应用流程 | Safe patch application process -- 自动处理文件依赖关系 | Automatic handling of file dependencies -- 完整性验证机制 | Integrity verification mechanism +### 3. 补丁还原 +- 安全的补丁应用流程 +- 自动处理文件依赖关系 +- 完整性验证机制 -### 4. 黑名单支持 | Blacklist Support -- 文件级黑名单 | File-level blacklist -- 格式级黑名单 | Format-level blacklist -- 灵活的过滤规则 | Flexible filtering rules +### 4. 黑名单支持 +- 文件级黑名单 +- 格式级黑名单 +- 灵活的过滤规则 --- -## 快速开始 | Quick Start - -### 安装 | Installation +## 快速开始 -通过 NuGet 安装 GeneralUpdate.Differential（包含在 Core 包中）： +### 安装 -Install GeneralUpdate.Differential via NuGet (included in Core package): +通过 NuGet 安装 GeneralUpdate.Differential(包含在 Core 包中): ```bash dotnet add package GeneralUpdate.Core ``` -### 初始化与使用 | Initialization and Usage - -以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作： +### 初始化与使用 -The following example demonstrates how to use DifferentialCore for incremental identification and patch operations: +以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作: ```csharp using GeneralUpdate.Differential; -// 增量识别并生成二进制补丁 | Identify increments and generate binary patches -var sourcePath = @"D:\packet\app"; // 旧版本路径 | Old version path -var targetPath = @"D:\packet\release"; // 新版本路径 | New version path -var patchPath = @"D:\packet\patch"; // 补丁输出路径 | Patch output path +// 增量识别并生成二进制补丁 +var sourcePath = @"D:\packet\app"; // 旧版本路径 +var targetPath = @"D:\packet\release"; // 新版本路径 +var patchPath = @"D:\packet\patch"; // 补丁输出路径 await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); -// 应用补丁（还原） | Apply patches (restoration) +// 应用补丁(还原) await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); ``` --- -## 核心 API 参考 | Core API Reference +## 核心 API 参考 -### DifferentialCore 类 | DifferentialCore Class +### DifferentialCore 类 -#### Instance 属性 | Instance Property +#### Instance 属性 获取 DifferentialCore 的单例实例。 -Get the singleton instance of DifferentialCore. - ```csharp public static DifferentialCore Instance { get; } ``` -#### Clean 方法 | Clean Method - -执行增量识别、删除文件识别，并生成二进制补丁文件。 +#### Clean 方法 -Perform incremental identification, deleted file identification, and generate binary patch files. +执行增量识别、删除文件识别,并生成二进制补丁文件。 -**方法签名 | Method Signature:** +**方法签名:** ```csharp public async Task Clean(string sourcePath, string targetPath, string patchPath = null) ``` -**参数 | Parameters:** -- `sourcePath`: 旧版本文件夹路径 | Path to the old version folder -- `targetPath`: 新版本文件夹路径 | Path to the new version folder -- `patchPath`: 补丁文件输出目录（可选）| Directory to store discovered incremental update files (optional) +**参数:** +- `sourcePath`: 旧版本文件夹路径 +- `targetPath`: 新版本文件夹路径 +- `patchPath`: 补丁文件输出目录(可选) -**功能说明 | Function Description:** +**功能说明:** 1. 对比 sourcePath 和 targetPath 两个目录 2. 识别新增、修改、删除的文件 3. 为修改的文件生成二进制差异补丁 4. 将补丁和新增文件保存到 patchPath -**示例 | Example:** +**示例:** ```csharp // 生成从 v1.0.0 到 v1.1.0 的补丁包 var source = @"D:\MyApp\v1.0.0"; @@ -122,46 +112,44 @@ var target = @"D:\MyApp\v1.1.0"; var patch = @"D:\MyApp\patches\v1.1.0"; await DifferentialCore.Instance.Clean(source, target, patch); -// 结果：patch 目录包含所有必要的增量更新文件 +// 结果:patch 目录包含所有必要的增量更新文件 ``` -#### Dirty 方法 | Dirty Method - -应用补丁，将旧版本文件更新到新版本。 +#### Dirty 方法 -Apply patches to update old version files to the new version. +应用补丁,将旧版本文件更新到新版本。 -**方法签名 | Method Signature:** +**方法签名:** ```csharp public async Task Dirty(string appPath, string patchPath) ``` -**参数 | Parameters:** -- `appPath`: 客户端应用程序目录（当前版本）| Client application directory (current version) -- `patchPath`: 补丁文件路径 | Path to the patch files +**参数:** +- `appPath`: 客户端应用程序目录(当前版本) +- `patchPath`: 补丁文件路径 -**功能说明 | Function Description:** +**功能说明:** 1. 读取 patchPath 中的补丁文件 2. 将补丁应用到 appPath 中的对应文件 3. 处理新增文件的复制 4. 处理删除文件的移除 -**示例 | Example:** +**示例:** ```csharp // 将补丁应用到当前应用程序 var appDir = AppDomain.CurrentDomain.BaseDirectory; var patchDir = Path.Combine(appDir, "temp", "patches"); await DifferentialCore.Instance.Dirty(appDir, patchDir); -// 结果：应用程序更新到新版本 +// 结果:应用程序更新到新版本 ``` --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：基本补丁生成 | Example 1: Basic Patch Generation +### 示例 1:基本补丁生成 ```csharp using GeneralUpdate.Differential; @@ -170,33 +158,33 @@ public async Task GeneratePatchAsync() { try { - // 版本路径 | Version paths + // 版本路径 var oldVersion = @"D:\MyApp\1.0.0"; var newVersion = @"D:\MyApp\1.0.1"; var patchOutput = @"D:\MyApp\patches\1.0.1"; Console.WriteLine("开始生成补丁..."); - // 生成补丁 | Generate patches + // 生成补丁 await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); - Console.WriteLine($"补丁生成完成！输出目录：{patchOutput}"); + Console.WriteLine($"补丁生成完成!输出目录:{patchOutput}"); - // 显示补丁信息 | Display patch information + // 显示补丁信息 var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); - Console.WriteLine($"总补丁大小：{totalSize / 1024.0:F2} KB"); + Console.WriteLine($"总补丁大小:{totalSize / 1024.0:F2} KB"); } catch (Exception ex) { - Console.WriteLine($"补丁生成失败：{ex.Message}"); + Console.WriteLine($"补丁生成失败:{ex.Message}"); } } ``` -### 示例 2：应用补丁 | Example 2: Apply Patches +### 示例 2:应用补丁 ```csharp using GeneralUpdate.Differential; @@ -205,32 +193,32 @@ public async Task ApplyPatchAsync() { try { - // 应用程序目录 | Application directory + // 应用程序目录 var appDirectory = @"D:\MyApp\current"; - // 补丁目录 | Patch directory + // 补丁目录 var patchDirectory = @"D:\MyApp\patches\1.0.1"; Console.WriteLine("开始应用补丁..."); - // 验证补丁存在 | Verify patch exists + // 验证补丁存在 if (!Directory.Exists(patchDirectory)) { - throw new DirectoryNotFoundException($"补丁目录不存在：{patchDirectory}"); + throw new DirectoryNotFoundException($"补丁目录不存在:{patchDirectory}"); } - // 应用补丁 | Apply patches + // 应用补丁 await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); - Console.WriteLine("补丁应用成功！应用程序已更新到新版本。"); + Console.WriteLine("补丁应用成功!应用程序已更新到新版本。"); } catch (Exception ex) { - Console.WriteLine($"补丁应用失败：{ex.Message}"); + Console.WriteLine($"补丁应用失败:{ex.Message}"); } } ``` -### 示例 3：完整的补丁流程 | Example 3: Complete Patch Workflow +### 示例 3:完整的补丁流程 ```csharp using GeneralUpdate.Differential; @@ -238,7 +226,7 @@ using System.IO.Compression; public class PatchManager { - // 生成并打包补丁 | Generate and package patches + // 生成并打包补丁 public async Task CreatePatchPackageAsync( string oldVersionPath, string newVersionPath, @@ -246,14 +234,14 @@ public class PatchManager { try { - // 1. 生成补丁文件 | Generate patch files + // 1. 生成补丁文件 var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); Directory.CreateDirectory(tempPatchDir); Console.WriteLine($"正在生成补丁..."); await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); - // 2. 压缩补丁文件 | Compress patch files + // 2. 压缩补丁文件 var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); Console.WriteLine($"正在打包补丁..."); @@ -263,69 +251,69 @@ public class PatchManager ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, CompressionLevel.Optimal, false); - // 3. 清理临时文件 | Clean up temp files + // 3. 清理临时文件 Directory.Delete(tempPatchDir, true); var patchSize = new FileInfo(patchZipPath).Length; - Console.WriteLine($"补丁包创建成功：{patchZipPath}"); - Console.WriteLine($"补丁包大小：{patchSize / 1024.0:F2} KB"); + Console.WriteLine($"补丁包创建成功:{patchZipPath}"); + Console.WriteLine($"补丁包大小:{patchSize / 1024.0:F2} KB"); return patchZipPath; } catch (Exception ex) { - Console.WriteLine($"创建补丁包失败：{ex.Message}"); + Console.WriteLine($"创建补丁包失败:{ex.Message}"); throw; } } - // 解压并应用补丁 | Extract and apply patches + // 解压并应用补丁 public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) { try { - // 1. 解压补丁包 | Extract patch package + // 1. 解压补丁包 var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); Directory.CreateDirectory(tempExtractDir); Console.WriteLine($"正在解压补丁包..."); ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); - // 2. 应用补丁 | Apply patches + // 2. 应用补丁 Console.WriteLine($"正在应用补丁..."); await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); - // 3. 清理临时文件 | Clean up temp files + // 3. 清理临时文件 Directory.Delete(tempExtractDir, true); - Console.WriteLine($"补丁应用成功！"); + Console.WriteLine($"补丁应用成功!"); } catch (Exception ex) { - Console.WriteLine($"应用补丁包失败：{ex.Message}"); + Console.WriteLine($"应用补丁包失败:{ex.Message}"); throw; } } } -// 使用示例 | Usage example +// 使用示例 var manager = new PatchManager(); -// 创建补丁包 | Create patch package +// 创建补丁包 var patchZip = await manager.CreatePatchPackageAsync( @"D:\MyApp\1.0.0", @"D:\MyApp\1.0.1", @"D:\MyApp\releases" ); -// 应用补丁包 | Apply patch package +// 应用补丁包 await manager.ApplyPatchPackageAsync( @"D:\MyApp\current", patchZip ); ``` -### 示例 4：带进度显示的补丁操作 | Example 4: Patch Operations with Progress Display +### 示例 4:带进度显示的补丁操作 ```csharp using GeneralUpdate.Differential; @@ -342,18 +330,18 @@ public class ProgressivePatchManager { progress?.Report("开始扫描文件差异..."); - // 在实际场景中，可以在 Clean 前后添加进度报告 + // 在实际场景中,可以在 Clean 前后添加进度报告 await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); - progress?.Report("补丁生成完成！"); + progress?.Report("补丁生成完成!"); - // 统计信息 | Statistics + // 统计信息 var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); progress?.Report($"共生成 {files.Length} 个补丁文件"); } catch (Exception ex) { - progress?.Report($"错误：{ex.Message}"); + progress?.Report($"错误:{ex.Message}"); throw; } } @@ -369,17 +357,17 @@ public class ProgressivePatchManager await DifferentialCore.Instance.Dirty(appPath, patchPath); - progress?.Report("补丁应用成功！"); + progress?.Report("补丁应用成功!"); } catch (Exception ex) { - progress?.Report($"错误：{ex.Message}"); + progress?.Report($"错误:{ex.Message}"); throw; } } } -// 使用示例 | Usage example +// 使用示例 var manager = new ProgressivePatchManager(); var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); @@ -392,74 +380,59 @@ await manager.GeneratePatchWithProgressAsync( ``` --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **文件名限制 | File Name Restrictions** - - 不能包含同名但扩展名不同的文件（如 file.txt 和 file.log） +1. **文件名限制** + - 不能包含同名但扩展名不同的文件(如 file.txt 和 file.log) - 建议使用唯一的文件名命名规则 - - Cannot include files with the same name but different extensions (e.g., file.txt and file.log) - - Recommended to use unique file naming conventions -2. **目录结构 | Directory Structure** +2. **目录结构** - 源目录和目标目录的相对结构应保持一致 - 补丁生成时会保留目录层次关系 - - The relative structure of source and target directories should remain consistent - - Directory hierarchy is preserved during patch generation -3. **磁盘空间 | Disk Space** +3. **磁盘空间** - 确保有足够的磁盘空间存储补丁文件 - - 二进制差异补丁通常比完整文件小，但仍需要临时空间 - - Ensure sufficient disk space for storing patch files - - Binary differential patches are usually smaller than complete files, but still require temporary space + - 二进制差异补丁通常比完整文件小,但仍需要临时空间 -4. **文件占用 | File Locking** - - 应用补丁时，确保目标文件没有被其他进程占用 +4. **文件占用** + - 应用补丁时,确保目标文件没有被其他进程占用 - 建议在应用程序关闭后应用补丁 - - When applying patches, ensure target files are not locked by other processes - - Recommended to apply patches after the application is closed -5. **备份建议 | Backup Recommendations** +5. **备份建议** - 在应用补丁前建议备份原始文件 - 可以使用 ClientCore 的 BackUp 选项自动备份 - - Recommended to backup original files before applying patches - - Can use ClientCore's BackUp option for automatic backup -### 💡 最佳实践 | Best Practices +### 💡 最佳实践 -- **版本管理**：为每个版本维护独立的补丁包，便于版本追踪和回滚 -- **补丁验证**：生成补丁后进行验证测试，确保补丁可以正确应用 -- **增量更新**：优先使用差异更新而非全量更新，可节省 50%-90% 的下载量 -- **错误处理**：实现完整的异常捕获和错误恢复机制 -- **性能优化**：对于大文件，差异算法的性能优势更加明显 -- **Version Management**: Maintain separate patch packages for each version for easier version tracking and rollback -- **Patch Validation**: Perform validation testing after generating patches to ensure they can be applied correctly -- **Incremental Updates**: Prioritize differential updates over full updates, which can save 50%-90% of download size -- **Error Handling**: Implement complete exception capture and error recovery mechanisms -- **Performance Optimization**: For large files, the performance advantage of the differential algorithm is more pronounced +- **版本管理**:为每个版本维护独立的补丁包,便于版本追踪和回滚 +- **补丁验证**:生成补丁后进行验证测试,确保补丁可以正确应用 +- **增量更新**:优先使用差异更新而非全量更新,可节省 50%-90% 的下载量 +- **错误处理**:实现完整的异常捕获和错误恢复机制 +- **性能优化**:对于大文件,差异算法的性能优势更加明显 -### 🔍 工作原理 | How It Works +### 🔍 工作原理 -**Clean 方法工作流程 | Clean Method Workflow:** +**Clean 方法工作流程:** 1. 扫描源目录和目标目录中的所有文件 2. 比较文件的MD5哈希值以识别变化 -3. 对于修改的文件，使用二进制差异算法生成补丁 -4. 对于新增文件，直接复制到补丁目录 +3. 对于修改的文件,使用二进制差异算法生成补丁 +4. 对于新增文件,直接复制到补丁目录 5. 记录删除的文件列表 -**Dirty 方法工作流程 | Dirty Method Workflow:** +**Dirty 方法工作流程:** 1. 读取补丁目录中的所有文件 -2. 对于补丁文件，应用到对应的原文件上 -3. 对于新增文件，直接复制到应用目录 +2. 对于补丁文件,应用到对应的原文件上 +3. 对于新增文件,直接复制到应用目录 4. 根据删除列表移除相应文件 5. 验证更新完整性 --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | +| 产品 | 版本 | | ------------------ | ----------------- | | .NET | 5, 6, 7, 8, 9 | | .NET Framework | 4.6.1 | @@ -468,8 +441,8 @@ await manager.GeneratePatchWithProgressAsync( --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) -- **打包工具**：GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 | The GeneralUpdate.PacketTool project depends on this component for differential packaging +- **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) +- **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) +- **打包工具**:GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 diff --git a/website/docs/doc/GeneralUpdate.Differential.zh-CN.md b/website/docs/doc/GeneralUpdate.Differential.zh-CN.md deleted file mode 100644 index edb101a..0000000 --- a/website/docs/doc/GeneralUpdate.Differential.zh-CN.md +++ /dev/null @@ -1,448 +0,0 @@ ---- -sidebar_position: 6 ---- - -# GeneralUpdate.Differential - -## 组件概览 - -**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法,可以精确识别两个版本之间的文件变化,生成高效的增量补丁包,并支持补丁还原操作。通过使用差异更新,可以显著减少更新包的大小和下载时间,特别适合频繁发布更新的应用场景。 - -**命名空间:** `GeneralUpdate.Differential` -**程序集:** `GeneralUpdate.Core.dll` - -```csharp -public sealed class DifferentialCore -``` - ---- - -## 核心特性 - -### 1. 增量识别 -- 精确识别新增、修改、删除的文件 -- 智能文件版本对比 -- 支持跳过指定文件和格式 - -### 2. 二进制补丁生成 -- 高效的二进制差异算法 -- 最小化补丁文件大小 -- 快速补丁生成速度 - -### 3. 补丁还原 -- 安全的补丁应用流程 -- 自动处理文件依赖关系 -- 完整性验证机制 - -### 4. 黑名单支持 -- 文件级黑名单 -- 格式级黑名单 -- 灵活的过滤规则 - ---- - -## 快速开始 - -### 安装 - -通过 NuGet 安装 GeneralUpdate.Differential(包含在 Core 包中): - -```bash -dotnet add package GeneralUpdate.Core -``` - -### 初始化与使用 - -以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作: - -```csharp -using GeneralUpdate.Differential; - -// 增量识别并生成二进制补丁 -var sourcePath = @"D:\packet\app"; // 旧版本路径 -var targetPath = @"D:\packet\release"; // 新版本路径 -var patchPath = @"D:\packet\patch"; // 补丁输出路径 - -await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); - -// 应用补丁(还原) -await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); -``` - ---- - -## 核心 API 参考 - -### DifferentialCore 类 - -#### Instance 属性 - -获取 DifferentialCore 的单例实例。 - -```csharp -public static DifferentialCore Instance { get; } -``` - -#### Clean 方法 - -执行增量识别、删除文件识别,并生成二进制补丁文件。 - -**方法签名:** - -```csharp -public async Task Clean(string sourcePath, string targetPath, string patchPath = null) -``` - -**参数:** -- `sourcePath`: 旧版本文件夹路径 -- `targetPath`: 新版本文件夹路径 -- `patchPath`: 补丁文件输出目录(可选) - -**功能说明:** -1. 对比 sourcePath 和 targetPath 两个目录 -2. 识别新增、修改、删除的文件 -3. 为修改的文件生成二进制差异补丁 -4. 将补丁和新增文件保存到 patchPath - -**示例:** -```csharp -// 生成从 v1.0.0 到 v1.1.0 的补丁包 -var source = @"D:\MyApp\v1.0.0"; -var target = @"D:\MyApp\v1.1.0"; -var patch = @"D:\MyApp\patches\v1.1.0"; - -await DifferentialCore.Instance.Clean(source, target, patch); -// 结果:patch 目录包含所有必要的增量更新文件 -``` - -#### Dirty 方法 - -应用补丁,将旧版本文件更新到新版本。 - -**方法签名:** - -```csharp -public async Task Dirty(string appPath, string patchPath) -``` - -**参数:** -- `appPath`: 客户端应用程序目录(当前版本) -- `patchPath`: 补丁文件路径 - -**功能说明:** -1. 读取 patchPath 中的补丁文件 -2. 将补丁应用到 appPath 中的对应文件 -3. 处理新增文件的复制 -4. 处理删除文件的移除 - -**示例:** -```csharp -// 将补丁应用到当前应用程序 -var appDir = AppDomain.CurrentDomain.BaseDirectory; -var patchDir = Path.Combine(appDir, "temp", "patches"); - -await DifferentialCore.Instance.Dirty(appDir, patchDir); -// 结果:应用程序更新到新版本 -``` - ---- - -## 实际使用示例 - -### 示例 1:基本补丁生成 - -```csharp -using GeneralUpdate.Differential; - -public async Task GeneratePatchAsync() -{ - try - { - // 版本路径 - var oldVersion = @"D:\MyApp\1.0.0"; - var newVersion = @"D:\MyApp\1.0.1"; - var patchOutput = @"D:\MyApp\patches\1.0.1"; - - Console.WriteLine("开始生成补丁..."); - - // 生成补丁 - await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); - - Console.WriteLine($"补丁生成完成!输出目录:{patchOutput}"); - - // 显示补丁信息 - var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); - Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); - - long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); - Console.WriteLine($"总补丁大小:{totalSize / 1024.0:F2} KB"); - } - catch (Exception ex) - { - Console.WriteLine($"补丁生成失败:{ex.Message}"); - } -} -``` - -### 示例 2:应用补丁 - -```csharp -using GeneralUpdate.Differential; - -public async Task ApplyPatchAsync() -{ - try - { - // 应用程序目录 - var appDirectory = @"D:\MyApp\current"; - // 补丁目录 - var patchDirectory = @"D:\MyApp\patches\1.0.1"; - - Console.WriteLine("开始应用补丁..."); - - // 验证补丁存在 - if (!Directory.Exists(patchDirectory)) - { - throw new DirectoryNotFoundException($"补丁目录不存在:{patchDirectory}"); - } - - // 应用补丁 - await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); - - Console.WriteLine("补丁应用成功!应用程序已更新到新版本。"); - } - catch (Exception ex) - { - Console.WriteLine($"补丁应用失败:{ex.Message}"); - } -} -``` - -### 示例 3:完整的补丁流程 - -```csharp -using GeneralUpdate.Differential; -using System.IO.Compression; - -public class PatchManager -{ - // 生成并打包补丁 - public async Task CreatePatchPackageAsync( - string oldVersionPath, - string newVersionPath, - string outputPath) - { - try - { - // 1. 生成补丁文件 - var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); - Directory.CreateDirectory(tempPatchDir); - - Console.WriteLine($"正在生成补丁..."); - await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); - - // 2. 压缩补丁文件 - var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); - Console.WriteLine($"正在打包补丁..."); - - if (File.Exists(patchZipPath)) - File.Delete(patchZipPath); - - ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, - CompressionLevel.Optimal, false); - - // 3. 清理临时文件 - Directory.Delete(tempPatchDir, true); - - var patchSize = new FileInfo(patchZipPath).Length; - Console.WriteLine($"补丁包创建成功:{patchZipPath}"); - Console.WriteLine($"补丁包大小:{patchSize / 1024.0:F2} KB"); - - return patchZipPath; - } - catch (Exception ex) - { - Console.WriteLine($"创建补丁包失败:{ex.Message}"); - throw; - } - } - - // 解压并应用补丁 - public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) - { - try - { - // 1. 解压补丁包 - var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); - Directory.CreateDirectory(tempExtractDir); - - Console.WriteLine($"正在解压补丁包..."); - ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); - - // 2. 应用补丁 - Console.WriteLine($"正在应用补丁..."); - await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); - - // 3. 清理临时文件 - Directory.Delete(tempExtractDir, true); - - Console.WriteLine($"补丁应用成功!"); - } - catch (Exception ex) - { - Console.WriteLine($"应用补丁包失败:{ex.Message}"); - throw; - } - } -} - -// 使用示例 -var manager = new PatchManager(); - -// 创建补丁包 -var patchZip = await manager.CreatePatchPackageAsync( - @"D:\MyApp\1.0.0", - @"D:\MyApp\1.0.1", - @"D:\MyApp\releases" -); - -// 应用补丁包 -await manager.ApplyPatchPackageAsync( - @"D:\MyApp\current", - patchZip -); -``` - -### 示例 4:带进度显示的补丁操作 - -```csharp -using GeneralUpdate.Differential; - -public class ProgressivePatchManager -{ - public async Task GeneratePatchWithProgressAsync( - string sourcePath, - string targetPath, - string patchPath, - IProgress progress) - { - try - { - progress?.Report("开始扫描文件差异..."); - - // 在实际场景中,可以在 Clean 前后添加进度报告 - await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); - - progress?.Report("补丁生成完成!"); - - // 统计信息 - var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); - progress?.Report($"共生成 {files.Length} 个补丁文件"); - } - catch (Exception ex) - { - progress?.Report($"错误:{ex.Message}"); - throw; - } - } - - public async Task ApplyPatchWithProgressAsync( - string appPath, - string patchPath, - IProgress progress) - { - try - { - progress?.Report("开始应用补丁..."); - - await DifferentialCore.Instance.Dirty(appPath, patchPath); - - progress?.Report("补丁应用成功!"); - } - catch (Exception ex) - { - progress?.Report($"错误:{ex.Message}"); - throw; - } - } -} - -// 使用示例 -var manager = new ProgressivePatchManager(); -var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); - -await manager.GeneratePatchWithProgressAsync( - @"D:\MyApp\1.0.0", - @"D:\MyApp\1.0.1", - @"D:\MyApp\patches\1.0.1", - progress -); -``` ---- - -## 注意事项与警告 - -### ⚠️ 重要提示 - -1. **文件名限制** - - 不能包含同名但扩展名不同的文件(如 file.txt 和 file.log) - - 建议使用唯一的文件名命名规则 - -2. **目录结构** - - 源目录和目标目录的相对结构应保持一致 - - 补丁生成时会保留目录层次关系 - -3. **磁盘空间** - - 确保有足够的磁盘空间存储补丁文件 - - 二进制差异补丁通常比完整文件小,但仍需要临时空间 - -4. **文件占用** - - 应用补丁时,确保目标文件没有被其他进程占用 - - 建议在应用程序关闭后应用补丁 - -5. **备份建议** - - 在应用补丁前建议备份原始文件 - - 可以使用 ClientCore 的 BackUp 选项自动备份 - -### 💡 最佳实践 - -- **版本管理**:为每个版本维护独立的补丁包,便于版本追踪和回滚 -- **补丁验证**:生成补丁后进行验证测试,确保补丁可以正确应用 -- **增量更新**:优先使用差异更新而非全量更新,可节省 50%-90% 的下载量 -- **错误处理**:实现完整的异常捕获和错误恢复机制 -- **性能优化**:对于大文件,差异算法的性能优势更加明显 - -### 🔍 工作原理 - -**Clean 方法工作流程:** -1. 扫描源目录和目标目录中的所有文件 -2. 比较文件的MD5哈希值以识别变化 -3. 对于修改的文件,使用二进制差异算法生成补丁 -4. 对于新增文件,直接复制到补丁目录 -5. 记录删除的文件列表 - -**Dirty 方法工作流程:** -1. 读取补丁目录中的所有文件 -2. 对于补丁文件,应用到对应的原文件上 -3. 对于新增文件,直接复制到应用目录 -4. 根据删除列表移除相应文件 -5. 验证更新完整性 - ---- - -## 适用平台 - -| 产品 | 版本 | -| ------------------ | ----------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | - ---- - -## 相关资源 - -- **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) -- **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) -- **打包工具**:GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 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 index 005337f..f63b17c 100644 --- 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 @@ -4,14 +4,12 @@ sidebar_position: 4 # GeneralUpdate.ClientCore -## 组件概览 | Component Overview - -**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一，提供了丰富的客户端更新功能。该组件运行在主应用程序中，负责检查更新、下载更新包、验证完整性，并在完成后启动升级助手（GeneralUpdate.Core）来执行实际的文件替换操作。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` +**Namespace:** `GeneralUpdate.ClientCore` +**Assembly:** `GeneralUpdate.ClientCore.dll` ```csharp public class GeneralClientBootstrap : AbstractBootstrap @@ -19,36 +17,34 @@ public class GeneralClientBootstrap : AbstractBootstrap LaunchAsync() ``` -#### SetConfig 方法 | SetConfig Method - -设置更新配置信息。 +#### SetConfig Method Set update configuration information. @@ -185,9 +175,7 @@ Set update configuration information. public GeneralClientBootstrap SetConfig(Configinfo configinfo) ``` -#### Option 方法 | Option Method - -设置更新选项。 +#### Option Method Set update options. @@ -195,9 +183,7 @@ Set update options. public GeneralClientBootstrap Option(UpdateOption option, object value) ``` -#### SetBlacklist 方法 | SetBlacklist Method - -设置更新黑名单，指定不需要更新的文件。 +#### SetBlacklist Method Set update blacklist to specify files that should not be updated. @@ -206,9 +192,7 @@ public GeneralClientBootstrap SetBlacklist(List blackFiles = null, List blackFormats = null) ``` -#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method - -监听下载统计信息（速度、进度、剩余时间等）。 +#### AddListenerMultiDownloadStatistics Method Listen for download statistics (speed, progress, remaining time, etc.). @@ -217,9 +201,7 @@ public GeneralClientBootstrap AddListenerMultiDownloadStatistics( Action callbackAction) ``` -#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method - -监听单个更新包下载完成事件。 +#### AddListenerMultiDownloadCompleted Method Listen for single update package download completion event. @@ -228,9 +210,7 @@ public GeneralClientBootstrap AddListenerMultiDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method - -监听所有下载任务完成事件。 +#### AddListenerMultiAllDownloadCompleted Method Listen for all download tasks completion event. @@ -239,9 +219,7 @@ public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method - -监听下载错误事件。 +#### AddListenerMultiDownloadError Method Listen for download error events. @@ -250,9 +228,7 @@ public GeneralClientBootstrap AddListenerMultiDownloadError( Action callbackAction) ``` -#### AddListenerException 方法 | AddListenerException Method - -监听更新过程中的所有异常。 +#### AddListenerException Method Listen for all exceptions during the update process. @@ -261,9 +237,7 @@ public GeneralClientBootstrap AddListenerException( Action callbackAction) ``` -#### AddCustomOption 方法 | AddCustomOption Method - -添加自定义异步操作，可在更新前后执行自定义逻辑。 +#### AddCustomOption Method Add custom asynchronous operations that can execute custom logic before or after updates. @@ -271,9 +245,7 @@ Add custom asynchronous operations that can execute custom logic before or after public GeneralClientBootstrap AddCustomOption(Func customFunc) ``` -#### SetCustomSkipOption 方法 | SetCustomSkipOption Method - -设置自定义跳过选项，允许用户决定是否继续更新。 +#### SetCustomSkipOption Method Set custom skip options, allowing users to decide whether to continue with the update. @@ -283,149 +255,127 @@ public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) --- -## 配置类详解 | Configuration Class Details +## Configuration Class Details -### Configinfo 类 | Configinfo Class +### Configinfo Class ```csharp public class Configinfo { /// - /// 更新检查 API 地址 /// Update check API address /// public string UpdateUrl { get; set; } /// - /// 更新状态报告 API 地址 /// 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; } /// - /// 当前产品分支的唯一 ID /// Unique ID of the current product branch /// public string ProductId { get; set; } /// - /// Bowl 监控进程路径，更新完成后启动 Bowl 检查客户端是否正常启动 /// Bowl monitoring process path, starts after updates to check if the client starts normally /// public string Bowl { get; set; } /// - /// HTTP 请求中用于传递 token 的 Scheme（如 Bearer） /// Scheme used for passing token in HTTP requests (e.g., Bearer) /// public string Scheme { get; set; } /// - /// HTTP 请求中用于身份验证的 Token /// Token used for authentication in HTTP requests /// public string Token { get; set; } /// - /// Linux 平台下的脚本，用于在更新完成后为文件分配权限 /// Script for Linux platform to assign permissions to files after update completion /// public string Script { get; set; } } ``` -### UpdateOption 枚举 | UpdateOption Enum +### UpdateOption Enum ```csharp public enum UpdateOption { /// - /// 更新包文件格式（默认为 Zip） /// Update package file format (default is Zip) /// Format, /// - /// 压缩编码格式 /// Compression encoding format /// Encoding, /// - /// 下载超时时间（秒）。如果不指定，默认超时时间为 30 秒 /// Download timeout duration (seconds). Default is 30 seconds if not specified /// DownloadTimeOut, /// - /// 是否启用二进制差异更新功能，默认启用；设置为 false 则执行全量覆盖安装 /// Whether to enable binary differential update function, enabled by default; /// if set to false, full overwrite installation will be performed /// Patch, /// - /// 是否在更新前启用备份功能，默认启用；设置为 false 则不进行备份 /// Whether to enable backup function before update, enabled by default; /// if set to false, no backup will be performed /// @@ -435,9 +385,9 @@ public enum UpdateOption --- -## 实际使用示例 | Practical Usage Examples +## Practical Usage Examples -### 示例 1：基本更新流程 | Example 1: Basic Update Process +### Example 1: Basic Update Process ```csharp using GeneralUpdate.ClientCore; @@ -460,12 +410,12 @@ await new GeneralClientBootstrap() .SetConfig(config) .AddListenerException((sender, args) => { - Console.WriteLine($"更新异常: {args.Exception.Message}"); + Console.WriteLine($"Update exception: {args.Exception.Message}"); }) .LaunchAsync(); ``` -### 示例 2：带黑名单的更新 | Example 2: Update with Blacklist +### Example 2: Update with Blacklist ```csharp using GeneralUpdate.ClientCore; @@ -476,7 +426,7 @@ var config = new Configinfo UpdateUrl = "http://your-server.com/api/update/check", ClientVersion = "1.0.0.0", InstallPath = AppDomain.CurrentDomain.BaseDirectory, - // 黑名单配置 | Blacklist configuration + // Blacklist configuration BlackFiles = new List { "config.json", "userdata.db" }, BlackFormats = new List { ".log", ".cache" }, SkipDirectorys = new List { "logs", "temp" } @@ -487,7 +437,7 @@ await new GeneralClientBootstrap() .LaunchAsync(); ``` -### 示例 3：自定义更新选项 | Example 3: Custom Update Options +### Example 3: Custom Update Options ```csharp using System.Text; @@ -504,18 +454,18 @@ var config = new Configinfo await new GeneralClientBootstrap() .SetConfig(config) - // 设置下载超时 | Set download timeout + // Set download timeout .Option(UpdateOption.DownloadTimeOut, 120) - // 设置编码格式 | Set encoding format + // Set encoding format .Option(UpdateOption.Encoding, Encoding.UTF8) - // 启用二进制差异更新 | Enable binary differential update + // Enable binary differential update .Option(UpdateOption.Patch, true) - // 启用备份 | Enable backup + // Enable backup .Option(UpdateOption.BackUp, true) .LaunchAsync(); ``` -### 示例 4：完整的事件监听 | Example 4: Complete Event Listening +### Example 4: Complete Event Listening ```csharp using GeneralUpdate.ClientCore; @@ -532,45 +482,45 @@ var config = new Configinfo await new GeneralClientBootstrap() .SetConfig(config) - // 下载统计 | Download statistics + // Download statistics .AddListenerMultiDownloadStatistics((sender, args) => { var version = args.Version as VersionInfo; - Console.WriteLine($"[{version.Version}] 进度: {args.ProgressPercentage}% | " + - $"速度: {args.Speed} | 剩余: {args.Remaining}"); + Console.WriteLine($"[{version.Version}] Progress: {args.ProgressPercentage}% | " + + $"Speed: {args.Speed} | Remaining: {args.Remaining}"); }) - // 单个下载完成 | Single download completed + // Single download completed .AddListenerMultiDownloadCompleted((sender, args) => { var version = args.Version as VersionInfo; if (args.IsComplated) - Console.WriteLine($"✓ 版本 {version.Version} 下载成功"); + Console.WriteLine($"✓ Version {version.Version} download succeeded"); else - Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); + Console.WriteLine($"✗ Version {version.Version} download failed"); }) - // 所有下载完成 | All downloads completed + // All downloads completed .AddListenerMultiAllDownloadCompleted((sender, args) => { if (args.IsAllDownloadCompleted) - Console.WriteLine("✓ 所有更新包下载完成，准备安装..."); + Console.WriteLine("✓ All update packages downloaded, preparing installation..."); else - Console.WriteLine($"✗ 下载失败，共 {args.FailedVersions.Count} 个版本失败"); + Console.WriteLine($"✗ Download failed, {args.FailedVersions.Count} versions failed"); }) - // 下载错误 | Download error + // Download error .AddListenerMultiDownloadError((sender, args) => { var version = args.Version as VersionInfo; - Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); + Console.WriteLine($"✗ Version {version.Version} download error: {args.Exception.Message}"); }) - // 异常处理 | Exception handling + // Exception handling .AddListenerException((sender, args) => { - Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); + Console.WriteLine($"⚠ Update exception: {args.Exception.Message}\n{args.Exception.StackTrace}"); }) .LaunchAsync(); ``` -### 示例 5：自定义操作和跳过选项 | Example 5: Custom Operations and Skip Options +### Example 5: Custom Operations and Skip Options ```csharp using GeneralUpdate.ClientCore; @@ -585,18 +535,18 @@ var config = new Configinfo await new GeneralClientBootstrap() .SetConfig(config) - // 添加自定义操作（更新前检查环境）| Add custom operation (check environment before update) + // Add custom operation (check environment before update) .AddCustomOption(async () => { - Console.WriteLine("正在检查运行环境..."); + Console.WriteLine("Checking runtime environment..."); await Task.Delay(1000); - // 检查磁盘空间、依赖项等 | Check disk space, dependencies, etc. - Console.WriteLine("环境检查完成"); + // Check disk space, dependencies, etc. + Console.WriteLine("Environment check completed"); }) - // 设置用户跳过选项 | Set user skip option + // Set user skip option .SetCustomSkipOption(() => { - Console.WriteLine("发现新版本，是否更新？(y/n)"); + Console.WriteLine("New version found, update now? (y/n)"); var input = Console.ReadLine(); return input?.ToLower() == "y"; }) @@ -605,47 +555,32 @@ await new GeneralClientBootstrap() --- -## 注意事项与警告 | Notes and Warnings +## Notes and Warnings -### ⚠️ 重要提示 | Important Notes +### ⚠️ Important Notes -1. **版本号格式 | Version Number Format** - - 版本号必须遵循语义化版本规范（如 1.0.0.0） - - 确保客户端和服务器端版本号格式一致 +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** - - 确保更新服务器地址可访问 - - 建议实现重试机制处理网络波动 +2. **Network Connection** - Ensure update server address is accessible - Recommend implementing retry mechanism to handle network fluctuations -3. **进程管理 | Process Management** - - 更新过程会关闭主程序并启动升级助手 - - 确保保存所有用户数据后再执行更新 +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** - - 在 Windows 上可能需要管理员权限来替换文件 - - 在 Linux/macOS 上需要适当的文件系统权限 +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** - - 黑名单中的文件和目录不会被更新 - - 常用于保护配置文件、用户数据等 +5. **Blacklist Usage** - Files and directories in the blacklist will not be updated - Commonly used to protect configuration files, user data, etc. -### 💡 最佳实践 | Best Practices +### 💡 Best Practices -- **备份策略**：始终启用 BackUp 选项，以便更新失败时可以回滚 -- **差异更新**：启用 Patch 选项以减少下载量和更新时间 -- **错误处理**：实现完整的异常监听和错误处理逻辑 -- **用户体验**：在更新前提示用户并允许选择更新时机 -- **测试验证**：在生产环境部署前充分测试更新流程 - **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 @@ -654,10 +589,10 @@ await new GeneralClientBootstrap() --- -## 适用平台 | Applicable Platforms +## Applicable Platforms -| 产品 Product | 版本 Version | -| ------------------ | -------------------- | +| Product | Version | +| -------------- | ---------------- | | .NET | 5, 6, 7, 8, 9, 10 | | .NET Framework | 4.6.1 | | .NET Standard | 2.0 | @@ -665,7 +600,7 @@ await new GeneralClientBootstrap() --- -## 相关资源 | Related Resources +## Related Resources -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **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 09ce675..882ee84 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 @@ -4,14 +4,12 @@ sidebar_position: 5 # GeneralUpdate.Core -## 组件概览 | Component Overview - -**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一，提供了完整的升级执行能力。与 ClientCore 不同，Core 组件作为独立的升级助手程序运行，负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式，Core 接收来自 ClientCore 的更新指令，并安全地完成主程序的升级任务。 +## 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. -**命名空间 | Namespace:** `GeneralUpdate.Core` -**程序集 | Assembly:** `GeneralUpdate.Core.dll` +**Namespace:** `GeneralUpdate.Core` +**Assembly:** `GeneralUpdate.Core.dll` ```csharp public class GeneralUpdateBootstrap : AbstractBootstrap @@ -19,36 +17,34 @@ public class GeneralUpdateBootstrap : AbstractBootstrap LaunchAsync() ``` -**返回值 | Return Value:** -- 返回当前 GeneralUpdateBootstrap 实例，支持链式调用 +**Return Value:** - Returns the current GeneralUpdateBootstrap instance, supporting method chaining -#### Option 方法 | Option Method - -设置升级选项。 +#### Option Method Set upgrade options. @@ -161,18 +150,16 @@ Set upgrade options. public GeneralUpdateBootstrap Option(UpdateOption option, object value) ``` -**参数 | Parameters:** -- `option`: 升级选项枚举 | Upgrade option enum -- `value`: 选项值 | Option value +**Parameters:** +- `option`: Upgrade option enum +- `value`: Option value -**示例 | Example:** +**Example:** ```csharp -.Option(UpdateOption.Drive, true) // 启用驱动升级 | Enable driver upgrade +.Option(UpdateOption.Drive, true) // Enable driver upgrade ``` -#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method - -监听下载统计信息（速度、进度、剩余时间等）。 +#### AddListenerMultiDownloadStatistics Method Listen for download statistics (speed, progress, remaining time, etc.). @@ -181,9 +168,7 @@ public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( Action callbackAction) ``` -#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method - -监听单个更新包下载完成事件。 +#### AddListenerMultiDownloadCompleted Method Listen for single update package download completion event. @@ -192,9 +177,7 @@ public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method - -监听所有版本下载完成事件。 +#### AddListenerMultiAllDownloadCompleted Method Listen for all version downloads completion event. @@ -203,9 +186,7 @@ public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method - -监听每个版本下载错误事件。 +#### AddListenerMultiDownloadError Method Listen for download error events for each version. @@ -214,9 +195,7 @@ public GeneralUpdateBootstrap AddListenerMultiDownloadError( Action callbackAction) ``` -#### AddListenerException 方法 | AddListenerException Method - -监听升级组件内部所有异常。 +#### AddListenerException Method Listen for all internal exceptions in the upgrade component. @@ -225,9 +204,7 @@ public GeneralUpdateBootstrap AddListenerException( Action callbackAction) ``` -#### SetFieldMappings 方法 | SetFieldMappings Method - -设置字段映射表，用于解析驱动包信息。 +#### SetFieldMappings Method Set field mapping table for parsing driver package information. @@ -235,30 +212,26 @@ Set field mapping table for parsing driver package information. public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) ``` -**参数 | Parameters:** -- `fieldMappings`: 字段映射字典，键为英文字段名，值为本地化字段名 -- Field mapping dictionary, key is English field name, value is localized field name +**Parameters:** +- `fieldMappings`: Field mapping dictionary, key is English field name, value is localized field name --- -## 配置类详解 | Configuration Class Details +## Configuration Class Details -### UpdateOption 枚举 | UpdateOption Enum +### UpdateOption Enum ```csharp public enum UpdateOption { /// - /// 是否启用驱动升级功能 /// Whether to enable driver upgrade functionality /// Drive } ``` -### Packet 类 | Packet Class - -升级包信息类，由 ClientCore 通过参数传递给 Core： +### Packet Class Upgrade package information class, passed from ClientCore to Core via parameters: @@ -266,133 +239,111 @@ Upgrade package information class, passed from ClientCore to Core via parameters public class Packet { /// - /// 主更新检查 API 地址 /// Main update check API address /// public string MainUpdateUrl { get; set; } /// - /// 应用类型：1=客户端应用，2=更新应用 /// Application type: 1=ClientApp, 2=UpdateApp /// public int AppType { get; set; } /// - /// 更新检查 API 地址 /// Update check API address /// public string UpdateUrl { get; set; } /// - /// 需要启动的应用程序名称 /// Name of the application to be launched /// public string AppName { get; set; } /// - /// 主应用程序名称 /// Main application name /// public string MainAppName { get; set; } /// - /// 更新包文件格式（默认为 Zip） /// Update package file format (default is Zip) /// public string Format { get; set; } /// - /// 是否需要升级更新应用 /// Indicates if the update application needs to be upgraded /// public bool IsUpgradeUpdate { get; set; } /// - /// 是否需要更新主应用 /// Indicates if the main application needs to be updated /// public bool IsMainUpdate { get; set; } /// - /// 更新日志网页 URL /// Update log webpage URL /// public string UpdateLogUrl { get; set; } /// - /// 需要更新的版本信息列表 /// List of version information that needs updating /// public List UpdateVersions { get; set; } /// - /// 文件操作编码格式 /// File operation encoding format /// public Encoding Encoding { get; set; } /// - /// 下载超时时间（秒） /// Download timeout duration (seconds) /// public int DownloadTimeOut { get; set; } /// - /// 应用密钥，与服务器约定 /// Application secret key, agreed upon with the server /// public string AppSecretKey { get; set; } /// - /// 当前客户端版本 /// Current client version /// public string ClientVersion { get; set; } /// - /// 最新版本 /// Latest version /// public string LastVersion { get; set; } /// - /// 安装路径（用于更新文件逻辑） /// Installation path (used for update file logic) /// public string InstallPath { get; set; } /// - /// 下载文件的临时存储路径 /// Temporary storage path for downloaded files /// public string TempPath { get; set; } /// - /// 升级终端程序的配置参数（Base64 编码） /// Configuration parameters for the upgrade terminal program (Base64 encoded) /// public string ProcessBase64 { get; set; } /// - /// 当前策略所属平台（Windows/Linux/Mac） /// Platform to which the current strategy belongs (Windows/Linux/Mac) /// public string Platform { get; set; } /// - /// 黑名单文件列表 /// Files in the blacklist /// public List BlackFiles { get; set; } /// - /// 黑名单文件格式列表 /// File formats in the blacklist /// public List BlackFormats { get; set; } /// - /// 是否启用驱动升级功能 /// Indicates if the driver upgrade feature is enabled /// public bool DriveEnabled { get; set; } @@ -401,9 +352,9 @@ public class Packet --- -## 实际使用示例 | Practical Usage Examples +## Practical Usage Examples -### 示例 1：基本升级流程 | Example 1: Basic Upgrade Process +### Example 1: Basic Upgrade Process ```csharp using GeneralUpdate.Common.Download; @@ -413,36 +364,36 @@ using GeneralUpdate.Core; try { - Console.WriteLine("升级程序初始化..."); + Console.WriteLine("Upgrade program initialization..."); - // 启动升级流程 | Launch upgrade process + // Launch upgrade process await new GeneralUpdateBootstrap() .AddListenerMultiDownloadStatistics((sender, args) => { var version = args.Version as VersionInfo; - Console.WriteLine($"[{version.Version}] 下载进度: {args.ProgressPercentage}%"); + Console.WriteLine($"[{version.Version}] Download progress: {args.ProgressPercentage}%"); }) .AddListenerException((sender, args) => { - Console.WriteLine($"升级异常: {args.Exception.Message}"); + Console.WriteLine($"Upgrade exception: {args.Exception.Message}"); }) .LaunchAsync(); - Console.WriteLine("升级完成！"); + Console.WriteLine("Upgrade complete!"); } catch (Exception e) { - Console.WriteLine($"升级失败: {e.Message}"); + Console.WriteLine($"Upgrade failed: {e.Message}"); } ``` -### 示例 2：启用驱动升级 | Example 2: Enable Driver Upgrade +### Example 2: Enable Driver Upgrade ```csharp using GeneralUpdate.Core; using GeneralUpdate.Common.Internal.Bootstrap; -// 中文字段映射表 | Chinese field mapping table +// Chinese field mapping table var fieldMappingsCN = new Dictionary { { "DriverName", "驱动名称" }, @@ -452,18 +403,18 @@ var fieldMappingsCN = new Dictionary }; await new GeneralUpdateBootstrap() - // 设置字段映射表 | Set field mappings + // Set field mappings .SetFieldMappings(fieldMappingsCN) - // 启用驱动更新 | Enable driver update + // Enable driver update .Option(UpdateOption.Drive, true) .AddListenerException((sender, args) => { - Console.WriteLine($"升级异常: {args.Exception.Message}"); + Console.WriteLine($"Upgrade exception: {args.Exception.Message}"); }) .LaunchAsync(); ``` -### 示例 3：完整事件监听 | Example 3: Complete Event Listening +### Example 3: Complete Event Listening ```csharp using GeneralUpdate.Core; @@ -471,64 +422,64 @@ using GeneralUpdate.Common.Download; using GeneralUpdate.Common.Shared.Object; await new GeneralUpdateBootstrap() - // 下载统计 | Download statistics + // Download statistics .AddListenerMultiDownloadStatistics((sender, args) => { var version = args.Version as VersionInfo; Console.WriteLine($"[{version.Version}]"); - Console.WriteLine($" 速度: {args.Speed}"); - Console.WriteLine($" 进度: {args.ProgressPercentage}%"); - Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); - Console.WriteLine($" 剩余时间: {args.Remaining}"); + Console.WriteLine($" Speed: {args.Speed}"); + Console.WriteLine($" Progress: {args.ProgressPercentage}%"); + Console.WriteLine($" Downloaded: {args.BytesReceived} / {args.TotalBytesToReceive}"); + Console.WriteLine($" Remaining time: {args.Remaining}"); }) - // 单个下载完成 | Single download completed + // Single download completed .AddListenerMultiDownloadCompleted((sender, args) => { var version = args.Version as VersionInfo; - string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; - Console.WriteLine($"版本 {version.Version} 下载{status}"); + string status = args.IsComplated ? "✓ Success" : "✗ Failed"; + Console.WriteLine($"Version {version.Version} download {status}"); }) - // 所有下载完成 | All downloads completed + // All downloads completed .AddListenerMultiAllDownloadCompleted((sender, args) => { if (args.IsAllDownloadCompleted) { - Console.WriteLine("✓ 所有版本下载完成，开始安装..."); + Console.WriteLine("✓ All versions downloaded, starting installation..."); } else { - Console.WriteLine($"✗ 下载失败，{args.FailedVersions.Count} 个版本失败："); + Console.WriteLine($"✗ Download failed, {args.FailedVersions.Count} versions failed:"); foreach (var version in args.FailedVersions) { Console.WriteLine($" - {version}"); } } }) - // 下载错误 | Download error + // Download error .AddListenerMultiDownloadError((sender, args) => { var version = args.Version as VersionInfo; - Console.WriteLine($"✗ 版本 {version.Version} 错误:"); + Console.WriteLine($"✗ Version {version.Version} error:"); Console.WriteLine($" {args.Exception.Message}"); }) - // 异常处理 | Exception handling + // Exception handling .AddListenerException((sender, args) => { - Console.WriteLine("⚠ 升级过程异常:"); - Console.WriteLine($" 错误: {args.Exception.Message}"); - Console.WriteLine($" 堆栈: {args.Exception.StackTrace}"); + Console.WriteLine("⚠ Upgrade process exception:"); + Console.WriteLine($" Error: {args.Exception.Message}"); + Console.WriteLine($" Stack: {args.Exception.StackTrace}"); }) .LaunchAsync(); ``` -### 示例 4：自定义升级流程 | Example 4: Custom Upgrade Process +### Example 4: Custom Upgrade Process ```csharp using GeneralUpdate.Core; using GeneralUpdate.Common.Download; using GeneralUpdate.Common.Shared.Object; -// 记录升级开始时间 | Record upgrade start time +// Record upgrade start time var startTime = DateTime.Now; var downloadedVersions = new List(); @@ -546,14 +497,14 @@ await new GeneralUpdateBootstrap() if (args.IsAllDownloadCompleted) { var duration = DateTime.Now - startTime; - Console.WriteLine($"升级完成！"); - Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); - Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); + Console.WriteLine($"Upgrade complete!"); + Console.WriteLine($"Total time: {duration.TotalSeconds:F2} seconds"); + Console.WriteLine($"Updated versions: {string.Join(", ", downloadedVersions)}"); } }) .AddListenerException((sender, args) => { - // 记录日志到文件 | Log to file + // Log to file File.AppendAllText("upgrade_error.log", $"[{DateTime.Now}] {args.Exception}\n"); }) @@ -562,47 +513,32 @@ await new GeneralUpdateBootstrap() --- -## 注意事项与警告 | Notes and Warnings +## Notes and Warnings -### ⚠️ 重要提示 | Important Notes +### ⚠️ Important Notes -1. **进程隔离 | Process Isolation** - - Core 必须作为独立进程运行，不能在主程序中直接调用 - - 升级时主程序必须完全关闭，否则文件替换会失败 +1. **Process Isolation** - Core must run as an independent process, cannot be called directly in the main program - The main program must be completely closed during upgrade, otherwise file replacement will fail -2. **参数传递 | Parameter Passing** - - ClientCore 通过 Base64 编码的参数传递配置给 Core - - 确保参数传递过程中不会被截断或损坏 +2. **Parameter Passing** - ClientCore passes configuration to Core via Base64 encoded parameters - Ensure parameters are not truncated or corrupted during passing -3. **文件权限 | File Permissions** - - 在 Windows 上可能需要管理员权限替换系统目录中的文件 - - 在 Linux/macOS 上需要适当的文件系统权限 +3. **File Permissions** - Administrator privileges may be required on Windows to replace files in system directories - Appropriate file system permissions are required on Linux/macOS -4. **驱动升级 | Driver Upgrade** - - 驱动升级功能需要系统级权限 - - 建议在测试环境充分验证后再使用 +4. **Driver Upgrade** - Driver upgrade functionality requires system-level permissions - Recommended to thoroughly validate in test environment before use -5. **回滚机制 | Rollback Mechanism** - - Core 不直接提供回滚功能，但保留了备份文件 - - 如需回滚，可使用 ClientCore 的备份功能 +5. **Rollback Mechanism** - Core does not directly provide rollback functionality, but backup files are preserved - For rollback, use ClientCore's backup functionality -### 💡 最佳实践 | Best Practices +### 💡 Best Practices -- **日志记录**：实现完整的异常监听，记录升级过程中的所有问题 -- **超时设置**：根据网络环境合理设置下载超时时间 -- **进度反馈**：向用户显示升级进度，提升用户体验 -- **错误处理**：升级失败时提供清晰的错误信息和解决方案 -- **测试验证**：在各种网络条件下测试升级流程的稳定性 - **Logging**: Implement complete exception listening to record all issues during the upgrade process - **Timeout Settings**: Set download timeout appropriately based on network environment - **Progress Feedback**: Display upgrade progress to users to improve user experience @@ -611,10 +547,10 @@ await new GeneralUpdateBootstrap() --- -## 适用平台 | Applicable Platforms +## Applicable Platforms -| 产品 Product | 版本 Version | -| ------------------ | ----------------- | +| Product | Version | +| -------------- | ------------- | | .NET | 5, 6, 7, 8, 9 | | .NET Framework | 4.6.1 | | .NET Standard | 2.0 | @@ -622,8 +558,8 @@ await new GeneralUpdateBootstrap() --- -## 相关资源 | Related Resources +## Related Resources -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) -- **相关组件**：[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) +- **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) 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 7bf5a80..4132a1a 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 @@ -4,14 +4,12 @@ sidebar_position: 6 # GeneralUpdate.Differential -## 组件概览 | Component Overview - -**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法，可以精确识别两个版本之间的文件变化，生成高效的增量补丁包，并支持补丁还原操作。通过使用差异更新，可以显著减少更新包的大小和下载时间，特别适合频繁发布更新的应用场景。 +## Component Overview **GeneralUpdate.Differential** is the core component responsible for binary differential updates in the GeneralUpdate framework. This component provides powerful differential algorithms that can accurately identify file changes between two versions, generate efficient incremental patch packages, and support patch restoration operations. By using differential updates, you can significantly reduce update package size and download time, making it particularly suitable for scenarios with frequent update releases. -**命名空间 | Namespace:** `GeneralUpdate.Differential` -**程序集 | Assembly:** `GeneralUpdate.Core.dll` +**Namespace:** `GeneralUpdate.Differential` +**Assembly:** `GeneralUpdate.Core.dll` ```csharp public sealed class DifferentialCore @@ -19,35 +17,33 @@ public sealed class DifferentialCore --- -## 核心特性 | Core Features +## Core Features -### 1. 增量识别 | Incremental Identification -- 精确识别新增、修改、删除的文件 | Accurately identify added, modified, and deleted files -- 智能文件版本对比 | Intelligent file version comparison -- 支持跳过指定文件和格式 | Support skipping specified files and formats +### 1. Incremental Identification +- Accurately identify added, modified, and deleted files +- Intelligent file version comparison +- Support skipping specified files and formats -### 2. 二进制补丁生成 | Binary Patch Generation -- 高效的二进制差异算法 | Efficient binary differential algorithm -- 最小化补丁文件大小 | Minimize patch file size -- 快速补丁生成速度 | Fast patch generation speed +### 2. Binary Patch Generation +- Efficient binary differential algorithm +- Minimize patch file size +- Fast patch generation speed -### 3. 补丁还原 | Patch Restoration -- 安全的补丁应用流程 | Safe patch application process -- 自动处理文件依赖关系 | Automatic handling of file dependencies -- 完整性验证机制 | Integrity verification mechanism +### 3. Patch Restoration +- Safe patch application process +- Automatic handling of file dependencies +- Integrity verification mechanism -### 4. 黑名单支持 | Blacklist Support -- 文件级黑名单 | File-level blacklist -- 格式级黑名单 | Format-level blacklist -- 灵活的过滤规则 | Flexible filtering rules +### 4. Blacklist Support +- File-level blacklist +- Format-level blacklist +- Flexible filtering rules --- -## 快速开始 | Quick Start - -### 安装 | Installation +## Quick Start -通过 NuGet 安装 GeneralUpdate.Differential（包含在 Core 包中）： +### Installation Install GeneralUpdate.Differential via NuGet (included in Core package): @@ -55,35 +51,31 @@ Install GeneralUpdate.Differential via NuGet (included in Core package): dotnet add package GeneralUpdate.Core ``` -### 初始化与使用 | Initialization and Usage - -以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作： +### Initialization and Usage The following example demonstrates how to use DifferentialCore for incremental identification and patch operations: ```csharp using GeneralUpdate.Differential; -// 增量识别并生成二进制补丁 | Identify increments and generate binary patches -var sourcePath = @"D:\packet\app"; // 旧版本路径 | Old version path -var targetPath = @"D:\packet\release"; // 新版本路径 | New version path -var patchPath = @"D:\packet\patch"; // 补丁输出路径 | Patch output path +// Identify increments and generate binary patches +var sourcePath = @"D:\packet\app"; // Old version path +var targetPath = @"D:\packet\release"; // New version path +var patchPath = @"D:\packet\patch"; // Patch output path await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); -// 应用补丁（还原） | Apply patches (restoration) +// Apply patches (restoration) await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); ``` --- -## 核心 API 参考 | Core API Reference - -### DifferentialCore 类 | DifferentialCore Class +## Core API Reference -#### Instance 属性 | Instance Property +### DifferentialCore Class -获取 DifferentialCore 的单例实例。 +#### Instance Property Get the singleton instance of DifferentialCore. @@ -91,77 +83,73 @@ Get the singleton instance of DifferentialCore. public static DifferentialCore Instance { get; } ``` -#### Clean 方法 | Clean Method - -执行增量识别、删除文件识别，并生成二进制补丁文件。 +#### Clean Method Perform incremental identification, deleted file identification, and generate binary patch files. -**方法签名 | Method Signature:** +**Method Signature:** ```csharp public async Task Clean(string sourcePath, string targetPath, string patchPath = null) ``` -**参数 | Parameters:** -- `sourcePath`: 旧版本文件夹路径 | Path to the old version folder -- `targetPath`: 新版本文件夹路径 | Path to the new version folder -- `patchPath`: 补丁文件输出目录（可选）| Directory to store discovered incremental update files (optional) +**Parameters:** +- `sourcePath`: Path to the old version folder +- `targetPath`: Path to the new version folder +- `patchPath`: Directory to store discovered incremental update files (optional) -**功能说明 | Function Description:** -1. 对比 sourcePath 和 targetPath 两个目录 -2. 识别新增、修改、删除的文件 -3. 为修改的文件生成二进制差异补丁 -4. 将补丁和新增文件保存到 patchPath +**Function Description:** +1. Compare sourcePath and targetPath directories +2. Identify added, modified, and deleted files +3. Generate binary differential patches for modified files +4. Save patches and added files to patchPath -**示例 | Example:** +**Example:** ```csharp -// 生成从 v1.0.0 到 v1.1.0 的补丁包 +// Generate patch package from v1.0.0 to v1.1.0 var source = @"D:\MyApp\v1.0.0"; var target = @"D:\MyApp\v1.1.0"; var patch = @"D:\MyApp\patches\v1.1.0"; await DifferentialCore.Instance.Clean(source, target, patch); -// 结果：patch 目录包含所有必要的增量更新文件 +// Result: patch directory contains all necessary incremental update files ``` -#### Dirty 方法 | Dirty Method - -应用补丁，将旧版本文件更新到新版本。 +#### Dirty Method Apply patches to update old version files to the new version. -**方法签名 | Method Signature:** +**Method Signature:** ```csharp public async Task Dirty(string appPath, string patchPath) ``` -**参数 | Parameters:** -- `appPath`: 客户端应用程序目录（当前版本）| Client application directory (current version) -- `patchPath`: 补丁文件路径 | Path to the patch files +**Parameters:** +- `appPath`: Client application directory (current version) +- `patchPath`: Path to the patch files -**功能说明 | Function Description:** -1. 读取 patchPath 中的补丁文件 -2. 将补丁应用到 appPath 中的对应文件 -3. 处理新增文件的复制 -4. 处理删除文件的移除 +**Function Description:** +1. Read patch files from patchPath +2. Apply patches to corresponding files in appPath +3. Handle copying of added files +4. Handle removal of deleted files -**示例 | Example:** +**Example:** ```csharp -// 将补丁应用到当前应用程序 +// Apply patches to current application var appDir = AppDomain.CurrentDomain.BaseDirectory; var patchDir = Path.Combine(appDir, "temp", "patches"); await DifferentialCore.Instance.Dirty(appDir, patchDir); -// 结果：应用程序更新到新版本 +// Result: application updated to new version ``` --- -## 实际使用示例 | Practical Usage Examples +## Practical Usage Examples -### 示例 1：基本补丁生成 | Example 1: Basic Patch Generation +### Example 1: Basic Patch Generation ```csharp using GeneralUpdate.Differential; @@ -170,33 +158,33 @@ public async Task GeneratePatchAsync() { try { - // 版本路径 | Version paths + // Version paths var oldVersion = @"D:\MyApp\1.0.0"; var newVersion = @"D:\MyApp\1.0.1"; var patchOutput = @"D:\MyApp\patches\1.0.1"; - Console.WriteLine("开始生成补丁..."); + Console.WriteLine("Starting patch generation..."); - // 生成补丁 | Generate patches + // Generate patches await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); - Console.WriteLine($"补丁生成完成！输出目录：{patchOutput}"); + Console.WriteLine($"Patch generation complete! Output directory: {patchOutput}"); - // 显示补丁信息 | Display patch information + // Display patch information var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); - Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); + Console.WriteLine($"Generated {patchFiles.Length} patch files"); long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); - Console.WriteLine($"总补丁大小：{totalSize / 1024.0:F2} KB"); + Console.WriteLine($"Total patch size: {totalSize / 1024.0:F2} KB"); } catch (Exception ex) { - Console.WriteLine($"补丁生成失败：{ex.Message}"); + Console.WriteLine($"Patch generation failed: {ex.Message}"); } } ``` -### 示例 2：应用补丁 | Example 2: Apply Patches +### Example 2: Apply Patches ```csharp using GeneralUpdate.Differential; @@ -205,32 +193,32 @@ public async Task ApplyPatchAsync() { try { - // 应用程序目录 | Application directory + // Application directory var appDirectory = @"D:\MyApp\current"; - // 补丁目录 | Patch directory + // Patch directory var patchDirectory = @"D:\MyApp\patches\1.0.1"; - Console.WriteLine("开始应用补丁..."); + Console.WriteLine("Starting patch application..."); - // 验证补丁存在 | Verify patch exists + // Verify patch exists if (!Directory.Exists(patchDirectory)) { - throw new DirectoryNotFoundException($"补丁目录不存在：{patchDirectory}"); + throw new DirectoryNotFoundException($"Patch directory not found: {patchDirectory}"); } - // 应用补丁 | Apply patches + // Apply patches await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); - Console.WriteLine("补丁应用成功！应用程序已更新到新版本。"); + Console.WriteLine("Patch applied successfully! Application updated to new version."); } catch (Exception ex) { - Console.WriteLine($"补丁应用失败：{ex.Message}"); + Console.WriteLine($"Patch application failed: {ex.Message}"); } } ``` -### 示例 3：完整的补丁流程 | Example 3: Complete Patch Workflow +### Example 3: Complete Patch Workflow ```csharp using GeneralUpdate.Differential; @@ -238,7 +226,7 @@ using System.IO.Compression; public class PatchManager { - // 生成并打包补丁 | Generate and package patches + // Generate and package patches public async Task CreatePatchPackageAsync( string oldVersionPath, string newVersionPath, @@ -246,16 +234,16 @@ public class PatchManager { try { - // 1. 生成补丁文件 | Generate patch files + // 1. Generate patch files var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); Directory.CreateDirectory(tempPatchDir); - Console.WriteLine($"正在生成补丁..."); + Console.WriteLine($"Generating patches..."); await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); - // 2. 压缩补丁文件 | Compress patch files + // 2. Compress patch files var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); - Console.WriteLine($"正在打包补丁..."); + Console.WriteLine($"Packaging patches..."); if (File.Exists(patchZipPath)) File.Delete(patchZipPath); @@ -263,69 +251,69 @@ public class PatchManager ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, CompressionLevel.Optimal, false); - // 3. 清理临时文件 | Clean up temp files + // 3. Clean up temp files Directory.Delete(tempPatchDir, true); var patchSize = new FileInfo(patchZipPath).Length; - Console.WriteLine($"补丁包创建成功：{patchZipPath}"); - Console.WriteLine($"补丁包大小：{patchSize / 1024.0:F2} KB"); + Console.WriteLine($"Patch package created successfully: {patchZipPath}"); + Console.WriteLine($"Patch package size: {patchSize / 1024.0:F2} KB"); return patchZipPath; } catch (Exception ex) { - Console.WriteLine($"创建补丁包失败：{ex.Message}"); + Console.WriteLine($"Patch package creation failed: {ex.Message}"); throw; } } - // 解压并应用补丁 | Extract and apply patches + // Extract and apply patches public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) { try { - // 1. 解压补丁包 | Extract patch package + // 1. Extract patch package var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); Directory.CreateDirectory(tempExtractDir); - Console.WriteLine($"正在解压补丁包..."); + Console.WriteLine($"Extracting patch package..."); ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); - // 2. 应用补丁 | Apply patches - Console.WriteLine($"正在应用补丁..."); + // 2. Apply patches + Console.WriteLine($"Applying patches..."); await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); - // 3. 清理临时文件 | Clean up temp files + // 3. Clean up temp files Directory.Delete(tempExtractDir, true); - Console.WriteLine($"补丁应用成功！"); + Console.WriteLine($"Patch applied successfully!"); } catch (Exception ex) { - Console.WriteLine($"应用补丁包失败：{ex.Message}"); + Console.WriteLine($"Patch package application failed: {ex.Message}"); throw; } } } -// 使用示例 | Usage example +// Usage example var manager = new PatchManager(); -// 创建补丁包 | Create patch package +// Create patch package var patchZip = await manager.CreatePatchPackageAsync( @"D:\MyApp\1.0.0", @"D:\MyApp\1.0.1", @"D:\MyApp\releases" ); -// 应用补丁包 | Apply patch package +// Apply patch package await manager.ApplyPatchPackageAsync( @"D:\MyApp\current", patchZip ); ``` -### 示例 4：带进度显示的补丁操作 | Example 4: Patch Operations with Progress Display +### Example 4: Patch Operations with Progress Display ```csharp using GeneralUpdate.Differential; @@ -340,20 +328,20 @@ public class ProgressivePatchManager { try { - progress?.Report("开始扫描文件差异..."); + progress?.Report("Starting file difference scan..."); - // 在实际场景中，可以在 Clean 前后添加进度报告 + // In actual scenarios, you can add progress reports before and after Clean await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); - progress?.Report("补丁生成完成！"); + progress?.Report("Patch generation complete!"); - // 统计信息 | Statistics + // Statistics var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); - progress?.Report($"共生成 {files.Length} 个补丁文件"); + progress?.Report($"Generated {files.Length} patch files"); } catch (Exception ex) { - progress?.Report($"错误：{ex.Message}"); + progress?.Report($"Error: {ex.Message}"); throw; } } @@ -365,21 +353,21 @@ public class ProgressivePatchManager { try { - progress?.Report("开始应用补丁..."); + progress?.Report("Starting patch application..."); await DifferentialCore.Instance.Dirty(appPath, patchPath); - progress?.Report("补丁应用成功！"); + progress?.Report("Patch applied successfully!"); } catch (Exception ex) { - progress?.Report($"错误：{ex.Message}"); + progress?.Report($"Error: {ex.Message}"); throw; } } } -// 使用示例 | Usage example +// Usage example var manager = new ProgressivePatchManager(); var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); @@ -390,77 +378,63 @@ await manager.GeneratePatchWithProgressAsync( progress ); ``` + --- -## 注意事项与警告 | Notes and Warnings +## Notes and Warnings -### ⚠️ 重要提示 | Important Notes +### ⚠️ Important Notes -1. **文件名限制 | File Name Restrictions** - - 不能包含同名但扩展名不同的文件（如 file.txt 和 file.log） - - 建议使用唯一的文件名命名规则 +1. **File Name Restrictions** - Cannot include files with the same name but different extensions (e.g., file.txt and file.log) - Recommended to use unique file naming conventions -2. **目录结构 | Directory Structure** - - 源目录和目标目录的相对结构应保持一致 - - 补丁生成时会保留目录层次关系 +2. **Directory Structure** - The relative structure of source and target directories should remain consistent - Directory hierarchy is preserved during patch generation -3. **磁盘空间 | Disk Space** - - 确保有足够的磁盘空间存储补丁文件 - - 二进制差异补丁通常比完整文件小，但仍需要临时空间 +3. **Disk Space** - Ensure sufficient disk space for storing patch files - Binary differential patches are usually smaller than complete files, but still require temporary space -4. **文件占用 | File Locking** - - 应用补丁时，确保目标文件没有被其他进程占用 - - 建议在应用程序关闭后应用补丁 +4. **File Locking** - When applying patches, ensure target files are not locked by other processes - Recommended to apply patches after the application is closed -5. **备份建议 | Backup Recommendations** - - 在应用补丁前建议备份原始文件 - - 可以使用 ClientCore 的 BackUp 选项自动备份 +5. **Backup Recommendations** - Recommended to backup original files before applying patches - Can use ClientCore's BackUp option for automatic backup -### 💡 最佳实践 | Best Practices +### 💡 Best Practices -- **版本管理**：为每个版本维护独立的补丁包，便于版本追踪和回滚 -- **补丁验证**：生成补丁后进行验证测试，确保补丁可以正确应用 -- **增量更新**：优先使用差异更新而非全量更新，可节省 50%-90% 的下载量 -- **错误处理**：实现完整的异常捕获和错误恢复机制 -- **性能优化**：对于大文件，差异算法的性能优势更加明显 - **Version Management**: Maintain separate patch packages for each version for easier version tracking and rollback - **Patch Validation**: Perform validation testing after generating patches to ensure they can be applied correctly - **Incremental Updates**: Prioritize differential updates over full updates, which can save 50%-90% of download size - **Error Handling**: Implement complete exception capture and error recovery mechanisms - **Performance Optimization**: For large files, the performance advantage of the differential algorithm is more pronounced -### 🔍 工作原理 | How It Works +### 🔍 How It Works -**Clean 方法工作流程 | Clean Method Workflow:** -1. 扫描源目录和目标目录中的所有文件 -2. 比较文件的MD5哈希值以识别变化 -3. 对于修改的文件，使用二进制差异算法生成补丁 -4. 对于新增文件，直接复制到补丁目录 -5. 记录删除的文件列表 +**Clean Method Workflow:** +1. Scan all files in source and target directories +2. Compare MD5 hash values of files to identify changes +3. For modified files, use binary differential algorithm to generate patches +4. For added files, copy directly to patch directory +5. Record list of deleted files -**Dirty 方法工作流程 | Dirty Method Workflow:** -1. 读取补丁目录中的所有文件 -2. 对于补丁文件，应用到对应的原文件上 -3. 对于新增文件，直接复制到应用目录 -4. 根据删除列表移除相应文件 -5. 验证更新完整性 +**Dirty Method Workflow:** +1. Read all files in patch directory +2. For patch files, apply to corresponding original files +3. For added files, copy directly to application directory +4. Remove corresponding files according to deletion list +5. Verify update integrity --- -## 适用平台 | Applicable Platforms +## Applicable Platforms -| 产品 Product | 版本 Version | -| ------------------ | ----------------- | +| Product | Version | +| -------------- | ------------- | | .NET | 5, 6, 7, 8, 9 | | .NET Framework | 4.6.1 | | .NET Standard | 2.0 | @@ -468,8 +442,8 @@ await manager.GeneratePatchWithProgressAsync( --- -## 相关资源 | Related Resources +## Related Resources -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) -- **打包工具**：GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 | The GeneralUpdate.PacketTool project depends on this component for differential packaging +- **Sample Code**: [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) +- **Main Repository**: [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **Packaging Tool**: The GeneralUpdate.PacketTool project depends on this component for differential packaging From 67f5a14ff20197200cfb38a545b3ca71340ee278 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Feb 2026 15:45:43 +0000 Subject: [PATCH 7/7] Separate bilingual docs into proper i18n structure - Chinese and English in separate files Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com> --- .../current/doc/GeneralUpdate.Bowl.md | 199 ++++------- .../current/doc/GeneralUpdate.ClientCore.md | 329 +++++++----------- .../current/doc/GeneralUpdate.Core.md | 308 +++++++--------- .../current/doc/GeneralUpdate.Differential.md | 273 +++++++-------- 4 files changed, 453 insertions(+), 656 deletions(-) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md index 5af0825..de44ec6 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc/GeneralUpdate.Bowl.md @@ -4,14 +4,12 @@ sidebar_position: 3 # GeneralUpdate.Bowl -## 组件概览 | Component Overview +## 组件概览 **GeneralUpdate.Bowl** 是一个独立的进程监控组件，在升级流程结束前启动，负责启动主客户端应用程序并监控其运行状态。该组件提供了完整的崩溃监控和诊断能力，当被监控的应用程序发生异常时，会自动导出Dump文件、驱动信息、系统信息和事件日志，帮助开发者快速定位问题。 -**GeneralUpdate.Bowl** is an independent process monitoring component that launches before the end of the upgrade process. It is responsible for starting the main client application and monitoring its running status. This component provides comprehensive crash monitoring and diagnostic capabilities. When the monitored application encounters an exception, it automatically exports Dump files, driver information, system information, and event logs to help developers quickly locate issues. - -**命名空间 | Namespace:** `GeneralUpdate.Bowl` -**程序集 | Assembly:** `GeneralUpdate.Bowl.dll` +**命名空间：** `GeneralUpdate.Bowl` +**程序集：** `GeneralUpdate.Bowl.dll` ```csharp public sealed class Bowl @@ -19,41 +17,37 @@ public sealed class Bowl --- -## 核心特性 | Core Features +## 核心特性 -### 1. 进程监控 | Process Monitoring -- 实时监控目标应用程序的运行状态 | Real-time monitoring of target application status -- 自动检测进程崩溃和异常退出 | Automatic detection of process crashes and abnormal exits +### 1. 进程监控 +- 实时监控目标应用程序的运行状态 +- 自动检测进程崩溃和异常退出 -### 2. 崩溃诊断 | Crash Diagnostics -- 自动生成Dump文件（.dmp）用于崩溃分析 | Automatic generation of Dump files (.dmp) for crash analysis -- 导出详细的系统和驱动信息 | Export detailed system and driver information -- 收集Windows系统事件日志 | Collect Windows system event logs +### 2. 崩溃诊断 +- 自动生成Dump文件（.dmp）用于崩溃分析 +- 导出详细的系统和驱动信息 +- 收集Windows系统事件日志 -### 3. 版本化管理 | Version Management -- 按版本号分类存储故障信息 | Store failure information categorized by version number -- 支持升级和正常两种工作模式 | Support both upgrade and normal working modes +### 3. 版本化管理 +- 按版本号分类存储故障信息 +- 支持升级和正常两种工作模式 --- -## 快速开始 | Quick Start +## 快速开始 -### 安装 | Installation +### 安装 通过 NuGet 安装 GeneralUpdate.Bowl： -Install GeneralUpdate.Bowl via NuGet: - ```bash dotnet add package GeneralUpdate.Bowl ``` -### 初始化与使用 | Initialization and Usage +### 初始化与使用 以下示例展示了如何使用 Bowl 组件监控应用程序： -The following example demonstrates how to use the Bowl component to monitor an application: - ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; @@ -68,67 +62,59 @@ var processInfo = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", lastVersion), BackupDirectory = Path.Combine(installPath, lastVersion), - WorkModel = "Normal" // 使用 Normal 模式独立监控 | Use Normal mode for standalone monitoring + WorkModel = "Normal" // 使用 Normal 模式独立监控 }; Bowl.Launch(processInfo); ``` --- -## 核心 API 参考 | Core API Reference +## 核心 API 参考 -### Launch 方法 | Launch Method +### Launch 方法 启动进程监控功能。 -Start the process monitoring functionality. - -**方法签名 | Method Signature:** +**方法签名：** ```csharp public static void Launch(MonitorParameter? monitorParameter = null) ``` -**参数 | Parameters:** +**参数：** -#### MonitorParameter 类 | MonitorParameter Class +#### MonitorParameter 类 ```csharp public class MonitorParameter { /// /// 被监控的目录 - /// Directory being monitored /// public string TargetPath { get; set; } /// /// 导出异常信息的目录 - /// Directory where captured exception information is exported /// public string FailDirectory { get; set; } /// /// 备份目录 - /// Backup directory /// public string BackupDirectory { get; set; } /// /// 被监控进程的名称或ID - /// Name or ID of the process being monitored /// public string ProcessNameOrId { get; set; } /// /// Dump 文件名 - /// Dump file name /// public string DumpFileName { get; set; } /// /// 升级包版本信息（.json）文件名 - /// Upgrade package version information (.json) file name /// public string FailFileName { get; set; } @@ -136,12 +122,6 @@ public class MonitorParameter /// 工作模式： /// - Upgrade: 升级模式，主要用于与 GeneralUpdate 配合使用，内部逻辑处理，默认模式启动时请勿随意修改 /// - Normal: 正常模式，可独立使用监控单个程序，程序崩溃时导出崩溃信息 - /// - /// Work Mode: - /// - Upgrade: Upgrade mode, primarily used in conjunction with GeneralUpdate for internal logic handling. - /// Do not modify arbitrarily when the default mode is activated. - /// - Normal: Normal mode, can be used independently to monitor a single program. - /// Exports crash information when the program crashes. /// public string WorkModel { get; set; } = "Upgrade"; } @@ -149,15 +129,15 @@ public class MonitorParameter --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：独立模式监控应用 | Example 1: Standalone Mode Application Monitoring +### 示例 1：独立模式监控应用 ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; -// 配置监控参数 | Configure monitoring parameters +// 配置监控参数 var installPath = AppDomain.CurrentDomain.BaseDirectory; var currentVersion = "1.0.0.5"; @@ -169,20 +149,20 @@ var monitorConfig = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "crash_reports", currentVersion), BackupDirectory = Path.Combine(installPath, "backups", currentVersion), - WorkModel = "Normal" // 独立监控模式 | Standalone monitoring mode + WorkModel = "Normal" // 独立监控模式 }; -// 启动监控 | Start monitoring +// 启动监控 Bowl.Launch(monitorConfig); ``` -### 示例 2：结合 GeneralUpdate 使用 | Example 2: Use with GeneralUpdate +### 示例 2：结合 GeneralUpdate 使用 ```csharp using GeneralUpdate.Bowl; using GeneralUpdate.Bowl.Strategys; -// 在升级完成后启动 Bowl 监控 | Start Bowl monitoring after upgrade completion +// 在升级完成后启动 Bowl 监控 var installPath = AppDomain.CurrentDomain.BaseDirectory; var upgradedVersion = "2.0.0.1"; @@ -194,7 +174,7 @@ var upgradeMonitor = new MonitorParameter TargetPath = installPath, FailDirectory = Path.Combine(installPath, "fail", upgradedVersion), BackupDirectory = Path.Combine(installPath, upgradedVersion), - WorkModel = "Upgrade" // 升级模式 | Upgrade mode + WorkModel = "Upgrade" // 升级模式 }; Bowl.Launch(upgradeMonitor); @@ -202,51 +182,43 @@ Bowl.Launch(upgradeMonitor); --- -## 崩溃信息捕获 | Crash Information Capture +## 崩溃信息捕获 当检测到崩溃时，以下文件将在运行目录中生成： -When a crash is detected, the following files will be generated in the running directory: - -- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) | **Dump file** (`x.0.0.*_fail.dmp`) -- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) | **Upgrade package version information** (`x.0.0.*_fail.json`) -- 📒 **驱动信息** (`driverInfo.txt`) | **Driver information** (`driverInfo.txt`) -- 📒 **操作系统/硬件信息** (`systeminfo.txt`) | **Operating system/hardware information** (`systeminfo.txt`) -- 📒 **系统事件日志** (`systemlog.evtx`) | **System event log** (`systemlog.evtx`) +- 📒 **Dump 文件** (`x.0.0.*_fail.dmp`) +- 📒 **升级包版本信息** (`x.0.0.*_fail.json`) +- 📒 **驱动信息** (`driverInfo.txt`) +- 📒 **操作系统/硬件信息** (`systeminfo.txt`) +- 📒 **系统事件日志** (`systemlog.evtx`) 这些文件将按版本号分类导出到 "fail" 目录中。 -These files will be exported to the "fail" directory, categorized by version number. - -![Crash Files](imgs/crash.jpg) +![崩溃文件](imgs/crash.jpg) -### 1. Dump 文件 | Dump File +### 1. Dump 文件 Dump 文件包含崩溃时刻的内存快照，可用于调试分析： -The Dump file contains a memory snapshot at the moment of crash, which can be used for debugging analysis: +![Dump文件](imgs/dump.png) -![Dump File](imgs/dump.png) - -### 2. 版本信息文件 | Version Information File +### 2. 版本信息文件 JSON 格式的详细崩溃报告，包含参数配置和 ProcDump 输出： -Detailed crash report in JSON format, including parameter configuration and ProcDump output: - ```json { - "Parameter": { - "TargetPath": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\", - "FailDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\fail\\1.0.0.3", - "BackupDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\1.0.0.3", - "ProcessNameOrId": "JsonTest.exe", - "DumpFileName": "1.0.0.3_fail.dmp", - "FailFileName": "1.0.0.3_fail.json", - "WorkModel": "Normal", - "ExtendedField": null - }, - "ProcdumpOutPutLines": [ +"Parameter": { +"TargetPath": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\", +"FailDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\fail\\1.0.0.3", +"BackupDirectory": "D:\\github_project\\GeneralUpdate\\src\\c#\\Generalupdate.CatBowl\\bin\\Debug\\net9.0\\1.0.0.3", +"ProcessNameOrId": "JsonTest.exe", +"DumpFileName": "1.0.0.3_fail.dmp", +"FailFileName": "1.0.0.3_fail.json", +"WorkModel": "Normal", +"ExtendedField": null +}, +"ProcdumpOutPutLines": [ "ProcDump v11.0 - Sysinternals process dump utility", "Copyright (C) 2009-2022 Mark Russinovich and Andrew Richards", "Sysinternals - www.sysinternals.com", @@ -274,26 +246,22 @@ Detailed crash report in JSON format, including parameter configuration and Proc } ``` -### 3. 驱动信息文件 | Driver Information File +### 3. 驱动信息文件 包含系统中所有驱动程序的详细信息： -Contains detailed information about all drivers in the system: - ```text Module Name Display Name Description Driver Type Start Mode State Status ============ ====================== ====================== ============= ========== ========== ========== 360AntiAttac 360Safe Anti Attack Se 360Safe Anti Attack Se Kernel System Running OK 360AntiHacke 360Safe Anti Hacker Se 360Safe Anti Hacker Se Kernel System Running OK -// ...更多驱动信息 | ...more driver information +// ...更多驱动信息 ``` -### 4. 系统信息文件 | System Information File +### 4. 系统信息文件 完整的操作系统和硬件配置信息： -Complete operating system and hardware configuration information: - ```text Host Name: **** OS Name: Microsoft Windows 11 Pro @@ -302,72 +270,59 @@ System Manufacturer: ASUS System Model: System Product Name Processor(s): Intel** Family * Model *** Total Physical Memory: 16,194 MB -// ...更多系统信息 | ...more system information +// ...更多系统信息 ``` -### 5. 系统事件日志 | System Event Log +### 5. 系统事件日志 Windows 事件查看器格式的系统日志（.evtx 文件）： -System log in Windows Event Viewer format (.evtx file): - -![System Event Log](imgs/evtx.png) +![系统事件日志](imgs/evtx.png) --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **工作模式选择 | Work Mode Selection** +1. **工作模式选择** - `Upgrade` 模式：专门用于与 GeneralUpdate 框架集成，包含内部逻辑处理 - `Normal` 模式：可独立使用，适合监控任何 .NET 应用程序 - - `Upgrade` mode: Specifically for integration with GeneralUpdate framework, includes internal logic processing - - `Normal` mode: Can be used independently, suitable for monitoring any .NET application -2. **权限要求 | Permission Requirements** +2. **权限要求** - Bowl 需要足够的权限来生成 Dump 文件和读取系统信息 - 建议以管理员权限运行需要监控的应用程序 - - Bowl requires sufficient permissions to generate Dump files and read system information - - It is recommended to run the monitored application with administrator privileges -3. **磁盘空间 | Disk Space** +3. **磁盘空间** - Dump 文件可能占用大量磁盘空间（通常 50-200 MB） - 确保 FailDirectory 所在磁盘有足够的可用空间 - - Dump files may consume significant disk space (typically 50-200 MB) - - Ensure sufficient available space on the disk where FailDirectory is located -4. **依赖项 | Dependencies** +4. **依赖项** - Bowl 使用 ProcDump 工具生成 Dump 文件，该工具已内置在组件中 - 无需额外安装依赖项 - - Bowl uses the ProcDump tool to generate Dump files, which is built into the component - - No additional dependencies need to be installed -### 💡 最佳实践 | Best Practices +### 💡 最佳实践 - **版本号管理**：为每个版本使用独立的故障目录，便于问题追踪 - **日志清理**：定期清理旧版本的故障信息，避免磁盘空间耗尽 - **测试验证**：在生产环境部署前，在测试环境验证监控功能 -- **Version Management**: Use separate failure directories for each version for easier issue tracking -- **Log Cleanup**: Regularly clean up failure information from old versions to avoid disk space exhaustion -- **Testing**: Verify monitoring functionality in a test environment before production deployment --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | -| ------------------ | ----------------- | -| .NET | 5, 6, 7, 8, 9 | -| .NET Framework | 4.6.1 | -| .NET Standard | 2.0 | -| .NET Core | 2.0 | -| ASP.NET | Any | +| 产品 | 版本 | +| --------------- | ----------------- | +| .NET | 5, 6, 7, 8, 9 | +| .NET Framework | 4.6.1 | +| .NET Standard | 2.0 | +| .NET Core | 2.0 | +| ASP.NET | Any | --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) -- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) | [Watch Bilibili Tutorial](https://www.bilibili.com/video/BV1c8iyYZE7P) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) \ No newline at end of file +- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl) +- **视频教程**：[观看 Bilibili 教程](https://www.bilibili.com/video/BV1c8iyYZE7P) +- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) 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 index 005337f..deb4ec3 100644 --- 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 @@ -4,14 +4,12 @@ sidebar_position: 4 # GeneralUpdate.ClientCore -## 组件概览 | Component Overview +## 组件概览 -**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一，提供了丰富的客户端更新功能。该组件运行在主应用程序中，负责检查更新、下载更新包、验证完整性，并在完成后启动升级助手（GeneralUpdate.Core）来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新，而不影响当前运行状态。 +**GeneralUpdate.ClientCore** 是 GeneralUpdate 框架的核心组件之一,提供了丰富的客户端更新功能。该组件运行在主应用程序中,负责检查更新、下载更新包、验证完整性,并在完成后启动升级助手(GeneralUpdate.Core)来执行实际的文件替换操作。ClientCore 的设计理念是让主程序能够安全地检查和准备更新,而不影响当前运行状态。 -**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` +**命名空间:** `GeneralUpdate.ClientCore` +**程序集:** `GeneralUpdate.ClientCore.dll` ```csharp public class GeneralClientBootstrap : AbstractBootstrap @@ -19,48 +17,44 @@ public class GeneralClientBootstrap : AbstractBootstrap LaunchAsync() ``` -#### SetConfig 方法 | SetConfig Method +#### SetConfig 方法 设置更新配置信息。 -Set update configuration information. - ```csharp public GeneralClientBootstrap SetConfig(Configinfo configinfo) ``` -#### Option 方法 | Option Method +#### Option 方法 设置更新选项。 -Set update options. - ```csharp public GeneralClientBootstrap Option(UpdateOption option, object value) ``` -#### SetBlacklist 方法 | SetBlacklist Method +#### SetBlacklist 方法 -设置更新黑名单，指定不需要更新的文件。 - -Set update blacklist to specify files that should not be updated. +设置更新黑名单,指定不需要更新的文件。 ```csharp public GeneralClientBootstrap SetBlacklist(List blackFiles = null, List blackFormats = null) ``` -#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method - -监听下载统计信息（速度、进度、剩余时间等）。 +#### AddListenerMultiDownloadStatistics 方法 -Listen for download statistics (speed, progress, remaining time, etc.). +监听下载统计信息(速度、进度、剩余时间等)。 ```csharp public GeneralClientBootstrap AddListenerMultiDownloadStatistics( Action callbackAction) ``` -#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method +#### AddListenerMultiDownloadCompleted 方法 监听单个更新包下载完成事件。 -Listen for single update package download completion event. - ```csharp public GeneralClientBootstrap AddListenerMultiDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method +#### AddListenerMultiAllDownloadCompleted 方法 监听所有下载任务完成事件。 -Listen for all download tasks completion event. - ```csharp public GeneralClientBootstrap AddListenerMultiAllDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method +#### AddListenerMultiDownloadError 方法 监听下载错误事件。 -Listen for download error events. - ```csharp public GeneralClientBootstrap AddListenerMultiDownloadError( Action callbackAction) ``` -#### AddListenerException 方法 | AddListenerException Method +#### AddListenerException 方法 监听更新过程中的所有异常。 -Listen for all exceptions during the update process. - ```csharp public GeneralClientBootstrap AddListenerException( Action callbackAction) ``` -#### AddCustomOption 方法 | AddCustomOption Method +#### AddCustomOption 方法 -添加自定义异步操作，可在更新前后执行自定义逻辑。 - -Add custom asynchronous operations that can execute custom logic before or after updates. +添加自定义异步操作,可在更新前后执行自定义逻辑。 ```csharp public GeneralClientBootstrap AddCustomOption(Func customFunc) ``` -#### SetCustomSkipOption 方法 | SetCustomSkipOption Method - -设置自定义跳过选项，允许用户决定是否继续更新。 +#### SetCustomSkipOption 方法 -Set custom skip options, allowing users to decide whether to continue with the update. +设置自定义跳过选项,允许用户决定是否继续更新。 ```csharp public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) @@ -283,151 +255,127 @@ public GeneralClientBootstrap SetCustomSkipOption(Func customSkipFunc) --- -## 配置类详解 | Configuration Class Details +## 配置类详解 -### Configinfo 类 | Configinfo Class +### Configinfo 类 ```csharp public class Configinfo { /// /// 更新检查 API 地址 - /// Update check API address /// public string UpdateUrl { get; set; } /// /// 更新状态报告 API 地址 - /// 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; } /// /// 当前产品分支的唯一 ID - /// Unique ID of the current product branch /// public string ProductId { get; set; } /// - /// Bowl 监控进程路径，更新完成后启动 Bowl 检查客户端是否正常启动 - /// Bowl monitoring process path, starts after updates to check if the client starts normally + /// Bowl 监控进程路径,更新完成后启动 Bowl 检查客户端是否正常启动 /// public string Bowl { get; set; } /// - /// HTTP 请求中用于传递 token 的 Scheme（如 Bearer） - /// Scheme used for passing token in HTTP requests (e.g., Bearer) + /// HTTP 请求中用于传递 token 的 Scheme(如 Bearer) /// public string Scheme { get; set; } /// /// HTTP 请求中用于身份验证的 Token - /// Token used for authentication in HTTP requests /// public string Token { get; set; } /// - /// Linux 平台下的脚本，用于在更新完成后为文件分配权限 - /// Script for Linux platform to assign permissions to files after update completion + /// Linux 平台下的脚本,用于在更新完成后为文件分配权限 /// public string Script { get; set; } } ``` -### UpdateOption 枚举 | UpdateOption Enum +### UpdateOption 枚举 ```csharp public enum UpdateOption { /// - /// 更新包文件格式（默认为 Zip） - /// Update package file format (default is Zip) + /// 更新包文件格式(默认为 Zip) /// Format, /// /// 压缩编码格式 - /// Compression encoding format /// Encoding, /// - /// 下载超时时间（秒）。如果不指定，默认超时时间为 30 秒 - /// Download timeout duration (seconds). Default is 30 seconds if not specified + /// 下载超时时间(秒)。如果不指定,默认超时时间为 30 秒 /// DownloadTimeOut, /// - /// 是否启用二进制差异更新功能，默认启用；设置为 false 则执行全量覆盖安装 - /// Whether to enable binary differential update function, enabled by default; - /// if set to false, full overwrite installation will be performed + /// 是否启用二进制差异更新功能,默认启用;设置为 false 则执行全量覆盖安装 /// Patch, /// - /// 是否在更新前启用备份功能，默认启用；设置为 false 则不进行备份 - /// Whether to enable backup function before update, enabled by default; - /// if set to false, no backup will be performed + /// 是否在更新前启用备份功能,默认启用;设置为 false 则不进行备份 /// BackUp } @@ -435,9 +383,9 @@ public enum UpdateOption --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：基本更新流程 | Example 1: Basic Update Process +### 示例 1:基本更新流程 ```csharp using GeneralUpdate.ClientCore; @@ -465,7 +413,7 @@ await new GeneralClientBootstrap() .LaunchAsync(); ``` -### 示例 2：带黑名单的更新 | Example 2: Update with Blacklist +### 示例 2:带黑名单的更新 ```csharp using GeneralUpdate.ClientCore; @@ -476,7 +424,7 @@ 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" } @@ -487,7 +435,7 @@ await new GeneralClientBootstrap() .LaunchAsync(); ``` -### 示例 3：自定义更新选项 | Example 3: Custom Update Options +### 示例 3:自定义更新选项 ```csharp using System.Text; @@ -504,18 +452,18 @@ var config = new Configinfo 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(); ``` -### 示例 4：完整的事件监听 | Example 4: Complete Event Listening +### 示例 4:完整的事件监听 ```csharp using GeneralUpdate.ClientCore; @@ -532,14 +480,14 @@ var config = new Configinfo await new GeneralClientBootstrap() .SetConfig(config) - // 下载统计 | Download statistics + // 下载统计 .AddListenerMultiDownloadStatistics((sender, args) => { var version = args.Version as VersionInfo; Console.WriteLine($"[{version.Version}] 进度: {args.ProgressPercentage}% | " + $"速度: {args.Speed} | 剩余: {args.Remaining}"); }) - // 单个下载完成 | Single download completed + // 单个下载完成 .AddListenerMultiDownloadCompleted((sender, args) => { var version = args.Version as VersionInfo; @@ -548,21 +496,21 @@ await new GeneralClientBootstrap() else Console.WriteLine($"✗ 版本 {version.Version} 下载失败"); }) - // 所有下载完成 | All downloads completed + // 所有下载完成 .AddListenerMultiAllDownloadCompleted((sender, args) => { if (args.IsAllDownloadCompleted) - Console.WriteLine("✓ 所有更新包下载完成，准备安装..."); + Console.WriteLine("✓ 所有更新包下载完成,准备安装..."); else - Console.WriteLine($"✗ 下载失败，共 {args.FailedVersions.Count} 个版本失败"); + Console.WriteLine($"✗ 下载失败,共 {args.FailedVersions.Count} 个版本失败"); }) - // 下载错误 | Download error + // 下载错误 .AddListenerMultiDownloadError((sender, args) => { var version = args.Version as VersionInfo; Console.WriteLine($"✗ 版本 {version.Version} 下载错误: {args.Exception.Message}"); }) - // 异常处理 | Exception handling + // 异常处理 .AddListenerException((sender, args) => { Console.WriteLine($"⚠ 更新异常: {args.Exception.Message}\n{args.Exception.StackTrace}"); @@ -570,7 +518,7 @@ await new GeneralClientBootstrap() .LaunchAsync(); ``` -### 示例 5：自定义操作和跳过选项 | Example 5: Custom Operations and Skip Options +### 示例 5:自定义操作和跳过选项 ```csharp using GeneralUpdate.ClientCore; @@ -585,18 +533,18 @@ var config = new Configinfo await new GeneralClientBootstrap() .SetConfig(config) - // 添加自定义操作（更新前检查环境）| Add custom operation (check environment before update) + // 添加自定义操作(更新前检查环境) .AddCustomOption(async () => { Console.WriteLine("正在检查运行环境..."); await Task.Delay(1000); - // 检查磁盘空间、依赖项等 | Check disk space, dependencies, etc. + // 检查磁盘空间、依赖项等 Console.WriteLine("环境检查完成"); }) - // 设置用户跳过选项 | Set user skip option + // 设置用户跳过选项 .SetCustomSkipOption(() => { - Console.WriteLine("发现新版本，是否更新？(y/n)"); + Console.WriteLine("发现新版本,是否更新?(y/n)"); var input = Console.ReadLine(); return input?.ToLower() == "y"; }) @@ -605,58 +553,43 @@ await new GeneralClientBootstrap() --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **版本号格式 | Version Number Format** - - 版本号必须遵循语义化版本规范（如 1.0.0.0） +1. **版本号格式** + - 版本号必须遵循语义化版本规范(如 1.0.0.0) - 确保客户端和服务器端版本号格式一致 - - 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** +2. **网络连接** - 确保更新服务器地址可访问 - 建议实现重试机制处理网络波动 - - Ensure update server address is accessible - - Recommend implementing retry mechanism to handle network fluctuations -3. **进程管理 | Process Management** +3. **进程管理** - 更新过程会关闭主程序并启动升级助手 - 确保保存所有用户数据后再执行更新 - - 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** +4. **权限要求** - 在 Windows 上可能需要管理员权限来替换文件 - 在 Linux/macOS 上需要适当的文件系统权限 - - Administrator privileges may be required on Windows to replace files - - Appropriate file system permissions are required on Linux/macOS -5. **黑名单使用 | Blacklist Usage** +5. **黑名单使用** - 黑名单中的文件和目录不会被更新 - 常用于保护配置文件、用户数据等 - - Files and directories in the blacklist will not be updated - - Commonly used to protect configuration files, user data, etc. - -### 💡 最佳实践 | Best Practices - -- **备份策略**：始终启用 BackUp 选项，以便更新失败时可以回滚 -- **差异更新**：启用 Patch 选项以减少下载量和更新时间 -- **错误处理**：实现完整的异常监听和错误处理逻辑 -- **用户体验**：在更新前提示用户并允许选择更新时机 -- **测试验证**：在生产环境部署前充分测试更新流程 -- **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**: Prompt users before updating and allow them to choose update timing -- **Testing**: Thoroughly test the update process before production deployment + +### 💡 最佳实践 + +- **备份策略**:始终启用 BackUp 选项,以便更新失败时可以回滚 +- **差异更新**:启用 Patch 选项以减少下载量和更新时间 +- **错误处理**:实现完整的异常监听和错误处理逻辑 +- **用户体验**:在更新前提示用户并允许选择更新时机 +- **测试验证**:在生产环境部署前充分测试更新流程 --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | +| 产品 | 版本 | | ------------------ | -------------------- | | .NET | 5, 6, 7, 8, 9, 10 | | .NET Framework | 4.6.1 | @@ -665,7 +598,7 @@ await new GeneralClientBootstrap() --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Client/Program.cs) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) +- **示例代码**:[查看 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 09ce675..7e60681 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 @@ -4,14 +4,12 @@ sidebar_position: 5 # GeneralUpdate.Core -## 组件概览 | Component Overview +## 组件概览 -**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一，提供了完整的升级执行能力。与 ClientCore 不同，Core 组件作为独立的升级助手程序运行，负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式，Core 接收来自 ClientCore 的更新指令，并安全地完成主程序的升级任务。 +**GeneralUpdate.Core** 是 GeneralUpdate 框架最核心的组件之一,提供了完整的升级执行能力。与 ClientCore 不同,Core 组件作为独立的升级助手程序运行,负责在主程序关闭后执行实际的文件替换、版本升级和系统更新操作。通过进程启动和参数传递的方式,Core 接收来自 ClientCore 的更新指令,并安全地完成主程序的升级任务。 -**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. - -**命名空间 | Namespace:** `GeneralUpdate.Core` -**程序集 | Assembly:** `GeneralUpdate.Core.dll` +**命名空间:** `GeneralUpdate.Core` +**程序集:** `GeneralUpdate.Core.dll` ```csharp public class GeneralUpdateBootstrap : AbstractBootstrap @@ -19,48 +17,44 @@ public class GeneralUpdateBootstrap : AbstractBootstrap LaunchAsync() ``` -**返回值 | Return Value:** -- 返回当前 GeneralUpdateBootstrap 实例，支持链式调用 -- Returns the current GeneralUpdateBootstrap instance, supporting method chaining +**返回值:** +- 返回当前 GeneralUpdateBootstrap 实例,支持链式调用 -#### Option 方法 | Option Method +#### Option 方法 设置升级选项。 -Set upgrade options. - ```csharp public GeneralUpdateBootstrap Option(UpdateOption option, object value) ``` -**参数 | Parameters:** -- `option`: 升级选项枚举 | Upgrade option enum -- `value`: 选项值 | Option value +**参数:** +- `option`: 升级选项枚举 +- `value`: 选项值 -**示例 | Example:** +**示例:** ```csharp -.Option(UpdateOption.Drive, true) // 启用驱动升级 | Enable driver upgrade +.Option(UpdateOption.Drive, true) // 启用驱动升级 ``` -#### AddListenerMultiDownloadStatistics 方法 | AddListenerMultiDownloadStatistics Method - -监听下载统计信息（速度、进度、剩余时间等）。 +#### AddListenerMultiDownloadStatistics 方法 -Listen for download statistics (speed, progress, remaining time, etc.). +监听下载统计信息(速度、进度、剩余时间等)。 ```csharp public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics( Action callbackAction) ``` -#### AddListenerMultiDownloadCompleted 方法 | AddListenerMultiDownloadCompleted Method +#### AddListenerMultiDownloadCompleted 方法 监听单个更新包下载完成事件。 -Listen for single update package download completion event. - ```csharp public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiAllDownloadCompleted 方法 | AddListenerMultiAllDownloadCompleted Method +#### AddListenerMultiAllDownloadCompleted 方法 监听所有版本下载完成事件。 -Listen for all version downloads completion event. - ```csharp public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted( Action callbackAction) ``` -#### AddListenerMultiDownloadError 方法 | AddListenerMultiDownloadError Method +#### AddListenerMultiDownloadError 方法 监听每个版本下载错误事件。 -Listen for download error events for each version. - ```csharp public GeneralUpdateBootstrap AddListenerMultiDownloadError( Action callbackAction) ``` -#### AddListenerException 方法 | AddListenerException Method +#### AddListenerException 方法 监听升级组件内部所有异常。 -Listen for all internal exceptions in the upgrade component. - ```csharp public GeneralUpdateBootstrap AddListenerException( Action callbackAction) ``` -#### SetFieldMappings 方法 | SetFieldMappings Method +#### SetFieldMappings 方法 -设置字段映射表，用于解析驱动包信息。 - -Set field mapping table for parsing driver package information. +设置字段映射表,用于解析驱动包信息。 ```csharp public GeneralUpdateBootstrap SetFieldMappings(Dictionary fieldMappings) ``` -**参数 | Parameters:** -- `fieldMappings`: 字段映射字典，键为英文字段名，值为本地化字段名 -- Field mapping dictionary, key is English field name, value is localized field name +**参数:** +- `fieldMappings`: 字段映射字典,键为英文字段名,值为本地化字段名 --- -## 配置类详解 | Configuration Class Details +## 配置类详解 -### UpdateOption 枚举 | UpdateOption Enum +### UpdateOption 枚举 ```csharp public enum UpdateOption { /// /// 是否启用驱动升级功能 - /// Whether to enable driver upgrade functionality /// Drive } ``` -### Packet 类 | Packet Class - -升级包信息类，由 ClientCore 通过参数传递给 Core： +### Packet 类 -Upgrade package information class, passed from ClientCore to Core via parameters: +升级包信息类,由 ClientCore 通过参数传递给 Core: ```csharp public class Packet { /// /// 主更新检查 API 地址 - /// Main update check API address /// public string MainUpdateUrl { get; set; } /// - /// 应用类型：1=客户端应用，2=更新应用 - /// Application type: 1=ClientApp, 2=UpdateApp + /// 应用类型:1=客户端应用,2=更新应用 /// public int AppType { get; set; } /// /// 更新检查 API 地址 - /// Update check API address /// public string UpdateUrl { get; set; } /// /// 需要启动的应用程序名称 - /// Name of the application to be launched /// public string AppName { get; set; } /// /// 主应用程序名称 - /// Main application name /// public string MainAppName { get; set; } /// - /// 更新包文件格式（默认为 Zip） - /// Update package file format (default is Zip) + /// 更新包文件格式(默认为 Zip) /// public string Format { get; set; } /// /// 是否需要升级更新应用 - /// Indicates if the update application needs to be upgraded /// public bool IsUpgradeUpdate { get; set; } /// /// 是否需要更新主应用 - /// Indicates if the main application needs to be updated /// public bool IsMainUpdate { get; set; } /// /// 更新日志网页 URL - /// Update log webpage URL /// public string UpdateLogUrl { get; set; } /// /// 需要更新的版本信息列表 - /// List of version information that needs updating /// public List UpdateVersions { get; set; } /// /// 文件操作编码格式 - /// File operation encoding format /// public Encoding Encoding { get; set; } /// - /// 下载超时时间（秒） - /// Download timeout duration (seconds) + /// 下载超时时间(秒) /// public int DownloadTimeOut { get; set; } /// - /// 应用密钥，与服务器约定 - /// Application secret key, agreed upon with the server + /// 应用密钥,与服务器约定 /// public string AppSecretKey { get; set; } /// /// 当前客户端版本 - /// Current client version /// public string ClientVersion { get; set; } /// /// 最新版本 - /// Latest version /// public string LastVersion { get; set; } /// - /// 安装路径（用于更新文件逻辑） - /// Installation path (used for update file logic) + /// 安装路径(用于更新文件逻辑) /// public string InstallPath { get; set; } /// /// 下载文件的临时存储路径 - /// Temporary storage path for downloaded files /// public string TempPath { get; set; } /// - /// 升级终端程序的配置参数（Base64 编码） - /// Configuration parameters for the upgrade terminal program (Base64 encoded) + /// 升级终端程序的配置参数(Base64 编码) /// public string ProcessBase64 { get; set; } /// - /// 当前策略所属平台（Windows/Linux/Mac） - /// Platform to which the current strategy belongs (Windows/Linux/Mac) + /// 当前策略所属平台(Windows/Linux/Mac) /// public string Platform { get; set; } /// /// 黑名单文件列表 - /// Files in the blacklist /// public List BlackFiles { get; set; } /// /// 黑名单文件格式列表 - /// File formats in the blacklist /// public List BlackFormats { get; set; } /// /// 是否启用驱动升级功能 - /// Indicates if the driver upgrade feature is enabled /// public bool DriveEnabled { get; set; } } @@ -401,9 +352,9 @@ public class Packet --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：基本升级流程 | Example 1: Basic Upgrade Process +### 示例 1:基本升级流程 ```csharp using GeneralUpdate.Common.Download; @@ -415,7 +366,7 @@ try { Console.WriteLine("升级程序初始化..."); - // 启动升级流程 | Launch upgrade process + // 启动升级流程 await new GeneralUpdateBootstrap() .AddListenerMultiDownloadStatistics((sender, args) => { @@ -428,7 +379,7 @@ try }) .LaunchAsync(); - Console.WriteLine("升级完成！"); + Console.WriteLine("升级完成!"); } catch (Exception e) { @@ -436,13 +387,13 @@ catch (Exception e) } ``` -### 示例 2：启用驱动升级 | Example 2: Enable Driver Upgrade +### 示例 2:启用驱动升级 ```csharp using GeneralUpdate.Core; using GeneralUpdate.Common.Internal.Bootstrap; -// 中文字段映射表 | Chinese field mapping table +// 中文字段映射表 var fieldMappingsCN = new Dictionary { { "DriverName", "驱动名称" }, @@ -452,9 +403,9 @@ var fieldMappingsCN = new Dictionary }; await new GeneralUpdateBootstrap() - // 设置字段映射表 | Set field mappings + // 设置字段映射表 .SetFieldMappings(fieldMappingsCN) - // 启用驱动更新 | Enable driver update + // 启用驱动更新 .Option(UpdateOption.Drive, true) .AddListenerException((sender, args) => { @@ -463,7 +414,7 @@ await new GeneralUpdateBootstrap() .LaunchAsync(); ``` -### 示例 3：完整事件监听 | Example 3: Complete Event Listening +### 示例 3:完整事件监听 ```csharp using GeneralUpdate.Core; @@ -471,7 +422,7 @@ using GeneralUpdate.Common.Download; using GeneralUpdate.Common.Shared.Object; await new GeneralUpdateBootstrap() - // 下载统计 | Download statistics + // 下载统计 .AddListenerMultiDownloadStatistics((sender, args) => { var version = args.Version as VersionInfo; @@ -481,37 +432,37 @@ await new GeneralUpdateBootstrap() Console.WriteLine($" 已下载: {args.BytesReceived} / {args.TotalBytesToReceive}"); Console.WriteLine($" 剩余时间: {args.Remaining}"); }) - // 单个下载完成 | Single download completed + // 单个下载完成 .AddListenerMultiDownloadCompleted((sender, args) => { var version = args.Version as VersionInfo; string status = args.IsComplated ? "✓ 成功" : "✗ 失败"; Console.WriteLine($"版本 {version.Version} 下载{status}"); }) - // 所有下载完成 | All downloads completed + // 所有下载完成 .AddListenerMultiAllDownloadCompleted((sender, args) => { if (args.IsAllDownloadCompleted) { - Console.WriteLine("✓ 所有版本下载完成，开始安装..."); + Console.WriteLine("✓ 所有版本下载完成,开始安装..."); } else { - Console.WriteLine($"✗ 下载失败，{args.FailedVersions.Count} 个版本失败："); + Console.WriteLine($"✗ 下载失败,{args.FailedVersions.Count} 个版本失败:"); foreach (var version in args.FailedVersions) { Console.WriteLine($" - {version}"); } } }) - // 下载错误 | Download error + // 下载错误 .AddListenerMultiDownloadError((sender, args) => { var version = args.Version as VersionInfo; Console.WriteLine($"✗ 版本 {version.Version} 错误:"); Console.WriteLine($" {args.Exception.Message}"); }) - // 异常处理 | Exception handling + // 异常处理 .AddListenerException((sender, args) => { Console.WriteLine("⚠ 升级过程异常:"); @@ -521,14 +472,14 @@ await new GeneralUpdateBootstrap() .LaunchAsync(); ``` -### 示例 4：自定义升级流程 | Example 4: Custom Upgrade Process +### 示例 4:自定义升级流程 ```csharp using GeneralUpdate.Core; using GeneralUpdate.Common.Download; using GeneralUpdate.Common.Shared.Object; -// 记录升级开始时间 | Record upgrade start time +// 记录升级开始时间 var startTime = DateTime.Now; var downloadedVersions = new List(); @@ -546,14 +497,14 @@ await new GeneralUpdateBootstrap() if (args.IsAllDownloadCompleted) { var duration = DateTime.Now - startTime; - Console.WriteLine($"升级完成！"); + Console.WriteLine($"升级完成!"); Console.WriteLine($"总耗时: {duration.TotalSeconds:F2} 秒"); Console.WriteLine($"已更新版本: {string.Join(", ", downloadedVersions)}"); } }) .AddListenerException((sender, args) => { - // 记录日志到文件 | Log to file + // 记录日志到文件 File.AppendAllText("upgrade_error.log", $"[{DateTime.Now}] {args.Exception}\n"); }) @@ -562,58 +513,43 @@ await new GeneralUpdateBootstrap() --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **进程隔离 | Process Isolation** - - Core 必须作为独立进程运行，不能在主程序中直接调用 - - 升级时主程序必须完全关闭，否则文件替换会失败 - - Core must run as an independent process, cannot be called directly in the main program - - The main program must be completely closed during upgrade, otherwise file replacement will fail +1. **进程隔离** + - Core 必须作为独立进程运行,不能在主程序中直接调用 + - 升级时主程序必须完全关闭,否则文件替换会失败 -2. **参数传递 | Parameter Passing** +2. **参数传递** - ClientCore 通过 Base64 编码的参数传递配置给 Core - 确保参数传递过程中不会被截断或损坏 - - ClientCore passes configuration to Core via Base64 encoded parameters - - Ensure parameters are not truncated or corrupted during passing -3. **文件权限 | File Permissions** +3. **文件权限** - 在 Windows 上可能需要管理员权限替换系统目录中的文件 - 在 Linux/macOS 上需要适当的文件系统权限 - - Administrator privileges may be required on Windows to replace files in system directories - - Appropriate file system permissions are required on Linux/macOS -4. **驱动升级 | Driver Upgrade** +4. **驱动升级** - 驱动升级功能需要系统级权限 - 建议在测试环境充分验证后再使用 - - Driver upgrade functionality requires system-level permissions - - Recommended to thoroughly validate in test environment before use - -5. **回滚机制 | Rollback Mechanism** - - Core 不直接提供回滚功能，但保留了备份文件 - - 如需回滚，可使用 ClientCore 的备份功能 - - Core does not directly provide rollback functionality, but backup files are preserved - - For rollback, use ClientCore's backup functionality - -### 💡 最佳实践 | Best Practices - -- **日志记录**：实现完整的异常监听，记录升级过程中的所有问题 -- **超时设置**：根据网络环境合理设置下载超时时间 -- **进度反馈**：向用户显示升级进度，提升用户体验 -- **错误处理**：升级失败时提供清晰的错误信息和解决方案 -- **测试验证**：在各种网络条件下测试升级流程的稳定性 -- **Logging**: Implement complete exception listening to record all issues during the upgrade process -- **Timeout Settings**: Set download timeout appropriately based on network environment -- **Progress Feedback**: Display upgrade progress to users to improve user experience -- **Error Handling**: Provide clear error messages and solutions when upgrade fails -- **Testing**: Test upgrade process stability under various network conditions + +5. **回滚机制** + - Core 不直接提供回滚功能,但保留了备份文件 + - 如需回滚,可使用 ClientCore 的备份功能 + +### 💡 最佳实践 + +- **日志记录**:实现完整的异常监听,记录升级过程中的所有问题 +- **超时设置**:根据网络环境合理设置下载超时时间 +- **进度反馈**:向用户显示升级进度,提升用户体验 +- **错误处理**:升级失败时提供清晰的错误信息和解决方案 +- **测试验证**:在各种网络条件下测试升级流程的稳定性 --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | +| 产品 | 版本 | | ------------------ | ----------------- | | .NET | 5, 6, 7, 8, 9 | | .NET Framework | 4.6.1 | @@ -622,8 +558,8 @@ await new GeneralUpdateBootstrap() --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Upgrade/Program.cs) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) -- **相关组件**：[GeneralUpdate.ClientCore](./GeneralUpdate.ClientCore.md) | [GeneralUpdate.Bowl](./GeneralUpdate.Bowl.md) +- **示例代码**:[查看 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) 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 7bf5a80..edb101a 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 @@ -4,14 +4,12 @@ sidebar_position: 6 # GeneralUpdate.Differential -## 组件概览 | Component Overview +## 组件概览 -**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法，可以精确识别两个版本之间的文件变化，生成高效的增量补丁包，并支持补丁还原操作。通过使用差异更新，可以显著减少更新包的大小和下载时间，特别适合频繁发布更新的应用场景。 +**GeneralUpdate.Differential** 是 GeneralUpdate 框架中负责二进制差异更新的核心组件。该组件提供了强大的差异算法,可以精确识别两个版本之间的文件变化,生成高效的增量补丁包,并支持补丁还原操作。通过使用差异更新,可以显著减少更新包的大小和下载时间,特别适合频繁发布更新的应用场景。 -**GeneralUpdate.Differential** is the core component responsible for binary differential updates in the GeneralUpdate framework. This component provides powerful differential algorithms that can accurately identify file changes between two versions, generate efficient incremental patch packages, and support patch restoration operations. By using differential updates, you can significantly reduce update package size and download time, making it particularly suitable for scenarios with frequent update releases. - -**命名空间 | Namespace:** `GeneralUpdate.Differential` -**程序集 | Assembly:** `GeneralUpdate.Core.dll` +**命名空间:** `GeneralUpdate.Differential` +**程序集:** `GeneralUpdate.Core.dll` ```csharp public sealed class DifferentialCore @@ -19,102 +17,94 @@ public sealed class DifferentialCore --- -## 核心特性 | Core Features +## 核心特性 -### 1. 增量识别 | Incremental Identification -- 精确识别新增、修改、删除的文件 | Accurately identify added, modified, and deleted files -- 智能文件版本对比 | Intelligent file version comparison -- 支持跳过指定文件和格式 | Support skipping specified files and formats +### 1. 增量识别 +- 精确识别新增、修改、删除的文件 +- 智能文件版本对比 +- 支持跳过指定文件和格式 -### 2. 二进制补丁生成 | Binary Patch Generation -- 高效的二进制差异算法 | Efficient binary differential algorithm -- 最小化补丁文件大小 | Minimize patch file size -- 快速补丁生成速度 | Fast patch generation speed +### 2. 二进制补丁生成 +- 高效的二进制差异算法 +- 最小化补丁文件大小 +- 快速补丁生成速度 -### 3. 补丁还原 | Patch Restoration -- 安全的补丁应用流程 | Safe patch application process -- 自动处理文件依赖关系 | Automatic handling of file dependencies -- 完整性验证机制 | Integrity verification mechanism +### 3. 补丁还原 +- 安全的补丁应用流程 +- 自动处理文件依赖关系 +- 完整性验证机制 -### 4. 黑名单支持 | Blacklist Support -- 文件级黑名单 | File-level blacklist -- 格式级黑名单 | Format-level blacklist -- 灵活的过滤规则 | Flexible filtering rules +### 4. 黑名单支持 +- 文件级黑名单 +- 格式级黑名单 +- 灵活的过滤规则 --- -## 快速开始 | Quick Start - -### 安装 | Installation +## 快速开始 -通过 NuGet 安装 GeneralUpdate.Differential（包含在 Core 包中）： +### 安装 -Install GeneralUpdate.Differential via NuGet (included in Core package): +通过 NuGet 安装 GeneralUpdate.Differential(包含在 Core 包中): ```bash dotnet add package GeneralUpdate.Core ``` -### 初始化与使用 | Initialization and Usage - -以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作： +### 初始化与使用 -The following example demonstrates how to use DifferentialCore for incremental identification and patch operations: +以下示例展示了如何使用 DifferentialCore 进行增量识别和补丁操作: ```csharp using GeneralUpdate.Differential; -// 增量识别并生成二进制补丁 | Identify increments and generate binary patches -var sourcePath = @"D:\packet\app"; // 旧版本路径 | Old version path -var targetPath = @"D:\packet\release"; // 新版本路径 | New version path -var patchPath = @"D:\packet\patch"; // 补丁输出路径 | Patch output path +// 增量识别并生成二进制补丁 +var sourcePath = @"D:\packet\app"; // 旧版本路径 +var targetPath = @"D:\packet\release"; // 新版本路径 +var patchPath = @"D:\packet\patch"; // 补丁输出路径 await DifferentialCore.Instance?.Clean(sourcePath, targetPath, patchPath); -// 应用补丁（还原） | Apply patches (restoration) +// 应用补丁(还原) await DifferentialCore.Instance?.Dirty(sourcePath, patchPath); ``` --- -## 核心 API 参考 | Core API Reference +## 核心 API 参考 -### DifferentialCore 类 | DifferentialCore Class +### DifferentialCore 类 -#### Instance 属性 | Instance Property +#### Instance 属性 获取 DifferentialCore 的单例实例。 -Get the singleton instance of DifferentialCore. - ```csharp public static DifferentialCore Instance { get; } ``` -#### Clean 方法 | Clean Method - -执行增量识别、删除文件识别，并生成二进制补丁文件。 +#### Clean 方法 -Perform incremental identification, deleted file identification, and generate binary patch files. +执行增量识别、删除文件识别,并生成二进制补丁文件。 -**方法签名 | Method Signature:** +**方法签名:** ```csharp public async Task Clean(string sourcePath, string targetPath, string patchPath = null) ``` -**参数 | Parameters:** -- `sourcePath`: 旧版本文件夹路径 | Path to the old version folder -- `targetPath`: 新版本文件夹路径 | Path to the new version folder -- `patchPath`: 补丁文件输出目录（可选）| Directory to store discovered incremental update files (optional) +**参数:** +- `sourcePath`: 旧版本文件夹路径 +- `targetPath`: 新版本文件夹路径 +- `patchPath`: 补丁文件输出目录(可选) -**功能说明 | Function Description:** +**功能说明:** 1. 对比 sourcePath 和 targetPath 两个目录 2. 识别新增、修改、删除的文件 3. 为修改的文件生成二进制差异补丁 4. 将补丁和新增文件保存到 patchPath -**示例 | Example:** +**示例:** ```csharp // 生成从 v1.0.0 到 v1.1.0 的补丁包 var source = @"D:\MyApp\v1.0.0"; @@ -122,46 +112,44 @@ var target = @"D:\MyApp\v1.1.0"; var patch = @"D:\MyApp\patches\v1.1.0"; await DifferentialCore.Instance.Clean(source, target, patch); -// 结果：patch 目录包含所有必要的增量更新文件 +// 结果:patch 目录包含所有必要的增量更新文件 ``` -#### Dirty 方法 | Dirty Method - -应用补丁，将旧版本文件更新到新版本。 +#### Dirty 方法 -Apply patches to update old version files to the new version. +应用补丁,将旧版本文件更新到新版本。 -**方法签名 | Method Signature:** +**方法签名:** ```csharp public async Task Dirty(string appPath, string patchPath) ``` -**参数 | Parameters:** -- `appPath`: 客户端应用程序目录（当前版本）| Client application directory (current version) -- `patchPath`: 补丁文件路径 | Path to the patch files +**参数:** +- `appPath`: 客户端应用程序目录(当前版本) +- `patchPath`: 补丁文件路径 -**功能说明 | Function Description:** +**功能说明:** 1. 读取 patchPath 中的补丁文件 2. 将补丁应用到 appPath 中的对应文件 3. 处理新增文件的复制 4. 处理删除文件的移除 -**示例 | Example:** +**示例:** ```csharp // 将补丁应用到当前应用程序 var appDir = AppDomain.CurrentDomain.BaseDirectory; var patchDir = Path.Combine(appDir, "temp", "patches"); await DifferentialCore.Instance.Dirty(appDir, patchDir); -// 结果：应用程序更新到新版本 +// 结果:应用程序更新到新版本 ``` --- -## 实际使用示例 | Practical Usage Examples +## 实际使用示例 -### 示例 1：基本补丁生成 | Example 1: Basic Patch Generation +### 示例 1:基本补丁生成 ```csharp using GeneralUpdate.Differential; @@ -170,33 +158,33 @@ public async Task GeneratePatchAsync() { try { - // 版本路径 | Version paths + // 版本路径 var oldVersion = @"D:\MyApp\1.0.0"; var newVersion = @"D:\MyApp\1.0.1"; var patchOutput = @"D:\MyApp\patches\1.0.1"; Console.WriteLine("开始生成补丁..."); - // 生成补丁 | Generate patches + // 生成补丁 await DifferentialCore.Instance.Clean(oldVersion, newVersion, patchOutput); - Console.WriteLine($"补丁生成完成！输出目录：{patchOutput}"); + Console.WriteLine($"补丁生成完成!输出目录:{patchOutput}"); - // 显示补丁信息 | Display patch information + // 显示补丁信息 var patchFiles = Directory.GetFiles(patchOutput, "*.*", SearchOption.AllDirectories); Console.WriteLine($"生成了 {patchFiles.Length} 个补丁文件"); long totalSize = patchFiles.Sum(f => new FileInfo(f).Length); - Console.WriteLine($"总补丁大小：{totalSize / 1024.0:F2} KB"); + Console.WriteLine($"总补丁大小:{totalSize / 1024.0:F2} KB"); } catch (Exception ex) { - Console.WriteLine($"补丁生成失败：{ex.Message}"); + Console.WriteLine($"补丁生成失败:{ex.Message}"); } } ``` -### 示例 2：应用补丁 | Example 2: Apply Patches +### 示例 2:应用补丁 ```csharp using GeneralUpdate.Differential; @@ -205,32 +193,32 @@ public async Task ApplyPatchAsync() { try { - // 应用程序目录 | Application directory + // 应用程序目录 var appDirectory = @"D:\MyApp\current"; - // 补丁目录 | Patch directory + // 补丁目录 var patchDirectory = @"D:\MyApp\patches\1.0.1"; Console.WriteLine("开始应用补丁..."); - // 验证补丁存在 | Verify patch exists + // 验证补丁存在 if (!Directory.Exists(patchDirectory)) { - throw new DirectoryNotFoundException($"补丁目录不存在：{patchDirectory}"); + throw new DirectoryNotFoundException($"补丁目录不存在:{patchDirectory}"); } - // 应用补丁 | Apply patches + // 应用补丁 await DifferentialCore.Instance.Dirty(appDirectory, patchDirectory); - Console.WriteLine("补丁应用成功！应用程序已更新到新版本。"); + Console.WriteLine("补丁应用成功!应用程序已更新到新版本。"); } catch (Exception ex) { - Console.WriteLine($"补丁应用失败：{ex.Message}"); + Console.WriteLine($"补丁应用失败:{ex.Message}"); } } ``` -### 示例 3：完整的补丁流程 | Example 3: Complete Patch Workflow +### 示例 3:完整的补丁流程 ```csharp using GeneralUpdate.Differential; @@ -238,7 +226,7 @@ using System.IO.Compression; public class PatchManager { - // 生成并打包补丁 | Generate and package patches + // 生成并打包补丁 public async Task CreatePatchPackageAsync( string oldVersionPath, string newVersionPath, @@ -246,14 +234,14 @@ public class PatchManager { try { - // 1. 生成补丁文件 | Generate patch files + // 1. 生成补丁文件 var tempPatchDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); Directory.CreateDirectory(tempPatchDir); Console.WriteLine($"正在生成补丁..."); await DifferentialCore.Instance.Clean(oldVersionPath, newVersionPath, tempPatchDir); - // 2. 压缩补丁文件 | Compress patch files + // 2. 压缩补丁文件 var patchZipPath = Path.Combine(outputPath, "patch_1.0.1.zip"); Console.WriteLine($"正在打包补丁..."); @@ -263,69 +251,69 @@ public class PatchManager ZipFile.CreateFromDirectory(tempPatchDir, patchZipPath, CompressionLevel.Optimal, false); - // 3. 清理临时文件 | Clean up temp files + // 3. 清理临时文件 Directory.Delete(tempPatchDir, true); var patchSize = new FileInfo(patchZipPath).Length; - Console.WriteLine($"补丁包创建成功：{patchZipPath}"); - Console.WriteLine($"补丁包大小：{patchSize / 1024.0:F2} KB"); + Console.WriteLine($"补丁包创建成功:{patchZipPath}"); + Console.WriteLine($"补丁包大小:{patchSize / 1024.0:F2} KB"); return patchZipPath; } catch (Exception ex) { - Console.WriteLine($"创建补丁包失败：{ex.Message}"); + Console.WriteLine($"创建补丁包失败:{ex.Message}"); throw; } } - // 解压并应用补丁 | Extract and apply patches + // 解压并应用补丁 public async Task ApplyPatchPackageAsync(string appPath, string patchZipPath) { try { - // 1. 解压补丁包 | Extract patch package + // 1. 解压补丁包 var tempExtractDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString()); Directory.CreateDirectory(tempExtractDir); Console.WriteLine($"正在解压补丁包..."); ZipFile.ExtractToDirectory(patchZipPath, tempExtractDir); - // 2. 应用补丁 | Apply patches + // 2. 应用补丁 Console.WriteLine($"正在应用补丁..."); await DifferentialCore.Instance.Dirty(appPath, tempExtractDir); - // 3. 清理临时文件 | Clean up temp files + // 3. 清理临时文件 Directory.Delete(tempExtractDir, true); - Console.WriteLine($"补丁应用成功！"); + Console.WriteLine($"补丁应用成功!"); } catch (Exception ex) { - Console.WriteLine($"应用补丁包失败：{ex.Message}"); + Console.WriteLine($"应用补丁包失败:{ex.Message}"); throw; } } } -// 使用示例 | Usage example +// 使用示例 var manager = new PatchManager(); -// 创建补丁包 | Create patch package +// 创建补丁包 var patchZip = await manager.CreatePatchPackageAsync( @"D:\MyApp\1.0.0", @"D:\MyApp\1.0.1", @"D:\MyApp\releases" ); -// 应用补丁包 | Apply patch package +// 应用补丁包 await manager.ApplyPatchPackageAsync( @"D:\MyApp\current", patchZip ); ``` -### 示例 4：带进度显示的补丁操作 | Example 4: Patch Operations with Progress Display +### 示例 4:带进度显示的补丁操作 ```csharp using GeneralUpdate.Differential; @@ -342,18 +330,18 @@ public class ProgressivePatchManager { progress?.Report("开始扫描文件差异..."); - // 在实际场景中，可以在 Clean 前后添加进度报告 + // 在实际场景中,可以在 Clean 前后添加进度报告 await DifferentialCore.Instance.Clean(sourcePath, targetPath, patchPath); - progress?.Report("补丁生成完成！"); + progress?.Report("补丁生成完成!"); - // 统计信息 | Statistics + // 统计信息 var files = Directory.GetFiles(patchPath, "*.*", SearchOption.AllDirectories); progress?.Report($"共生成 {files.Length} 个补丁文件"); } catch (Exception ex) { - progress?.Report($"错误：{ex.Message}"); + progress?.Report($"错误:{ex.Message}"); throw; } } @@ -369,17 +357,17 @@ public class ProgressivePatchManager await DifferentialCore.Instance.Dirty(appPath, patchPath); - progress?.Report("补丁应用成功！"); + progress?.Report("补丁应用成功!"); } catch (Exception ex) { - progress?.Report($"错误：{ex.Message}"); + progress?.Report($"错误:{ex.Message}"); throw; } } } -// 使用示例 | Usage example +// 使用示例 var manager = new ProgressivePatchManager(); var progress = new Progress(msg => Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {msg}")); @@ -392,74 +380,59 @@ await manager.GeneratePatchWithProgressAsync( ``` --- -## 注意事项与警告 | Notes and Warnings +## 注意事项与警告 -### ⚠️ 重要提示 | Important Notes +### ⚠️ 重要提示 -1. **文件名限制 | File Name Restrictions** - - 不能包含同名但扩展名不同的文件（如 file.txt 和 file.log） +1. **文件名限制** + - 不能包含同名但扩展名不同的文件(如 file.txt 和 file.log) - 建议使用唯一的文件名命名规则 - - Cannot include files with the same name but different extensions (e.g., file.txt and file.log) - - Recommended to use unique file naming conventions -2. **目录结构 | Directory Structure** +2. **目录结构** - 源目录和目标目录的相对结构应保持一致 - 补丁生成时会保留目录层次关系 - - The relative structure of source and target directories should remain consistent - - Directory hierarchy is preserved during patch generation -3. **磁盘空间 | Disk Space** +3. **磁盘空间** - 确保有足够的磁盘空间存储补丁文件 - - 二进制差异补丁通常比完整文件小，但仍需要临时空间 - - Ensure sufficient disk space for storing patch files - - Binary differential patches are usually smaller than complete files, but still require temporary space + - 二进制差异补丁通常比完整文件小,但仍需要临时空间 -4. **文件占用 | File Locking** - - 应用补丁时，确保目标文件没有被其他进程占用 +4. **文件占用** + - 应用补丁时,确保目标文件没有被其他进程占用 - 建议在应用程序关闭后应用补丁 - - When applying patches, ensure target files are not locked by other processes - - Recommended to apply patches after the application is closed -5. **备份建议 | Backup Recommendations** +5. **备份建议** - 在应用补丁前建议备份原始文件 - 可以使用 ClientCore 的 BackUp 选项自动备份 - - Recommended to backup original files before applying patches - - Can use ClientCore's BackUp option for automatic backup -### 💡 最佳实践 | Best Practices +### 💡 最佳实践 -- **版本管理**：为每个版本维护独立的补丁包，便于版本追踪和回滚 -- **补丁验证**：生成补丁后进行验证测试，确保补丁可以正确应用 -- **增量更新**：优先使用差异更新而非全量更新，可节省 50%-90% 的下载量 -- **错误处理**：实现完整的异常捕获和错误恢复机制 -- **性能优化**：对于大文件，差异算法的性能优势更加明显 -- **Version Management**: Maintain separate patch packages for each version for easier version tracking and rollback -- **Patch Validation**: Perform validation testing after generating patches to ensure they can be applied correctly -- **Incremental Updates**: Prioritize differential updates over full updates, which can save 50%-90% of download size -- **Error Handling**: Implement complete exception capture and error recovery mechanisms -- **Performance Optimization**: For large files, the performance advantage of the differential algorithm is more pronounced +- **版本管理**:为每个版本维护独立的补丁包,便于版本追踪和回滚 +- **补丁验证**:生成补丁后进行验证测试,确保补丁可以正确应用 +- **增量更新**:优先使用差异更新而非全量更新,可节省 50%-90% 的下载量 +- **错误处理**:实现完整的异常捕获和错误恢复机制 +- **性能优化**:对于大文件,差异算法的性能优势更加明显 -### 🔍 工作原理 | How It Works +### 🔍 工作原理 -**Clean 方法工作流程 | Clean Method Workflow:** +**Clean 方法工作流程:** 1. 扫描源目录和目标目录中的所有文件 2. 比较文件的MD5哈希值以识别变化 -3. 对于修改的文件，使用二进制差异算法生成补丁 -4. 对于新增文件，直接复制到补丁目录 +3. 对于修改的文件,使用二进制差异算法生成补丁 +4. 对于新增文件,直接复制到补丁目录 5. 记录删除的文件列表 -**Dirty 方法工作流程 | Dirty Method Workflow:** +**Dirty 方法工作流程:** 1. 读取补丁目录中的所有文件 -2. 对于补丁文件，应用到对应的原文件上 -3. 对于新增文件，直接复制到应用目录 +2. 对于补丁文件,应用到对应的原文件上 +3. 对于新增文件,直接复制到应用目录 4. 根据删除列表移除相应文件 5. 验证更新完整性 --- -## 适用平台 | Applicable Platforms +## 适用平台 -| 产品 Product | 版本 Version | +| 产品 | 版本 | | ------------------ | ----------------- | | .NET | 5, 6, 7, 8, 9 | | .NET Framework | 4.6.1 | @@ -468,8 +441,8 @@ await manager.GeneratePatchWithProgressAsync( --- -## 相关资源 | Related Resources +## 相关资源 -- **示例代码**：[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) | [View GitHub Examples](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) -- **主仓库**：[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) | [GeneralUpdate Project](https://github.com/GeneralLibrary/GeneralUpdate) -- **打包工具**：GeneralUpdate.PacketTool 项目依赖此组件实现差异打包 | The GeneralUpdate.PacketTool project depends on this component for differential packaging +- **示例代码**:[查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Diff) +- **主仓库**:[GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate) +- **打包工具**:GeneralUpdate.PacketTool 项目依赖此组件实现差异打包