LanMountainDesktop/docs/AIRAPP_SDK_V1_MIGRATION.md

AirApp SDK V1 迁移指南

从旧的插件系统（LanMountainDesktop.PluginSdk / plugin.json / API 5.0.0）迁移到统一的 AirApp 扩展系统（LanMountainDesktop.AirAppSdk / airapp.json / API 1.0.0）。

概览

AirApp 取代插件成为阑山桌面的统一扩展系统。旧插件不再被加载；请按本指南迁移。

项目	旧（插件系统）	新（AirApp）
SDK 包	LanMountainDesktop.PluginSdk	LanMountainDesktop.AirAppSdk
API 版本	5.0.0	1.0.0
清单文件	plugin.json	airapp.json
命名空间	LanMountainDesktop.PluginSdk	LanMountainDesktop.AirAppSdk
模板	dotnet new lmd-plugin	dotnet new lmd-airapp

关键 API 映射

旧	新
[PluginEntrance] / IPlugin	[AirAppEntrance] / IAirApp
PluginBase	AirAppBase
PluginManifest	AirAppManifest
IPluginRuntimeContext	IAirAppRuntimeContext
IPluginWorker / PluginWorkerBase	IAirAppWorker / AirAppWorkerBase
IPluginAppearanceContext / PluginAppearanceSnapshot	IAirAppAppearanceContext / AirAppAppearanceSnapshot
IPluginSettingsService	IAirAppSettingsService
PluginSettingsSectionBuilder	AirAppSettingsSectionBuilder
AddPluginDesktopComponent	AddAirAppComponent
AddPluginDesktopComponentEditor	AddAirAppComponentEditor
AddPluginSettingsSection	AddAirAppSettingsSection
AddPluginExport	AddAirAppExport
AddPluginPublicIpc	AddAirAppPublicIpc
IPluginMessageBus	IAirAppMessageBus
IPluginPackageManager	IAirAppPackageManager
PluginSdkInfo	AirAppSdkInfo

完整类型映射见代码库 airapp/LanMountainDesktop.AirAppSdk/ 中的实际类型。

生命周期变化

IAirApp 在 Initialize 之外新增两个生命周期方法：

[AirAppEntrance]
public sealed class MyAirApp : AirAppBase
{
    public override void Initialize(HostBuilderContext context, IServiceCollection services)
    {
        // 注册组件 / 窗口 / 设置
        services.AddAirAppComponent<MyComponent>(new AirAppComponentOptions
        {
            ComponentId = "my-component",
            DisplayName = "My Component"
        });
        services.AddAirAppWindow<MyWindow>("my-window", "My Window");
    }

    public override Task OnStartedAsync(IAirAppRuntimeContext context)
    {
        // 宿主启动完成后回调
        return Task.CompletedTask;
    }

    public override Task OnStoppingAsync()
    {
        // 宿主停止前回调
        return Task.CompletedTask;
    }
}

plugin.json → airapp.json

// 旧 plugin.json
{
  "id": "com.example.myapp",
  "name": "My App",
  "apiVersion": "5.0.0",
  "entranceAssembly": "MyApp.dll",
  "runtime": { "mode": "in-proc" }
}

// 新 airapp.json
{
  "id": "com.example.myapp",
  "name": "My App",
  "apiVersion": "1.0.0",
  "entranceAssembly": "MyApp.dll",
  "runtime": { "mode": "in-process" },
  "components": [
    { "id": "my-component", "name": "My Component", "defaultWidth": 2, "defaultHeight": 2 }
  ],
  "windows": [
    { "id": "my-window", "name": "My Window" }
  ]
}

迁移步骤

1. 把 plugin.json 重命名为 airapp.json，字段按上表更新（runtime.mode 用 in-process，apiVersion 用 1.0.0，补充 components / windows 声明）。
2. 把 csproj 的 PackageReference 从 LanMountainDesktop.PluginSdk 改为 LanMountainDesktop.AirAppSdk（Version 1.0.0）。
3. 全局替换命名空间与类型名（见 API 映射表）。
4. 在 Initialize 中改用 AddAirAppComponent / AddAirAppWindow / AddAirAppSettingsSection。
5. 把 IPlugin.Initialize 拆分为 Initialize + OnStartedAsync + OnStoppingAsync（如需要）。
6. 用 dotnet new lmd-airapp 生成新工程作参考，或直接升级现有工程。