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

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：

<add key="Dump:EnableScheduledDump" value="true" />
<add key="Dump:ScheduledIntervalMinutes" value="60" />

3. 手动触发 | Manual Trigger

通过 IDumpService 接口的方法手动触发：

// 生成 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> 中配置：

<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

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