LanMountainDesktop/docs/archive/Plugins develop/01-快速开始/04-调试运行指南.md

04-调试运行指南

掌握插件调试技巧，能大幅提升开发效率。本文介绍阑山桌面插件的各种调试方法和常见问题排查。

---

🔄 调试方式概述

阑山桌面插件有两种主要调试方式：

方式	适用场景	优点	缺点
附加到进程	日常开发调试	不改变项目结构	每次需手动附加
独立调试	深度调试、单元测试	启动即调试	配置较复杂

---

🎯 方式一：附加到进程（推荐）

这是日常开发中最常用的调试方式。

步骤

1. 启动阑山桌面

   • 正常启动宿主应用（非调试模式）
   • 确保你的插件已安装

2. 在 IDE 中打开插件项目

   • 使用 Visual Studio / Rider / VS Code 打开项目

3. 设置断点

   • 在你想要调试的代码行左侧点击，设置断点
   • 常见断点位置：
     • Plugin.Initialize() - 插件初始化
     • 组件构造函数
     • 设置页面加载方法

4. 附加到进程

   Visual Studio：

   • 菜单：调试 → 附加到进程
   • 或快捷键：Ctrl+Alt+P
   • 在列表中找到 LanMountainDesktop.exe
   • 点击附加

   Rider：

   • 菜单：Run → Attach to Process
   • 或快捷键：Ctrl+Alt+F5
   • 选择 LanMountainDesktop.exe

   VS Code：

   • 按 Ctrl+Shift+D 打开调试面板
   • 点击创建 launch.json 文件
   • 选择 .NET Core Attach
   • 选择 LanMountainDesktop 进程

5. 触发调试

   • 在阑山桌面中操作，触发插件代码
   • 例如：添加组件、打开设置页面等
   • 程序会在断点处暂停

附加配置（VS Code）

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "附加到阑山桌面",
      "type": "coreclr",
      "request": "attach",
      "processName": "LanMountainDesktop"
    }
  ]
}

---

🔧 方式二：独立调试

适用于深度调试或单元测试。

配置步骤

1. 修改 .csproj 临时引用宿主

   <ItemGroup>
     <!-- 临时添加，仅用于调试 -->
     <ProjectReference Include="..\LanMountainDesktop\LanMountainDesktop.csproj" />
   </ItemGroup>
   

2. 创建调试启动配置

   Visual Studio：

   • 右键项目 → 属性 → 调试
   • 启动外部程序：选择 LanMountainDesktop.exe
   • 工作目录：设为宿主输出目录

   VS Code launch.json：

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "启动阑山桌面(调试)",
         "type": "coreclr",
         "request": "launch",
         "program": "${workspaceFolder}/../LanMountainDesktop/bin/Debug/net10.0/LanMountainDesktop.exe",
         "args": [],
         "cwd": "${workspaceFolder}/../LanMountainDesktop/bin/Debug/net10.0",
         "stopAtEntry": false
       }
     ]
   }
   

3. 启动调试

   • 按 F5 启动
   • 宿主会以调试模式启动
   • 插件代码中的断点会直接命中

⚠️ 注意： 发布插件前务必移除临时引用！

---

📝 日志调试

当断点调试不方便时，日志是最有效的调试手段。

使用 ILogger

using Microsoft.Extensions.Logging;

public class MyService
{
    private readonly ILogger<MyService> _logger;

    public MyService(ILogger<MyService> logger)
    {
        _logger = logger;
    }

    public void DoWork()
    {
        _logger.LogInformation("开始执行任务");
        
        try
        {
            // 业务逻辑
            _logger.LogDebug("处理数据: {Data}", data);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "任务执行失败");
        }
        
        _logger.LogInformation("任务完成");
    }
}

日志级别

级别	使用场景
LogTrace	最详细的跟踪信息
LogDebug	调试信息
LogInformation	一般信息
LogWarning	警告信息
LogError	错误信息
LogCritical	严重错误

查看日志文件

日志文件位置：

Windows: %LOCALAPPDATA%\LanMountainDesktop\logs\
Linux:   ~/.local/share/LanMountainDesktop/logs/
macOS:   ~/Library/Application Support/LanMountainDesktop/logs/

日志文件命名格式：

log-20240413.txt
log-20240413_001.txt

实时查看日志

Windows PowerShell：

Get-Content "$env:LOCALAPPDATA\LanMountainDesktop\logs\log-$(Get-Date -Format 'yyyyMMdd').txt" -Wait

Linux/macOS：

tail -f ~/.local/share/LanMountainDesktop/logs/log-$(date +%Y%m%d).txt

---

🚫 热重载限制

⚠️ 重要： 阑山桌面插件不支持热重载（Hot Reload）

原因

插件运行在独立的 AssemblyLoadContext 中，.NET 不支持卸载已加载的程序集。因此：

• 修改代码后必须重新构建
• 必须重启宿主才能加载新版本
• 无法使用 dotnet watch

高效开发流程

修改代码 → dotnet build → 重启宿主 → 测试

加速技巧：

1. 创建批处理脚本（rebuild-and-run.ps1）：

   dotnet build
   Stop-Process -Name "LanMountainDesktop" -ErrorAction SilentlyContinue
   Start-Process "C:\Path\To\LanMountainDesktop.exe"
   

2. 使用 Rider 的外部工具：

   • 配置构建后自动复制 .laapp 到插件目录

---

🐛 常见问题排查

问题 1：断点不命中

可能原因：

• 插件未重新构建
• PDB 符号文件未生成
• 附加到了错误的进程

解决步骤：

1. 确认已重新构建：dotnet build
2. 检查输出目录是否有 .pdb 文件
3. 确认附加的是 LanMountainDesktop.exe（不是 LanMountainDesktop.dll）
4. 尝试清理重建：

   dotnet clean
   dotnet build
   

问题 2：插件不加载

排查步骤：

1. 检查日志

   Get-Content "$env:LOCALAPPDATA\LanMountainDesktop\logs\log-$(Get-Date -Format 'yyyyMMdd').txt" | Select-String "MyPlugin"
   

2. 验证 plugin.json

   • JSON 格式是否有效
   • id 是否合法（只含小写字母、数字、点号）
   • apiVersion 是否与 SDK 版本匹配

3. 检查 .laapp 包

   • 用压缩软件打开，确认文件完整
   • 确认 plugin.json 和 DLL 存在

问题 3：依赖项找不到

现象： FileNotFoundException 或 Could not load file or assembly

解决：

1. 确保所有依赖项都复制到输出目录
2. 在 .csproj 中添加：

   <PropertyGroup>
     <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
   </PropertyGroup>
   

问题 4：调试时宿主卡顿

原因： 断点暂停导致 UI 线程阻塞

解决：

• 使用 Debugger.Break() 代替断点
• 或使用日志代替断点调试

---

💡 调试技巧

1. 条件断点

当需要在特定条件下暂停时使用：

Visual Studio：

• 右键断点 → 条件
• 输入条件表达式，如：count > 10

2. 日志点（Tracepoint）

不暂停程序，只输出日志：

Visual Studio：

• 右键断点 → 操作
• 勾选 将消息输出到输出窗口
• 输入消息模板：变量值: {variableName}

3. 异常设置

自动在抛出异常时中断：

Visual Studio：

• 调试 → 窗口 → 异常设置
• 勾选 Common Language Runtime Exceptions

4. 立即窗口

在调试时执行代码：

Visual Studio：

• 快捷键：Ctrl+Alt+I
• 可查看变量值、调用方法

---

📊 性能调试

使用 Diagnostic Tools

Visual Studio：

• 调试时自动显示 CPU 和内存使用情况
• 调试 → 窗口 → 诊断工具

内存泄漏排查

// 在可疑位置添加诊断代码
GC.Collect();
GC.WaitForPendingFinalizers();
GC.Collect();
var memory = GC.GetTotalMemory(true);
Debug.WriteLine($"内存使用: {memory / 1024 / 1024} MB");

---

🎯 下一步

掌握了调试技巧后，接下来学习核心概念：

👉 01-插件生命周期 - 理解插件运行机制

或者查看实战案例：

👉 01-开发天气组件 - 完整开发流程

---

📚 参考资源

• PluginBase 源码
• docs/DEVELOPMENT.md
• Visual Studio 调试文档
• Rider 调试文档

---

最后更新：2026年4月