LanMountainDesktop/docs/01-插件开发/03-API参考/02-IPluginContext.md

# IPluginContext 详解

`IPluginContext` 是插件与宿主应用交互的主要接口，提供对宿主服务、日志、设置等的访问。

## 接口定义

```csharp
namespace LanMountainDesktop.PluginSdk;

/// <summary>
/// 插件上下文接口
/// </summary>
public interface IPluginContext
{
    /// <summary>
    /// 插件根目录
    /// 包含插件的所有文件（DLL、资源等）
    /// </summary>
    string PluginDirectory { get; }
    
    /// <summary>
    /// 插件数据目录
    /// 用于存储插件的持久化数据（缓存、数据库等）
    /// </summary>
    string DataDirectory { get; }
    
    /// <summary>
    /// 服务提供者
    /// 用于获取宿主提供的服务
    /// </summary>
    IServiceProvider Services { get; }
    
    /// <summary>
    /// 日志记录器
    /// 用于记录插件运行日志
    /// </summary>
    ILogger Logger { get; }
    
    /// <summary>
    /// 设置服务
    /// 用于读写插件配置
    /// </summary>
    ISettingsService Settings { get; }
}
```

## 属性详解

### PluginDirectory

**类型**: `string`

**说明**: 插件的根目录，包含插件的所有文件。

**典型路径**:
```
%LOCALAPPDATA%\LanMountainDesktop\plugins\{PluginId}\
```

**用途**:
- 加载插件资源文件
- 读取配置文件
- 访问插件自带的数据文件

**示例**:

```csharp
public async Task InitializeAsync(IPluginContext context)
{
    // 加载插件自带的数据文件
    var dataFile = Path.Combine(context.PluginDirectory, "data", "cities.json");
    if (File.Exists(dataFile))
    {
        var json = await File.ReadAllTextAsync(dataFile);
        var cities = JsonSerializer.Deserialize<List<City>>(json);
    }
    
    // 加载图标
    var iconPath = Path.Combine(context.PluginDirectory, "Assets", "icon.png");
    
    // 加载资源文件（使用 avares 方案更好）
    // avares://MyPlugin/Assets/icon.png
}
```

**注意事项**:
- ✅ 只能读取，不要在此目录写入文件
- ✅ 使用 `Path.Combine` 构建路径
- ❌ 不要硬编码路径
- ❌ 不要依赖目录结构（可能变化）

### DataDirectory

**类型**: `string`

**说明**: 插件的数据目录，用于存储插件生成的持久化数据。

**典型路径**:
```
%LOCALAPPDATA%\LanMountainDesktop\plugin-data\{PluginId}\
```

**用途**:
- 存储缓存文件
- 存储本地数据库
- 存储临时文件
- 存储下载的文件

**示例**:

```csharp
public async Task InitializeAsync(IPluginContext context)
{
    // 确保数据目录存在
    Directory.CreateDirectory(context.DataDirectory);
    
    // 缓存文件路径
    var cacheFile = Path.Combine(context.DataDirectory, "weather-cache.json");
    
    // SQLite 数据库路径
    var dbPath = Path.Combine(context.DataDirectory, "todos.db");
    
    // 下载文件路径
    var downloadPath = Path.Combine(context.DataDirectory, "downloads");
}
```

**最佳实践**:

```csharp
public class MyPlugin : IPlugin
{
    private string? _cacheDirectory;
    private string? _logsDirectory;
    
    public async Task InitializeAsync(IPluginContext context)
    {
        // 创建子目录组织数据
        _cacheDirectory = Path.Combine(context.DataDirectory, "cache");
        _logsDirectory = Path.Combine(context.DataDirectory, "logs");
        
        Directory.CreateDirectory(_cacheDirectory);
        Directory.CreateDirectory(_logsDirectory);
    }
    
    public async Task SaveCacheAsync(string key, string data)
    {
        var cacheFile = Path.Combine(_cacheDirectory!, $"{key}.json");
        await File.WriteAllTextAsync(cacheFile, data);
    }
}
```

**清理数据**:

```csharp
public async Task ShutdownAsync()
{
    // 清理旧的缓存文件
    if (_cacheDirectory != null)
    {
        var files = Directory.GetFiles(_cacheDirectory);
        foreach (var file in files)
        {
            var fileInfo = new FileInfo(file);
            if (DateTime.Now - fileInfo.LastWriteTime > TimeSpan.FromDays(7))
            {
                File.Delete(file);
            }
        }
    }
}
```

### Services

**类型**: `IServiceProvider`

**说明**: 服务提供者，用于获取宿主提供的服务。

**常用服务**:

| 服务接口 | 说明 |
|---------|------|
| `IComponentRegistry` | 组件注册表 |
| `ISettingsPageRegistry` | 设置页注册表 |
| `IEventBus` | 事件总线 |
| `INotificationService` | 通知服务 |
| `IDialogService` | 对话框服务 |
| `IThemeService` | 主题服务 |
| `ILocalizationService` | 本地化服务 |
| `IHttpClientFactory` | HTTP 客户端工厂 |

**使用方法**:

```csharp
public async Task InitializeAsync(IPluginContext context)
{
    // 获取服务
    var componentRegistry = context.Services
        .GetService<IComponentRegistry>();
    
    var eventBus = context.Services
        .GetService<IEventBus>();
    
    var themeService = context.Services
        .GetService<IThemeService>();
    
    // 检查服务是否可用
    if (componentRegistry != null)
    {
        // 使用服务
        componentRegistry.RegisterComponent<MyComponent>();
    }
    else
    {
        context.Logger.LogWarning("IComponentRegistry not available");
    }
}
```

**泛型扩展方法**:

```csharp
// 使用 Microsoft.Extensions.DependencyInjection 的扩展方法
using Microsoft.Extensions.DependencyInjection;

var componentRegistry = context.Services.GetService<IComponentRegistry>();
var eventBus = context.Services.GetRequiredService<IEventBus>(); // 不存在会抛异常
```

**服务定位器模式**:

```csharp
public class MyPlugin : IPlugin
{
    private IServiceProvider? _services;
    
    public async Task InitializeAsync(IPluginContext context)
    {
        _services = context.Services;
    }
    
    private void SomeMethod()
    {
        // 运行时获取服务
        var notificationService = _services?
            .GetService<INotificationService>();
        
        notificationService?.ShowNotification(
            "标题",
            "内容",
            NotificationType.Information
        );
    }
}
```

### Logger

**类型**: `ILogger`

**说明**: 日志记录器，用于记录插件运行日志。

**日志级别**:

| 级别 | 方法 | 用途 |
|-----|------|------|
| Trace | `LogTrace` | 最详细的信息，用于诊断 |
| Debug | `LogDebug` | 调试信息 |
| Information | `LogInformation` | 一般信息 |
| Warning | `LogWarning` | 警告信息 |
| Error | `LogError` | 错误信息 |
| Critical | `LogCritical` | 严重错误 |

**基本用法**:

```csharp
public async Task InitializeAsync(IPluginContext context)
{
    var logger = context.Logger;
    
    // 信息日志
    logger.LogInformation("Plugin is initializing");
    
    // 警告日志
    logger.LogWarning("Configuration is missing, using defaults");
    
    // 错误日志
    try
    {
        await LoadDataAsync();
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Failed to load data");
    }
    
    // 调试日志
    logger.LogDebug("Loaded {Count} items", items.Count);
}
```

**结构化日志**:

```csharp
// ✅ 好：使用参数化日志
logger.LogInformation(
    "User {UserId} requested weather for {City}",
    userId,
    city
);

// ❌ 差：字符串拼接
logger.LogInformation(
    $"User {userId} requested weather for {city}"
);
```

**异常日志**:

```csharp
try
{
    await FetchWeatherAsync();
}
catch (HttpRequestException ex)
{
    // 记录异常和上下文
    logger.LogError(
        ex,
        "Failed to fetch weather for {City}. Retry count: {RetryCount}",
        city,
        retryCount
    );
}
catch (Exception ex)
{
    // 严重错误
    logger.LogCritical(
        ex,
        "Unexpected error in weather service"
    );
}
```

**条件日志**:

```csharp
// 检查日志级别以避免不必要的计算
if (logger.IsEnabled(LogLevel.Debug))
{
    var expensiveDebugInfo = CalculateDebugInfo(); // 只在启用 Debug 时计算
    logger.LogDebug("Debug info: {Info}", expensiveDebugInfo);
}
```

**日志作用域**:

```csharp
using (logger.BeginScope("WeatherFetch-{City}", city))
{
    logger.LogInformation("Starting fetch");
    await FetchWeatherAsync(city);
    logger.LogInformation("Fetch completed");
}
// 所有日志会包含作用域信息
```

### Settings

**类型**: `ISettingsService`

**说明**: 设置服务，用于读写插件配置。详见 [设置系统](../02-核心概念/03-设置系统.md)。

**快速示例**:

```csharp
public async Task InitializeAsync(IPluginContext context)
{
    var settings = context.Settings;
    
    // 读取设置
    var apiKey = settings.GetValue("ApiKey", "");
    var refreshRate = settings.GetValue("RefreshRate", 10);
    var cities = settings.GetValue<List<string>>(
        "FavoriteCities",
        new List<string>()
    );
    
    // 保存设置
    settings.SetValue("LastStartTime", DateTime.Now);
    
    // 监听设置变更
    settings.SettingChanged += (sender, e) =>
    {
        if (e.Key == "ApiKey")
        {
            // 响应变更
        }
    };
}
```

## 使用模式

### 保存上下文引用

```csharp
public class MyPlugin : IPlugin
{
    private IPluginContext? _context;
    private ILogger? _logger;
    private ISettingsService? _settings;
    
    public async Task InitializeAsync(IPluginContext context)
    {
        // 保存引用供后续使用
        _context = context;
        _logger = context.Logger;
        _settings = context.Settings;
        
        // 后续可以在任何方法中使用
    }
    
    private void SomeMethod()
    {
        _logger?.LogInformation("Doing something");
        
        var value = _settings?.GetValue("Key", "Default");
    }
}
```

### 依赖注入模式

```csharp
public class MyComponent : ComponentBase
{
    private readonly INotificationService? _notificationService;
    
    public MyComponent()
    {
        // 组件构造时注入依赖
        _notificationService = Services.GetService<INotificationService>();
    }
    
    public void NotifyUser(string message)
    {
        _notificationService?.ShowNotification(
            "提醒",
            message,
            NotificationType.Information
        );
    }
}
```

### 服务包装

```csharp
public class MyPlugin : IPlugin
{
    private WeatherService? _weatherService;
    
    public async Task InitializeAsync(IPluginContext context)
    {
        // 创建服务包装类
        _weatherService = new WeatherService(
            context.Logger,
            context.Settings,
            context.Services.GetService<IHttpClientFactory>()
        );
        
        await _weatherService.InitializeAsync();
    }
}

public class WeatherService
{
    private readonly ILogger _logger;
    private readonly ISettingsService _settings;
    private readonly HttpClient _httpClient;
    
    public WeatherService(
        ILogger logger,
        ISettingsService settings,
        IHttpClientFactory? httpFactory)
    {
        _logger = logger;
        _settings = settings;
        _httpClient = httpFactory?.CreateClient() ?? new HttpClient();
    }
    
    public async Task InitializeAsync()
    {
        var apiKey = _settings.GetValue("ApiKey", "");
        _logger.LogInformation("Weather service initialized");
    }
}
```

## 最佳实践

### ✅ 检查服务可用性

```csharp
// ✅ 好：检查服务是否存在
var notificationService = context.Services
    .GetService<INotificationService>();

if (notificationService != null)
{
    notificationService.ShowNotification(...);
}
else
{
    context.Logger.LogWarning("Notification service not available");
}

// ❌ 差：不检查直接使用
var notificationService = context.Services
    .GetRequiredService<INotificationService>(); // 可能抛异常
```

### ✅ 使用结构化日志

```csharp
// ✅ 好：参数化日志
logger.LogInformation(
    "Processed {Count} items in {Duration}ms",
    count,
    duration
);

// ❌ 差：字符串插值
logger.LogInformation(
    $"Processed {count} items in {duration}ms"
);
```

### ✅ 正确处理路径

```csharp
// ✅ 好：使用 Path.Combine
var dataFile = Path.Combine(
    context.DataDirectory,
    "cache",
    "data.json"
);

// ❌ 差：字符串拼接
var dataFile = context.DataDirectory + "\\cache\\data.json"; // Windows 专用
```

### ✅ 清理资源

```csharp
public class MyPlugin : IPlugin
{
    private ISettingsService? _settings;
    
    public async Task InitializeAsync(IPluginContext context)
    {
        _settings = context.Settings;
        _settings.SettingChanged += OnSettingChanged;
    }
    
    public async Task ShutdownAsync()
    {
        // 取消订阅
        if (_settings != null)
        {
            _settings.SettingChanged -= OnSettingChanged;
        }
    }
}
```

## 完整示例

```csharp
using LanMountainDesktop.PluginSdk;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

namespace MyPlugin;

public class WeatherPlugin : IPlugin
{
    public string Id => "com.example.weatherplugin";
    public string Name => "天气插件";
    public string Version => "1.0.0";
    
    // 上下文引用
    private IPluginContext? _context;
    private ILogger? _logger;
    private ISettingsService? _settings;
    private string? _dataDirectory;
    
    // 服务引用
    private INotificationService? _notificationService;
    private IHttpClientFactory? _httpFactory;
    
    public async Task InitializeAsync(IPluginContext context)
    {
        // 1. 保存上下文引用
        _context = context;
        _logger = context.Logger;
        _settings = context.Settings;
        _dataDirectory = context.DataDirectory;
        
        _logger.LogInformation(
            "{PluginName} v{Version} initializing from {Directory}",
            Name,
            Version,
            context.PluginDirectory
        );
        
        // 2. 获取宿主服务
        _notificationService = context.Services
            .GetService<INotificationService>();
        
        _httpFactory = context.Services
            .GetService<IHttpClientFactory>();
        
        // 3. 创建数据目录
        Directory.CreateDirectory(_dataDirectory);
        
        var cacheDir = Path.Combine(_dataDirectory, "cache");
        Directory.CreateDirectory(cacheDir);
        
        _logger.LogDebug("Data directory: {Directory}", _dataDirectory);
        
        // 4. 加载配置
        var apiKey = _settings.GetValue("ApiKey", "");
        if (string.IsNullOrEmpty(apiKey))
        {
            _logger.LogWarning("API Key not configured");
        }
        
        // 5. 注册组件和服务
        RegisterComponents(context);
        RegisterSettingsPage(context);
        
        // 6. 订阅事件
        SubscribeEvents(context);
        
        _logger.LogInformation("{PluginName} initialized successfully", Name);
    }
    
    private void RegisterComponents(IPluginContext context)
    {
        var registry = context.Services.GetService<IComponentRegistry>();
        if (registry != null)
        {
            registry.RegisterComponent<WeatherComponent>();
            _logger?.LogDebug("Components registered");
        }
    }
    
    private void RegisterSettingsPage(IPluginContext context)
    {
        var settingsRegistry = context.Services
            .GetService<ISettingsPageRegistry>();
        
        if (settingsRegistry != null)
        {
            settingsRegistry.RegisterPage(
                title: Name,
                category: "插件",
                pageFactory: () => new WeatherSettingsPage(
                    _settings!,
                    _logger!
                )
            );
            _logger?.LogDebug("Settings page registered");
        }
    }
    
    private void SubscribeEvents(IPluginContext context)
    {
        var eventBus = context.Services.GetService<IEventBus>();
        if (eventBus != null)
        {
            eventBus.Subscribe<ThemeChangedEvent>(OnThemeChanged);
            _logger?.LogDebug("Event subscriptions created");
        }
    }
    
    private void OnThemeChanged(ThemeChangedEvent evt)
    {
        _logger?.LogInformation("Theme changed to: {Theme}", evt.NewTheme);
    }
    
    public async Task ShutdownAsync()
    {
        _logger?.LogInformation("{PluginName} shutting down", Name);
        
        // 取消订阅
        var eventBus = _context?.Services.GetService<IEventBus>();
        if (eventBus != null)
        {
            eventBus.Unsubscribe<ThemeChangedEvent>(OnThemeChanged);
        }
        
        _logger?.LogInformation("{PluginName} shutdown completed", Name);
        await Task.CompletedTask;
    }
}
```

## 相关文档

- [IPlugin 接口](01-IPlugin接口.md) - 插件接口详解
- [设置系统](../02-核心概念/03-设置系统.md) - 设置服务详解
- [插件生命周期](../02-核心概念/01-插件生命周期.md) - 生命周期详解