将Feature/XP.Common和Feature/XP.Hardware分支合并至Develop/XP.forHardwareAndCommon，完善XPapp注册和相关硬件类库通用类库功能。

2026-04-16 17:31:13 +08:00
parent 6ec4c3ddaa
commit 2bd6e566c3
581 changed files with 74600 additions and 222 deletions
@@ -0,0 +1,183 @@
+# Dump 文件管理服务使用指南 | Dump File Management Service Usage Guide
+
+## 概述 | Overview
+
+XplorePlane 提供 Dump 文件管理功能，用于在应用程序崩溃或需要诊断时生成进程转储文件。支持三种触发方式：崩溃自动触发、定时触发和手动触发，并提供文件大小限制、自动清理和可配置存储路径等管理能力。
+
+Dump 功能通过 Windows `MiniDumpWriteDump` API 实现，作为 `XP.Common` 的子模块集成到 `CommonModule` 中。
+
+## 基本用法 | Basic Usage
+
+### 通过依赖注入获取服务 | Get Service via DI
+
+```csharp
+public class DiagnosticsService
+{
+    private readonly IDumpService _dumpService;
+    private readonly ILoggerService _logger;
+
+    public DiagnosticsService(IDumpService dumpService, ILoggerService logger)
+    {
+        _dumpService = dumpService ?? throw new ArgumentNullException(nameof(dumpService));
+        _logger = logger?.ForModule<DiagnosticsService>() ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <summary>
+    /// 手动生成 Mini Dump | Manually generate Mini Dump
+    /// </summary>
+    public void CaptureMiniDump()
+    {
+        var filePath = _dumpService.CreateMiniDump();
+        if (filePath != null)
+        {
+            _logger.Info("Mini Dump 已生成：{FilePath} | Mini Dump generated: {FilePath}", filePath);
+        }
+    }
+
+    /// <summary>
+    /// 手动生成 Full Dump（包含完整内存）| Manually generate Full Dump (full memory)
+    /// </summary>
+    public void CaptureFullDump()
+    {
+        var filePath = _dumpService.CreateFullDump();
+        if (filePath != null)
+        {
+            _logger.Info("Full Dump 已生成：{FilePath} | Full Dump generated: {FilePath}", filePath);
+        }
+    }
+}
+```
+
+## 触发方式 | Trigger Modes
+
+### 1. 崩溃自动触发 | Crash Auto Trigger
+
+服务启动后自动订阅 `AppDomain.CurrentDomain.UnhandledException` 和 `TaskScheduler.UnobservedTaskException`，无需额外配置。崩溃时自动生成 Mini Dump。
+
+### 2. 定时触发 | Scheduled Trigger
+
+在 `App.config` 中启用定时触发后，服务按配置的时间间隔周期性生成 Mini Dump：
+
+```xml
+<add key="Dump:EnableScheduledDump" value="true" />
+<add key="Dump:ScheduledIntervalMinutes" value="60" />
+```
+
+### 3. 手动触发 | Manual Trigger
+
+通过 `IDumpService` 接口的方法手动触发：
+
+```csharp
+// 生成 Mini Dump（线程信息 + 数据段 + 句柄信息）
+// Generate Mini Dump (thread info + data segments + handle data)
+string? miniPath = _dumpService.CreateMiniDump();
+
+// 生成 Full Dump（完整内存，仅手动触发允许）
+// Generate Full Dump (full memory, manual trigger only)
+string? fullPath = _dumpService.CreateFullDump();
+```
+
+## Dump 类型说明 | Dump Type Description
+
+| 类型 | 包含内容 | 文件大小 | 触发限制 |
+|------|----------|----------|----------|
+| Mini Dump | 线程信息、数据段、句柄信息 | 较小（受大小限制约束） | 所有触发方式 |
+| Full Dump | 进程完整内存 | 较大（无大小限制） | 仅手动触发 |
+
+> 非手动触发（崩溃、定时）请求 Full Dump 时，系统会自动降级为 Mini Dump。
+
+## 文件命名规则 | File Naming Convention
+
+格式：`XplorePlane_{yyyyMMdd_HHmm}_{TriggerType}.dmp`
+
+示例：
+- `XplorePlane_20260317_1530_Crash.dmp` — 崩溃触发
+- `XplorePlane_20260317_1600_Scheduled.dmp` — 定时触发
+- `XplorePlane_20260317_1645_Manual.dmp` — 手动触发
+
+## 自动清理 | Auto Cleanup
+
+- 服务启动时立即执行一次清理
+- 运行期间每 24 小时执行一次清理
+- 超过保留天数（默认 7 天）的 `.dmp` 文件会被自动删除
+- 单个文件删除失败不影响其余文件的清理
+
+## 配置 | Configuration
+
+在 `App.config` 的 `<appSettings>` 中配置：
+
+```xml
+<appSettings>
+  <!-- Dump 文件存储路径 | Dump file storage path -->
+  <add key="Dump:StoragePath" value="D:\XplorePlane\Dump" />
+  <!-- 是否启用定时触发 | Enable scheduled trigger -->
+  <add key="Dump:EnableScheduledDump" value="false" />
+  <!-- 定时触发间隔（分钟）| Scheduled trigger interval (minutes) -->
+  <add key="Dump:ScheduledIntervalMinutes" value="60" />
+  <!-- Mini Dump 文件大小上限（MB）| Mini Dump file size limit (MB) -->
+  <add key="Dump:MiniDumpSizeLimitMB" value="100" />
+  <!-- 文件保留天数 | File retention days -->
+  <add key="Dump:RetentionDays" value="7" />
+</appSettings>
+```
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `Dump:StoragePath` | `D:\XplorePlane\Dump` | Dump 文件存储路径 |
+| `Dump:EnableScheduledDump` | `false` | 是否启用定时触发 |
+| `Dump:ScheduledIntervalMinutes` | `60` | 定时触发间隔（分钟） |
+| `Dump:MiniDumpSizeLimitMB` | `100` | Mini Dump 文件大小上限（MB），超过则删除 |
+| `Dump:RetentionDays` | `7` | 文件保留天数，超过则自动清理 |
+
+## 错误处理 | Error Handling
+
+Dump 功能遵循"记录并继续"原则，自身错误不影响主应用程序运行：
+
+- Dump 文件写入失败 → 记录错误日志，返回 `null`，不抛出异常
+- Mini Dump 超过大小限制 → 删除文件，记录警告
+- 存储目录创建失败 → 回退到默认路径 `D:\XplorePlane\Dump`
+- 清理过程中文件删除失败 → 记录错误，继续清理其余文件
+
+## IDumpService 接口 | IDumpService Interface
+
+```csharp
+public interface IDumpService : IDisposable
+{
+    /// <summary>
+    /// 手动触发 Mini Dump 生成 | Manually trigger Mini Dump generation
+    /// </summary>
+    string? CreateMiniDump();
+
+    /// <summary>
+    /// 手动触发 Full Dump 生成 | Manually trigger Full Dump generation
+    /// </summary>
+    string? CreateFullDump();
+
+    /// <summary>
+    /// 启动服务 | Start service
+    /// </summary>
+    void Start();
+
+    /// <summary>
+    /// 停止服务 | Stop service
+    /// </summary>
+    void Stop();
+}
+```
+
+## 文件结构 | File Structure
+
+```
+XP.Common/Dump/
+├── Interfaces/
+│   └── IDumpService.cs          # 服务接口 | Service interface
+├── Implementations/
+│   ├── DumpService.cs           # 服务实现 | Service implementation
+│   └── DumpCleaner.cs           # 自动清理组件 | Auto cleanup component
+├── Configs/
+│   ├── DumpConfig.cs            # 配置实体 | Config entity
+│   └── DumpTriggerType.cs       # 触发类型枚举 | Trigger type enum
+└── Native/
+    ├── NativeMethods.cs         # P/Invoke 声明 | P/Invoke declarations
+    └── MiniDumpType.cs          # Dump 类型标志枚举 | Dump type flags enum
+```