mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-27 21:04:27 +08:00
feat.文档更新
This commit is contained in:
lincube
220
docs/archive/Plugins develop/01-快速开始/01-开发环境准备.md
Normal file
220
docs/archive/Plugins develop/01-快速开始/01-开发环境准备.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 01-开发环境准备
|
||||
|
||||
在开始开发阑山桌面插件之前，你需要准备好开发环境。本指南将带你完成所有必要的安装和配置。
|
||||
|
||||
---
|
||||
|
||||
## ✅ 系统要求
|
||||
|
||||
### 支持的操作系统
|
||||
|
||||
| 操作系统 | 版本要求 | 备注 |
|
||||
|---------|---------|------|
|
||||
| **Windows** | Windows 10 版本 1809 或更高 | 推荐开发平台 |
|
||||
| **Windows** | Windows 11 | 最佳体验 |
|
||||
| **Linux** | Ubuntu 20.04+ / Debian 10+ | 支持开发和运行 |
|
||||
| **macOS** | macOS 12+ | 支持开发和运行 |
|
||||
|
||||
### 硬件要求
|
||||
|
||||
- **处理器**：x64 或 ARM64 架构
|
||||
- **内存**：至少 4GB RAM（推荐 8GB）
|
||||
- **磁盘空间**：至少 2GB 可用空间
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 安装 .NET SDK
|
||||
|
||||
阑山桌面插件基于 **.NET 10** 开发，你需要安装对应版本的 SDK。
|
||||
|
||||
### 下载安装
|
||||
|
||||
1. 访问 [.NET 10 下载页面](https://dotnet.microsoft.com/download/dotnet/10.0)
|
||||
2. 下载适合你操作系统的 SDK 安装包
|
||||
3. 运行安装程序，按提示完成安装
|
||||
|
||||
### 验证安装
|
||||
|
||||
打开终端（PowerShell、CMD 或 Bash），运行以下命令：
|
||||
|
||||
```powershell
|
||||
# 检查 .NET SDK 版本
|
||||
dotnet --version
|
||||
```
|
||||
|
||||
✅ **预期输出示例：**
|
||||
```
|
||||
10.0.100
|
||||
```
|
||||
|
||||
⚠️ **如果版本低于 10.0**，请重新下载安装最新版 .NET 10 SDK。
|
||||
|
||||
---
|
||||
|
||||
## 💻 安装 IDE（集成开发环境）
|
||||
|
||||
你可以选择以下任一 IDE 进行开发：
|
||||
|
||||
### 选项 1：Visual Studio 2022（推荐 Windows 用户）
|
||||
|
||||
**优点：** 功能最全，调试体验最佳
|
||||
|
||||
1. 下载 [Visual Studio 2022](https://visualstudio.microsoft.com/vs/)
|
||||
2. 安装时选择以下工作负载：
|
||||
- ✅ **.NET 桌面开发**
|
||||
- ✅ **Avalonia UI 开发**（可选，如需 Avalonia 设计器）
|
||||
|
||||
### 选项 2：JetBrains Rider（跨平台推荐）
|
||||
|
||||
**优点：** 跨平台，智能提示强大，Avalonia 支持好
|
||||
|
||||
1. 下载 [Rider](https://www.jetbrains.com/rider/)
|
||||
2. 安装后打开，会自动检测 .NET SDK
|
||||
|
||||
### 选项 3：Visual Studio Code（轻量级）
|
||||
|
||||
**优点：** 免费，轻量，插件丰富
|
||||
|
||||
1. 下载 [VS Code](https://code.visualstudio.com/)
|
||||
2. 安装以下扩展：
|
||||
- **C# Dev Kit**（Microsoft 官方）
|
||||
- **Avalonia for VS Code**（可选）
|
||||
|
||||
---
|
||||
|
||||
## 📦 安装插件模板
|
||||
|
||||
阑山桌面提供了官方的 `dotnet new` 模板，帮助你快速创建插件项目。
|
||||
|
||||
### 安装模板
|
||||
|
||||
```powershell
|
||||
# 安装最新版插件模板
|
||||
dotnet new install LanMountainDesktop.PluginTemplate
|
||||
```
|
||||
|
||||
✅ **成功提示：**
|
||||
```
|
||||
模板名 短名称 语言 标签
|
||||
------------------------------------- ---------- ---- ------------
|
||||
LanMountainDesktop Plugin lmd-plugin C# LanMountainDesktop/Plugin
|
||||
```
|
||||
|
||||
### 验证安装
|
||||
|
||||
```powershell
|
||||
# 列出已安装的模板，查找 lmd-plugin
|
||||
dotnet new list | findstr lmd
|
||||
```
|
||||
|
||||
或（Linux/macOS）：
|
||||
```bash
|
||||
dotnet new list | grep lmd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎮 获取宿主应用
|
||||
|
||||
插件需要在阑山桌面宿主中运行，你需要获取宿主应用：
|
||||
|
||||
### 方式 1：下载 Release 版本（推荐）
|
||||
|
||||
1. 访问 GitHub Releases 页面
|
||||
2. 下载最新版本的安装包（.exe / .deb / .dmg）
|
||||
3. 安装并运行阑山桌面
|
||||
|
||||
### 方式 2：从源码构建
|
||||
|
||||
如果你想调试宿主或了解内部机制：
|
||||
|
||||
```powershell
|
||||
# 克隆仓库
|
||||
git clone https://github.com/your-org/LanMountainDesktop.git
|
||||
cd LanMountainDesktop
|
||||
|
||||
# 还原依赖
|
||||
dotnet restore
|
||||
|
||||
# 构建项目
|
||||
dotnet build LanMountainDesktop.slnx -c Debug
|
||||
|
||||
# 运行宿主
|
||||
dotnet run --project LanMountainDesktop/LanMountainDesktop.csproj
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 环境验证清单
|
||||
|
||||
在继续之前，请确认以下检查项都已完成：
|
||||
|
||||
| 检查项 | 验证命令 | 预期结果 |
|
||||
|-------|---------|---------|
|
||||
| ✅ .NET SDK 版本 | `dotnet --version` | 10.0.xxx |
|
||||
| ✅ 模板已安装 | `dotnet new list \| findstr lmd` | 显示 lmd-plugin |
|
||||
| ✅ IDE 可创建项目 | 在 IDE 中新建项目 | 能看到 C# 项目模板 |
|
||||
| ✅ 宿主可运行 | 双击 LanMountainDesktop.exe | 应用正常启动 |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 常见问题
|
||||
|
||||
### 问题 1：dotnet 命令找不到
|
||||
|
||||
**现象：** 运行 `dotnet` 提示不是内部或外部命令
|
||||
|
||||
**解决：**
|
||||
1. 确认 .NET SDK 已正确安装
|
||||
2. 重启终端或 IDE
|
||||
3. 检查环境变量 PATH 是否包含 `C:\Program Files\dotnet\`
|
||||
|
||||
### 问题 2：模板安装失败
|
||||
|
||||
**现象：** `dotnet new install` 报错或卡住
|
||||
|
||||
**解决：**
|
||||
1. 检查网络连接（需要访问 nuget.org）
|
||||
2. 尝试指定版本号：
|
||||
```powershell
|
||||
dotnet new install LanMountainDesktop.PluginTemplate::1.0.0
|
||||
```
|
||||
3. 清除模板缓存后重试：
|
||||
```powershell
|
||||
dotnet new uninstall LanMountainDesktop.PluginTemplate
|
||||
dotnet new install LanMountainDesktop.PluginTemplate
|
||||
```
|
||||
|
||||
### 问题 3：SDK 版本不匹配
|
||||
|
||||
**现象：** 构建时提示 SDK 版本不符合 global.json 要求
|
||||
|
||||
**解决：**
|
||||
1. 检查项目根目录的 `global.json` 文件
|
||||
2. 安装对应版本的 .NET SDK
|
||||
3. 或使用以下命令使用已安装的版本：
|
||||
```powershell
|
||||
dotnet new globaljson --sdk-version 10.0.100 --roll-forward latestFeature
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
环境准备完成！接下来：
|
||||
|
||||
👉 **[02-三分钟创建第一个插件](02-三分钟创建第一个插件.md)** - 立即开始创建你的第一个插件！
|
||||
|
||||
---
|
||||
|
||||
## 📚 参考资源
|
||||
|
||||
- [.NET 10 下载](https://dotnet.microsoft.com/download/dotnet/10.0)
|
||||
- [Visual Studio 2022](https://visualstudio.microsoft.com/vs/)
|
||||
- [JetBrains Rider](https://www.jetbrains.com/rider/)
|
||||
- [VS Code](https://code.visualstudio.com/)
|
||||
- [Avalonia UI 文档](https://docs.avaloniaui.net/)
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026年4月*
|
||||
236
docs/archive/Plugins develop/01-快速开始/02-三分钟创建第一个插件.md
Normal file
236
docs/archive/Plugins develop/01-快速开始/02-三分钟创建第一个插件.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# 02-三分钟创建第一个插件
|
||||
|
||||
本指南将帮助你在三分钟内创建并运行你的第一个阑山桌面插件。让我们开始吧！
|
||||
|
||||
---
|
||||
|
||||
## 🎯 目标
|
||||
|
||||
完成本指南后，你将：
|
||||
- ✅ 创建一个可运行的插件项目
|
||||
- ✅ 在宿主中成功加载插件
|
||||
- ✅ 在插件列表中看到你的插件
|
||||
|
||||
---
|
||||
|
||||
## ⚡ 步骤一：创建项目（30秒）
|
||||
|
||||
打开终端，运行以下命令：
|
||||
|
||||
```powershell
|
||||
# 创建插件项目
|
||||
dotnet new lmd-plugin -n MyFirstPlugin
|
||||
|
||||
# 进入项目目录
|
||||
cd MyFirstPlugin
|
||||
```
|
||||
|
||||
✅ **成功标志：** 命令执行后没有报错，且生成了 `MyFirstPlugin` 文件夹。
|
||||
|
||||
---
|
||||
|
||||
## 📝 步骤二：配置插件信息（30秒）
|
||||
|
||||
打开 `plugin.json` 文件，修改以下字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "com.yourname.myfirstplugin",
|
||||
"name": "我的第一个插件",
|
||||
"description": "这是一个测试插件",
|
||||
"author": "你的名字",
|
||||
"version": "1.0.0",
|
||||
"apiVersion": "5.0.0",
|
||||
"entranceAssembly": "MyFirstPlugin.dll",
|
||||
"sharedContracts": []
|
||||
}
|
||||
```
|
||||
|
||||
⚠️ **重要提示：**
|
||||
- `id` 必须是唯一的，建议使用反向域名格式（如 `com.yourname.pluginname`）
|
||||
- `apiVersion` 必须与 SDK 版本匹配
|
||||
- 保存文件时使用 **UTF-8** 编码
|
||||
|
||||
---
|
||||
|
||||
## 🔨 步骤三：构建项目（30秒）
|
||||
|
||||
在终端中运行：
|
||||
|
||||
```powershell
|
||||
# 构建项目
|
||||
dotnet build
|
||||
```
|
||||
|
||||
✅ **成功标志：** 看到类似以下的输出：
|
||||
```
|
||||
生成成功。
|
||||
0 个警告
|
||||
0 个错误
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 步骤四：找到插件包（15秒）
|
||||
|
||||
构建完成后，插件包位于：
|
||||
|
||||
```
|
||||
MyFirstPlugin/
|
||||
└── bin/
|
||||
└── Debug/
|
||||
└── net10.0/
|
||||
└── MyFirstPlugin.laapp <-- 这就是插件包！
|
||||
```
|
||||
|
||||
⚠️ **什么是 .laapp 文件？**
|
||||
- `.laapp` 是阑山桌面的插件包格式
|
||||
- 本质上是一个 ZIP 压缩包，包含插件 DLL 和资源文件
|
||||
- 不要解压，直接安装即可
|
||||
|
||||
---
|
||||
|
||||
## 🚀 步骤五：安装到宿主（30秒）
|
||||
|
||||
1. **启动阑山桌面**（如果尚未运行）
|
||||
|
||||
2. **打开设置**：
|
||||
- 右键点击桌面上的阑山桌面图标
|
||||
- 选择「设置」
|
||||
|
||||
3. **进入插件管理**：
|
||||
- 在设置窗口左侧选择「插件」
|
||||
|
||||
4. **安装本地插件**：
|
||||
- 点击「安装本地插件」按钮
|
||||
- 选择刚才生成的 `.laapp` 文件
|
||||
- 点击「打开」
|
||||
|
||||
5. **重启宿主**：
|
||||
- 安装完成后，点击「重启」按钮
|
||||
- 阑山桌面将重新启动
|
||||
|
||||
---
|
||||
|
||||
## ✅ 步骤六：验证安装（15秒）
|
||||
|
||||
重启后，再次打开设置 → 插件：
|
||||
|
||||
🎉 **成功标志：**
|
||||
- 在插件列表中看到「我的第一个插件」
|
||||
- 状态显示为「已启用」
|
||||
- 作者显示为你设置的名字
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📂 生成的项目结构
|
||||
|
||||
你的项目现在包含以下文件：
|
||||
|
||||
```
|
||||
MyFirstPlugin/
|
||||
├── plugin.json # 插件清单文件
|
||||
├── MyFirstPlugin.csproj # 项目文件
|
||||
├── Plugin.cs # 插件入口类
|
||||
├── README.md # 项目说明
|
||||
└── Localization/ # 本地化文件夹
|
||||
├── zh-CN.json # 中文资源
|
||||
└── en-US.json # 英文资源
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 查看插件代码
|
||||
|
||||
打开 `Plugin.cs`，你会看到：
|
||||
|
||||
```csharp
|
||||
using LanMountainDesktop.PluginSdk;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
|
||||
namespace MyFirstPlugin;
|
||||
|
||||
[PluginEntrance]
|
||||
public sealed class Plugin : PluginBase
|
||||
{
|
||||
public override void Initialize(HostBuilderContext context, IServiceCollection services)
|
||||
{
|
||||
// 插件初始化代码
|
||||
// 在这里注册组件、设置页面等
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**关键点：**
|
||||
- `[PluginEntrance]` 特性标记入口类
|
||||
- 继承 `PluginBase` 基类
|
||||
- `Initialize` 方法是插件的初始化入口
|
||||
|
||||
---
|
||||
|
||||
## 🎉 恭喜！
|
||||
|
||||
你已经成功创建并安装了第一个阑山桌面插件！
|
||||
|
||||
虽然这个插件目前还没有任何功能，但你已经掌握了：
|
||||
- ✅ 使用模板创建项目
|
||||
- ✅ 配置插件信息
|
||||
- ✅ 构建插件包
|
||||
- ✅ 安装到宿主
|
||||
|
||||
---
|
||||
|
||||
## 🚦 常见问题
|
||||
|
||||
### 问题 1：构建失败，提示找不到 SDK
|
||||
|
||||
**现象：** 错误信息包含 "SDK not found"
|
||||
|
||||
**解决：**
|
||||
1. 确认已安装 .NET 10 SDK：`dotnet --version`
|
||||
2. 检查 `global.json` 中的版本要求
|
||||
|
||||
### 问题 2：宿主提示插件安装失败
|
||||
|
||||
**现象：** 安装时弹出错误对话框
|
||||
|
||||
**排查步骤：**
|
||||
1. 检查 `plugin.json` 是否为有效的 JSON 格式
|
||||
2. 确认 `id` 字段唯一且合法（只能包含字母、数字、点号）
|
||||
3. 确认 `apiVersion` 与 SDK 版本匹配
|
||||
|
||||
### 问题 3：插件列表中不显示
|
||||
|
||||
**现象：** 安装后重启，但列表中没有
|
||||
|
||||
**排查步骤：**
|
||||
1. 确认已点击「重启」按钮
|
||||
2. 检查日志文件：`%LOCALAPPDATA%\LanMountainDesktop\logs\`
|
||||
3. 确认 `.laapp` 文件完整未损坏
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
现在你的插件已经能运行了，接下来学习：
|
||||
|
||||
👉 **[03-插件项目结构详解](03-插件项目结构详解.md)** - 深入理解每个文件的作用
|
||||
|
||||
或者直接进入实战：
|
||||
|
||||
👉 **[02-桌面组件系统](../02-核心概念与原理/02-桌面组件系统.md)** - 创建你的第一个桌面组件！
|
||||
|
||||
---
|
||||
|
||||
## 💡 小贴士
|
||||
|
||||
- **快速重建**：修改代码后，只需运行 `dotnet build` 即可重新生成 `.laapp`
|
||||
- **自动安装**：可以在 IDE 中配置构建后自动复制到宿主插件目录
|
||||
- **日志调试**：使用 `ILogger` 记录日志，在 `%LOCALAPPDATA%\LanMountainDesktop\logs\` 查看
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026年4月*
|
||||
350
docs/archive/Plugins develop/01-快速开始/03-插件项目结构详解.md
Normal file
350
docs/archive/Plugins develop/01-快速开始/03-插件项目结构详解.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# 03-插件项目结构详解
|
||||
|
||||
了解插件项目的每个文件和文件夹的作用，是开发高质量插件的基础。本文将详细解析插件项目的完整结构。
|
||||
|
||||
---
|
||||
|
||||
## 📂 项目结构概览
|
||||
|
||||
使用模板创建的插件项目结构如下：
|
||||
|
||||
```
|
||||
MyPlugin/
|
||||
├── plugin.json # 插件清单（必需）
|
||||
├── MyPlugin.csproj # 项目文件（必需）
|
||||
├── Plugin.cs # 入口类（必需）
|
||||
├── README.md # 项目说明（推荐）
|
||||
├── .gitignore # Git忽略文件（可选）
|
||||
└── Localization/ # 本地化文件夹（可选）
|
||||
├── zh-CN.json # 中文资源
|
||||
└── en-US.json # 英文资源
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 plugin.json - 插件清单
|
||||
|
||||
这是插件最重要的配置文件，定义了插件的元数据。
|
||||
|
||||
### 完整示例
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "com.example.myplugin",
|
||||
"name": "我的插件",
|
||||
"description": "这是一个示例插件",
|
||||
"author": "作者名称",
|
||||
"version": "1.0.0",
|
||||
"apiVersion": "5.0.0",
|
||||
"entranceAssembly": "MyPlugin.dll",
|
||||
"sharedContracts": [],
|
||||
"website": "https://example.com",
|
||||
"icon": "icon.png",
|
||||
"tags": ["工具", "实用"]
|
||||
}
|
||||
```
|
||||
|
||||
### 字段详解
|
||||
|
||||
| 字段 | 必需 | 说明 | 示例 |
|
||||
|-----|------|------|------|
|
||||
| `id` | ✅ | 唯一标识符，反向域名格式 | `com.yourname.plugin` |
|
||||
| `name` | ✅ | 显示名称 | `天气插件` |
|
||||
| `description` | ✅ | 简短描述 | `显示实时天气信息` |
|
||||
| `author` | ✅ | 作者名称 | `张三` |
|
||||
| `version` | ✅ | 版本号（语义化版本） | `1.0.0` |
|
||||
| `apiVersion` | ✅ | SDK API 版本 | `5.0.0` |
|
||||
| `entranceAssembly` | ✅ | 入口程序集文件名 | `MyPlugin.dll` |
|
||||
| `sharedContracts` | ✅ | 共享契约类型列表 | `[]` |
|
||||
| `website` | ❌ | 项目网站 | `https://github.com/...` |
|
||||
| `icon` | ❌ | 图标文件名 | `icon.png` |
|
||||
| `tags` | ❌ | 标签数组 | `["天气", "工具"]` |
|
||||
|
||||
### 重要规则
|
||||
|
||||
⚠️ **id 字段规则：**
|
||||
- 只能包含小写字母、数字、点号（`.`）
|
||||
- 必须全局唯一
|
||||
- 建议使用反向域名格式：`com.yourname.pluginname`
|
||||
- 一经发布不可更改
|
||||
|
||||
⚠️ **version 字段规则：**
|
||||
- 使用语义化版本格式：`主版本.次版本.修订号`
|
||||
- 示例：`1.0.0`、`2.1.3-beta`
|
||||
|
||||
⚠️ **apiVersion 字段规则：**
|
||||
- 必须与引用的 SDK 版本兼容
|
||||
- 当前最新版本：`5.0.0`
|
||||
- 不兼容时宿主将拒绝加载插件
|
||||
|
||||
---
|
||||
|
||||
## 🔧 .csproj - 项目文件
|
||||
|
||||
定义了项目的构建配置和依赖项。
|
||||
|
||||
### 完整示例
|
||||
|
||||
```xml
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<Nullable>enable</Nullable>
|
||||
<LangVersion>latest</LangVersion>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="LanMountainDesktop.PluginSdk" Version="5.0.0" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<None Update="plugin.json">
|
||||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||||
</None>
|
||||
<None Update="Localization\**\*.json">
|
||||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||||
</None>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
```
|
||||
|
||||
### 关键配置项
|
||||
|
||||
| 配置项 | 说明 | 推荐值 |
|
||||
|-------|------|--------|
|
||||
| `TargetFramework` | 目标框架 | `net10.0` |
|
||||
| `LangVersion` | C# 语言版本 | `latest` |
|
||||
| `Nullable` | 可空引用类型 | `enable` |
|
||||
|
||||
### SDK 引用
|
||||
|
||||
```xml
|
||||
<PackageReference Include="LanMountainDesktop.PluginSdk" Version="5.0.0" />
|
||||
```
|
||||
|
||||
⚠️ **版本必须匹配：**
|
||||
- SDK 版本必须与 `plugin.json` 中的 `apiVersion` 兼容
|
||||
- 建议使用最新稳定版
|
||||
|
||||
### 资源文件配置
|
||||
|
||||
确保 `plugin.json` 和本地化文件被正确复制到输出目录：
|
||||
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<None Update="plugin.json">
|
||||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||||
</None>
|
||||
<None Update="Localization\**\*.json">
|
||||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||||
</None>
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚪 Plugin.cs - 入口类
|
||||
|
||||
插件的入口点，负责初始化逻辑。
|
||||
|
||||
### 基本结构
|
||||
|
||||
```csharp
|
||||
using LanMountainDesktop.PluginSdk;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
|
||||
namespace MyPlugin;
|
||||
|
||||
[PluginEntrance]
|
||||
public sealed class Plugin : PluginBase
|
||||
{
|
||||
public override void Initialize(HostBuilderContext context, IServiceCollection services)
|
||||
{
|
||||
// 在这里注册组件、设置页面、服务等
|
||||
|
||||
// 示例：注册桌面组件
|
||||
// services.AddPluginDesktopComponent<MyWidget>(...);
|
||||
|
||||
// 示例：注册设置页面
|
||||
// services.AddPluginSettingsSection(...);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 关键特性
|
||||
|
||||
| 特性/类 | 说明 |
|
||||
|--------|------|
|
||||
| `[PluginEntrance]` | 标记插件入口类，必须有且仅有一个 |
|
||||
| `PluginBase` | 插件基类，提供基础功能和日志访问 |
|
||||
| `Initialize` | 初始化方法，宿主启动时调用 |
|
||||
|
||||
### Initialize 方法参数
|
||||
|
||||
```csharp
|
||||
public override void Initialize(HostBuilderContext context, IServiceCollection services)
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|-----|------|------|
|
||||
| `context` | `HostBuilderContext` | 宿主构建上下文，可访问配置 |
|
||||
| `services` | `IServiceCollection` | 依赖注入服务集合，用于注册组件和服务 |
|
||||
|
||||
---
|
||||
|
||||
## 🌍 Localization - 本地化文件夹
|
||||
|
||||
存放多语言资源文件，支持插件的国际化。
|
||||
|
||||
### 文件夹结构
|
||||
|
||||
```
|
||||
Localization/
|
||||
├── zh-CN.json # 简体中文
|
||||
├── zh-TW.json # 繁体中文
|
||||
├── en-US.json # 英文（美国）
|
||||
├── ja-JP.json # 日文
|
||||
└── ko-KR.json # 韩文
|
||||
```
|
||||
|
||||
### 资源文件格式
|
||||
|
||||
```json
|
||||
{
|
||||
"PluginName": "我的插件",
|
||||
"Settings": {
|
||||
"Title": "设置",
|
||||
"RefreshInterval": "刷新间隔"
|
||||
},
|
||||
"Messages": {
|
||||
"Loading": "加载中...",
|
||||
"Error": "出错了：{0}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 在代码中使用
|
||||
|
||||
```csharp
|
||||
// 获取本地化字符串
|
||||
var localizer = serviceProvider.GetRequiredService<IStringLocalizer<MyPlugin>>();
|
||||
var pluginName = localizer["PluginName"];
|
||||
var message = localizer["Messages.Error", errorDetails];
|
||||
```
|
||||
|
||||
### 支持的语言代码
|
||||
|
||||
| 语言 | 代码 |
|
||||
|-----|------|
|
||||
| 简体中文 | `zh-CN` |
|
||||
| 繁体中文 | `zh-TW` |
|
||||
| 英文 | `en-US` |
|
||||
| 日文 | `ja-JP` |
|
||||
| 韩文 | `ko-KR` |
|
||||
|
||||
---
|
||||
|
||||
## 📦 构建输出结构
|
||||
|
||||
运行 `dotnet build` 后，生成的输出结构：
|
||||
|
||||
```
|
||||
bin/Debug/net10.0/
|
||||
├── MyPlugin.dll # 插件程序集
|
||||
├── MyPlugin.pdb # 调试符号
|
||||
├── plugin.json # 插件清单（复制）
|
||||
├── Localization/ # 本地化文件夹（复制）
|
||||
│ └── zh-CN.json
|
||||
├── MyPlugin.laapp # 插件包（由 SDK 自动生成）
|
||||
└── ...（依赖项 DLL）
|
||||
```
|
||||
|
||||
### .laapp 包结构
|
||||
|
||||
`.laapp` 文件本质是一个 ZIP 压缩包，包含：
|
||||
|
||||
```
|
||||
MyPlugin.laapp
|
||||
├── plugin.json # 清单文件
|
||||
├── MyPlugin.dll # 主程序集
|
||||
├── Localization/ # 本地化资源
|
||||
└── ...（其他依赖 DLL）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 与其他 .NET 项目的区别
|
||||
|
||||
| 特性 | 普通 .NET 应用 | 阑山桌面插件 |
|
||||
|-----|---------------|-------------|
|
||||
| 入口点 | `Program.cs` 的 `Main` | `Plugin.cs` 的 `Initialize` |
|
||||
| 运行方式 | 独立运行 | 由宿主加载运行 |
|
||||
| 依赖注入 | 自行配置 | 使用宿主提供的 `IServiceCollection` |
|
||||
| 输出格式 | `.exe` 或 `.dll` | `.laapp` 包 |
|
||||
| 资源访问 | 直接访问 | 通过 SDK API 访问宿主资源 |
|
||||
| 热重载 | 支持 | 不支持（需重启宿主） |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 项目组织建议
|
||||
|
||||
```
|
||||
MyPlugin/
|
||||
├── plugin.json
|
||||
├── MyPlugin.csproj
|
||||
├── Plugin.cs # 入口类（保持简洁）
|
||||
├── README.md
|
||||
├── .gitignore
|
||||
├── Localization/ # 本地化资源
|
||||
├── Services/ # 服务类文件夹
|
||||
│ ├── WeatherService.cs
|
||||
│ └── DataService.cs
|
||||
├── Views/ # 视图文件夹
|
||||
│ ├── WeatherWidget.axaml
|
||||
│ ├── WeatherWidget.axaml.cs
|
||||
│ └── SettingsPage.axaml
|
||||
└── ViewModels/ # 视图模型文件夹
|
||||
├── WeatherViewModel.cs
|
||||
└── SettingsViewModel.cs
|
||||
```
|
||||
|
||||
### 文件命名规范
|
||||
|
||||
| 类型 | 命名约定 | 示例 |
|
||||
|-----|---------|------|
|
||||
| 入口类 | `Plugin` | `Plugin.cs` |
|
||||
| 组件视图 | `{Name}Widget` | `WeatherWidget.axaml` |
|
||||
| 设置页面 | `{Name}SettingsPage` | `WeatherSettingsPage.axaml` |
|
||||
| 服务类 | `{Name}Service` | `WeatherService.cs` |
|
||||
| 视图模型 | `{Name}ViewModel` | `WeatherViewModel.cs` |
|
||||
|
||||
---
|
||||
|
||||
## 📚 参考资源
|
||||
|
||||
- [Plugin SDK 源码](../../LanMountainDesktop.PluginSdk/)
|
||||
- [插件模板](../../LanMountainDesktop.PluginTemplate/content/)
|
||||
- [02-桌面组件系统](../02-核心概念与原理/02-桌面组件系统.md)
|
||||
- [03-设置系统集成](../02-核心概念与原理/03-设置系统集成.md)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
理解了项目结构后，接下来学习：
|
||||
|
||||
👉 **[04-调试运行指南](04-调试运行指南.md)** - 掌握调试技巧
|
||||
|
||||
或者深入了解核心概念：
|
||||
|
||||
👉 **[01-插件生命周期](../02-核心概念与原理/01-插件生命周期.md)** - 理解插件运行机制
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026年4月*
|
||||
380
docs/archive/Plugins develop/01-快速开始/04-调试运行指南.md
Normal file
380
docs/archive/Plugins develop/01-快速开始/04-调试运行指南.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# 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`：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "附加到阑山桌面",
|
||||
"type": "coreclr",
|
||||
"request": "attach",
|
||||
"processName": "LanMountainDesktop"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 方式二：独立调试
|
||||
|
||||
适用于深度调试或单元测试。
|
||||
|
||||
### 配置步骤
|
||||
|
||||
1. **修改 .csproj 临时引用宿主**
|
||||
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<!-- 临时添加，仅用于调试 -->
|
||||
<ProjectReference Include="..\LanMountainDesktop\LanMountainDesktop.csproj" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
2. **创建调试启动配置**
|
||||
|
||||
**Visual Studio：**
|
||||
- 右键项目 → `属性` → `调试`
|
||||
- 启动外部程序：选择 `LanMountainDesktop.exe`
|
||||
- 工作目录：设为宿主输出目录
|
||||
|
||||
**VS Code launch.json：**
|
||||
```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
|
||||
|
||||
```csharp
|
||||
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：**
|
||||
```powershell
|
||||
Get-Content "$env:LOCALAPPDATA\LanMountainDesktop\logs\log-$(Get-Date -Format 'yyyyMMdd').txt" -Wait
|
||||
```
|
||||
|
||||
**Linux/macOS：**
|
||||
```bash
|
||||
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`）：
|
||||
```powershell
|
||||
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. 尝试清理重建：
|
||||
```powershell
|
||||
dotnet clean
|
||||
dotnet build
|
||||
```
|
||||
|
||||
### 问题 2：插件不加载
|
||||
|
||||
**排查步骤：**
|
||||
|
||||
1. **检查日志**
|
||||
```powershell
|
||||
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` 中添加：
|
||||
```xml
|
||||
<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 和内存使用情况
|
||||
- `调试` → `窗口` → `诊断工具`
|
||||
|
||||
### 内存泄漏排查
|
||||
|
||||
```csharp
|
||||
// 在可疑位置添加诊断代码
|
||||
GC.Collect();
|
||||
GC.WaitForPendingFinalizers();
|
||||
GC.Collect();
|
||||
var memory = GC.GetTotalMemory(true);
|
||||
Debug.WriteLine($"内存使用: {memory / 1024 / 1024} MB");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
掌握了调试技巧后，接下来学习核心概念：
|
||||
|
||||
👉 **[01-插件生命周期](../02-核心概念与原理/01-插件生命周期.md)** - 理解插件运行机制
|
||||
|
||||
或者查看实战案例：
|
||||
|
||||
👉 **[01-开发天气组件](../04-实战案例/01-开发天气组件.md)** - 完整开发流程
|
||||
|
||||
---
|
||||
|
||||
## 📚 参考资源
|
||||
|
||||
- [PluginBase 源码](../../LanMountainDesktop.PluginSdk/PluginBase.cs)
|
||||
- [docs/DEVELOPMENT.md](../../docs/DEVELOPMENT.md)
|
||||
- [Visual Studio 调试文档](https://docs.microsoft.com/visualstudio/debugger/)
|
||||
- [Rider 调试文档](https://www.jetbrains.com/help/rider/Debugging.html)
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026年4月*
|
||||
Reference in New Issue
Block a user