XplorePlane/XP.Common/Documents/Dump.README.md

# 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
```