LanMountainDesktop/docs/01-AirApp开发/01-快速开始/01-环境准备.md

轻应用开发 - 环境准备

前置要求

在开始开发轻应用之前，请确保你已经：

• ✅ 安装了 .NET 10 SDK
• ✅ 安装了支持 C# 的 IDE（Visual Studio 2022 / Rider / VS Code）
• ✅ 了解 C# 基础语法
• ✅ 了解 Avalonia UI 基础（或 WPF，两者相似）

如果还没有配置开发环境，请先阅读 开发环境配置

安装轻应用模板

安装官方模板

阑山桌面提供了官方的轻应用项目模板，可以快速创建轻应用项目骨架。

# 安装轻应用模板包
dotnet new install LanMountainDesktop.AirAppTemplate

# 验证安装成功
dotnet new list | Select-String "lmd"

你应该看到类似输出：

lmd-airapp    LanMountainDesktop AirApp    C#    LanMountainDesktop/AirApp

模板版本管理

# 查看已安装的模板
dotnet new list lmd

# 更新到最新版本
dotnet new install LanMountainDesktop.AirAppTemplate --force

# 卸载模板
dotnet new uninstall LanMountainDesktop.AirAppTemplate

创建第一个轻应用项目

使用模板创建项目

# 创建新轻应用项目
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 是轻应用的元数据文件，定义了轻应用的基本信息。

{
  "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：

主版本号.次版本号.修订号

例如: 1.2.3

• 主版本号: 不兼容的 API 修改
• 次版本号: 向下兼容的功能性新增
• 修订号: 向下兼容的问题修正

理解项目文件

MyFirstAirApp.csproj

<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 保持一致

构建轻应用

还原依赖

dotnet restore

构建项目

# Debug 模式
dotnet build

# Release 模式
dotnet build -c Release

查看输出

构建成功后，输出目录结构：

bin/Debug/net10.0/
├── MyFirstAirApp.dll                   # 主程序集
├── MyFirstAirApp.pdb                   # 调试符号
├── airapp.json                         # 轻应用清单
├── Assets/                             # 资源文件
│   └── icon.png
└── *.dll                               # 依赖程序集

调试轻应用

方法一：复制到轻应用目录（推荐）

# 构建轻应用
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 模式下构建，这样可以附加调试器）

方法二：使用符号链接

在开发模式下，可以创建符号链接避免每次复制：

# 创建符号链接（需要管理员权限）
$pluginDir = "$env:LOCALAPPDATA\LanMountainDesktop\plugins\MyFirstAirApp"
$buildDir = "$(pwd)\bin\Debug\net10.0"

New-Item -ItemType SymbolicLink -Path $pluginDir -Target $buildDir -Force

方法三：配置宿主调试路径

如果你有宿主源码，可以修改宿主的轻应用搜索路径指向你的轻应用构建目录。

在宿主项目的 appsettings.Development.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
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

解决方案:

# 确认引用了 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. 清理并重新构建项目

下一步

现在你已经完成了环境准备，可以继续：

• 创建第一个轻应用 - 实现轻应用功能
• 轻应用生命周期 - 理解轻应用运行机制
• 组件系统 - 创建桌面组件