mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-08-18 15:33:33 +08:00
345 lines
9.1 KiB
Markdown
345 lines
9.1 KiB
Markdown
# 轻应用开发 - 环境准备
|
||
|
||
## 前置要求
|
||
|
||
在开始开发轻应用之前，请确保你已经：
|
||
|
||
- ✅ 安装了 .NET 10 SDK
|
||
- ✅ 安装了支持 C# 的 IDE（Visual Studio 2022 / Rider / VS Code）
|
||
- ✅ 了解 C# 基础语法
|
||
- ✅ 了解 Avalonia UI 基础（或 WPF，两者相似）
|
||
|
||
> 如果还没有配置开发环境，请先阅读 [开发环境配置](../../00-快速开始/03-开发环境配置.md)
|
||
|
||
## 安装轻应用模板
|
||
|
||
### 安装官方模板
|
||
|
||
阑山桌面提供了官方的轻应用项目模板，可以快速创建轻应用项目骨架。
|
||
|
||
```powershell
|
||
# 安装轻应用模板包
|
||
dotnet new install LanMountainDesktop.AirAppTemplate
|
||
|
||
# 验证安装成功
|
||
dotnet new list | Select-String "lmd"
|
||
```
|
||
|
||
你应该看到类似输出：
|
||
|
||
```
|
||
lmd-airapp LanMountainDesktop AirApp C# LanMountainDesktop/AirApp
|
||
```
|
||
|
||
### 模板版本管理
|
||
|
||
```powershell
|
||
# 查看已安装的模板
|
||
dotnet new list lmd
|
||
|
||
# 更新到最新版本
|
||
dotnet new install LanMountainDesktop.AirAppTemplate --force
|
||
|
||
# 卸载模板
|
||
dotnet new uninstall LanMountainDesktop.AirAppTemplate
|
||
```
|
||
|
||
## 创建第一个轻应用项目
|
||
|
||
### 使用模板创建项目
|
||
|
||
```powershell
|
||
# 创建新轻应用项目
|
||
dotnet new lmd-airapp -n MyFirstAirApp
|
||
|
||
# 进入项目目录
|
||
cd MyFirstAirApp
|
||
```
|
||
|
||
### 项目结构
|
||
|
||
创建后的项目结构如下：
|
||
|
||
```
|
||
MyFirstAirApp/
|
||
├── MyFirstAirApp.csproj # 项目文件
|
||
├── AirApp.cs # 轻应用入口类
|
||
├── airapp.json # 轻应用清单
|
||
├── Components/ # 组件目录
|
||
│ └── SampleComponent.cs # 示例组件
|
||
├── Views/ # 视图目录
|
||
│ └── SampleComponentView.axaml # 组件视图
|
||
│ └── SampleComponentView.axaml.cs # 视图代码后台
|
||
├── ViewModels/ # 视图模型
|
||
│ └── SampleComponentViewModel.cs # 组件视图模型
|
||
├── Settings/ # 设置页目录
|
||
│ └── AirAppSettingsPage.axaml # 设置页视图
|
||
│ └── AirAppSettingsPage.axaml.cs # 设置页代码
|
||
├── Assets/ # 资源目录
|
||
│ └── icon.png # 轻应用图标
|
||
└── Localization/ # 本地化目录
|
||
└── Strings.resx # 字符串资源
|
||
```
|
||
|
||
## 理解轻应用清单
|
||
|
||
### airapp.json 文件
|
||
|
||
`airapp.json` 是轻应用的元数据文件，定义了轻应用的基本信息。
|
||
|
||
```json
|
||
{
|
||
"Id": "com.example.myfirstplugin",
|
||
"Name": "My First AirApp",
|
||
"Version": "1.0.0",
|
||
"Author": "Your Name",
|
||
"Description": "My first LanMountainDesktop plugin",
|
||
"MinHostVersion": "1.0.0",
|
||
"SdkVersion": "5.0.0",
|
||
"Dependencies": [],
|
||
"Permissions": [
|
||
"Network.Access"
|
||
],
|
||
"Icon": "Assets/icon.png",
|
||
"Homepage": "https://github.com/yourusername/myfirstplugin",
|
||
"Repository": "https://github.com/yourusername/myfirstplugin.git"
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `Id` | ✅ | 轻应用唯一标识符，建议使用反向域名格式 |
|
||
| `Name` | ✅ | 轻应用显示名称 |
|
||
| `Version` | ✅ | 轻应用版本号，遵循语义化版本 |
|
||
| `Author` | ✅ | 轻应用作者 |
|
||
| `Description` | ✅ | 轻应用简介 |
|
||
| `MinHostVersion` | ✅ | 最低宿主版本要求 |
|
||
| `SdkVersion` | ✅ | 使用的 SDK 版本 |
|
||
| `Dependencies` | ❌ | 依赖的其他轻应用 ID 列表 |
|
||
| `Permissions` | ❌ | 轻应用所需权限列表 |
|
||
| `Icon` | ❌ | 轻应用图标路径 |
|
||
| `Homepage` | ❌ | 轻应用主页 URL |
|
||
| `Repository` | ❌ | 源码仓库 URL |
|
||
|
||
### 版本号规范
|
||
|
||
轻应用版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/)：
|
||
|
||
```
|
||
主版本号.次版本号.修订号
|
||
|
||
例如: 1.2.3
|
||
```
|
||
|
||
- **主版本号**: 不兼容的 API 修改
|
||
- **次版本号**: 向下兼容的功能性新增
|
||
- **修订号**: 向下兼容的问题修正
|
||
|
||
## 理解项目文件
|
||
|
||
### MyFirstAirApp.csproj
|
||
|
||
```xml
|
||
<Project Sdk="Microsoft.NET.Sdk">
|
||
<PropertyGroup>
|
||
<TargetFramework>net10.0</TargetFramework>
|
||
<Nullable>enable</Nullable>
|
||
<ImplicitUsings>enable</ImplicitUsings>
|
||
|
||
<!-- 轻应用元数据 -->
|
||
<AirAppId>com.example.myfirstplugin</AirAppId>
|
||
<AirAppName>My First AirApp</AirAppName>
|
||
<AirAppVersion>1.0.0</AirAppVersion>
|
||
|
||
<!-- 禁用可执行文件生成，轻应用是类库 -->
|
||
<OutputType>Library</OutputType>
|
||
</PropertyGroup>
|
||
|
||
<ItemGroup>
|
||
<!-- AirApp SDK（v6 起包含共享契约依赖 LanMountainDesktop.Core） -->
|
||
<PackageReference Include="LanMountainDesktop.AirAppSdk" Version="6.0.0" />
|
||
|
||
<!-- Avalonia UI -->
|
||
<PackageReference Include="Avalonia" Version="12.0.1" />
|
||
<PackageReference Include="Avalonia.Themes.Fluent" Version="12.0.1" />
|
||
|
||
<!-- MVVM Toolkit -->
|
||
<PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.2" />
|
||
</ItemGroup>
|
||
|
||
<!-- 复制 airapp.json 到输出目录 -->
|
||
<ItemGroup>
|
||
<None Update="airapp.json">
|
||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||
</None>
|
||
<None Update="Assets\**">
|
||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||
</None>
|
||
</ItemGroup>
|
||
|
||
<!-- Avalonia 编译支持 -->
|
||
<ItemGroup>
|
||
<AvaloniaResource Include="**\*.axaml" />
|
||
</ItemGroup>
|
||
</Project>
|
||
```
|
||
|
||
### 关键配置项
|
||
|
||
- **TargetFramework**: 必须是 `net10.0`
|
||
- **OutputType**: 必须是 `Library`（轻应用是类库，不是可执行文件）
|
||
- **Nullable**: 建议启用，提高代码质量
|
||
- **AirAppId/AirAppName/AirAppVersion**: 应与 `airapp.json` 保持一致
|
||
|
||
## 构建轻应用
|
||
|
||
### 还原依赖
|
||
|
||
```powershell
|
||
dotnet restore
|
||
```
|
||
|
||
### 构建项目
|
||
|
||
```powershell
|
||
# Debug 模式
|
||
dotnet build
|
||
|
||
# Release 模式
|
||
dotnet build -c Release
|
||
```
|
||
|
||
### 查看输出
|
||
|
||
构建成功后，输出目录结构：
|
||
|
||
```
|
||
bin/Debug/net10.0/
|
||
├── MyFirstAirApp.dll # 主程序集
|
||
├── MyFirstAirApp.pdb # 调试符号
|
||
├── airapp.json # 轻应用清单
|
||
├── Assets/ # 资源文件
|
||
│ └── icon.png
|
||
└── *.dll # 依赖程序集
|
||
```
|
||
|
||
## 调试轻应用
|
||
|
||
### 方法一：复制到轻应用目录（推荐）
|
||
|
||
```powershell
|
||
# 构建轻应用
|
||
dotnet build
|
||
|
||
# 复制到宿主的轻应用目录
|
||
$pluginDir = "$env:LOCALAPPDATA\LanMountainDesktop\plugins\MyFirstAirApp"
|
||
New-Item -ItemType Directory -Path $pluginDir -Force
|
||
Copy-Item -Path "bin\Debug\net10.0\*" -Destination $pluginDir -Recurse -Force
|
||
|
||
# 启动宿主应用
|
||
# （确保宿主在 Debug 模式下构建，这样可以附加调试器）
|
||
```
|
||
|
||
### 方法二：使用符号链接
|
||
|
||
在开发模式下，可以创建符号链接避免每次复制：
|
||
|
||
```powershell
|
||
# 创建符号链接（需要管理员权限）
|
||
$pluginDir = "$env:LOCALAPPDATA\LanMountainDesktop\plugins\MyFirstAirApp"
|
||
$buildDir = "$(pwd)\bin\Debug\net10.0"
|
||
|
||
New-Item -ItemType SymbolicLink -Path $pluginDir -Target $buildDir -Force
|
||
```
|
||
|
||
### 方法三：配置宿主调试路径
|
||
|
||
如果你有宿主源码，可以修改宿主的轻应用搜索路径指向你的轻应用构建目录。
|
||
|
||
在宿主项目的 `appsettings.Development.json` 中：
|
||
|
||
```json
|
||
{
|
||
"AirAppPaths": [
|
||
"C:\\Dev\\MyFirstAirApp\\bin\\Debug\\net10.0"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 附加调试器
|
||
|
||
1. 启动宿主应用（LanMountainDesktop）
|
||
2. 在 Visual Studio 中，选择"调试" → "附加到进程"
|
||
3. 找到 `LanMountainDesktop.exe` 进程
|
||
4. 点击"附加"
|
||
5. 在轻应用代码中设置断点
|
||
|
||
## 查看日志
|
||
|
||
### 日志位置
|
||
|
||
```
|
||
%LOCALAPPDATA%\LanMountainDesktop\logs\latest.log
|
||
```
|
||
|
||
### 实时查看日志
|
||
|
||
```powershell
|
||
# PowerShell
|
||
Get-Content "$env:LOCALAPPDATA\LanMountainDesktop\logs\latest.log" -Wait -Tail 50
|
||
```
|
||
|
||
### 日志级别
|
||
|
||
- **Trace**: 最详细的信息，用于诊断
|
||
- **Debug**: 调试信息
|
||
- **Information**: 一般信息
|
||
- **Warning**: 警告信息
|
||
- **Error**: 错误信息
|
||
- **Critical**: 严重错误
|
||
|
||
## 常见问题
|
||
|
||
### 轻应用没有被加载
|
||
|
||
**检查清单**:
|
||
1. 确认 `airapp.json` 存在且格式正确
|
||
2. 确认轻应用 DLL 文件存在
|
||
3. 查看日志文件中的错误信息
|
||
4. 确认轻应用 ID 唯一，没有与其他轻应用冲突
|
||
5. 确认 SDK 版本匹配
|
||
|
||
### 编译错误：找不到类型
|
||
|
||
**问题**: `error CS0246: The type or namespace name 'IAirApp' could not be found`
|
||
|
||
**解决方案**:
|
||
```powershell
|
||
# 确认引用了 AirAppSdk
|
||
dotnet add package LanMountainDesktop.AirAppSdk --version 6.0.0
|
||
|
||
# 清理并重新构建
|
||
dotnet clean
|
||
dotnet build
|
||
```
|
||
|
||
### Avalonia 视图无法编译
|
||
|
||
**问题**: AXAML 文件编译错误
|
||
|
||
**解决方案**:
|
||
1. 确认安装了 Avalonia NuGet 包
|
||
2. 检查 AXAML 语法是否正确
|
||
3. 确认 `AvaloniaResource` 项已配置在 csproj 中
|
||
4. 清理并重新构建项目
|
||
|
||
## 下一步
|
||
|
||
现在你已经完成了环境准备，可以继续：
|
||
|
||
- [创建第一个轻应用](02-创建第一个轻应用.md) - 实现轻应用功能
|
||
- [轻应用生命周期](../02-核心概念/01-轻应用生命周期.md) - 理解轻应用运行机制
|
||
- [组件系统](../02-核心概念/02-组件系统.md) - 创建桌面组件
|