Asgard.PluginSdk 4.1.1

Asgard.PluginSdk

Asgard.PluginSdk 是 Asgard 插件开发的便捷 API 包，帮助你更轻松地编写插件、加载插件配置、创建作用域并快速启动插件型 Web 应用。

如果你正在开发 Asgard 插件，而不想从零拼装插件约定和宿主启动流程，这个包就是推荐入口。

适用场景

• 开发 Asgard 插件或内建业务模块
• 希望统一读取 plugin.yaml 并绑定强类型配置
• 在插件内部创建依赖注入作用域执行逻辑
• 快速搭建基于插件的 Web 应用

安装

dotnet add package Asgard.PluginSdk

当前公开 API

• PluginConventions
• PluginObjectMapper
• PluginScopeExtensions
• PluginWebAppDefaults

PluginConventions

PluginConventions 用于在插件启动阶段应用默认注册约定，并从 plugin.yaml 加载强类型配置。

注册默认约定并加载配置

using Asgard.Abstractions.Plugin;
using Asgard.Abstractions.SystemConfig;
using Asgard.Core.Plugin;
using Asgard.PluginSdk;

public sealed class DemoPluginConfig : ISystemConfig
{
    public string Name { get; set; } = "demo";
}

public sealed class DemoPlugin : PluginBase
{
    public override void ConfigureServices(IPluginServiceConfigurationContext context)
    {
        DemoPluginConfig config = context.AddPluginConventions<DemoPlugin, DemoPluginConfig>();
    }
}

直接读取插件配置

using Asgard.PluginSdk;

DemoPluginConfig configFromType = PluginConventions.LoadPluginConfig<DemoPlugin, DemoPluginConfig>();
DemoPluginConfig configFromAssembly = PluginConventions.LoadPluginConfig<DemoPluginConfig>(typeof(DemoPlugin).Assembly);

PluginScopeExtensions

PluginScopeExtensions 用来从 PluginBase.ServiceProvider 创建插件内部的依赖注入作用域。

在作用域中执行逻辑

using Asgard.PluginSdk;
using Microsoft.Extensions.DependencyInjection;

await plugin.RunInScopeAsync(async services =>
{
    var handler = services.GetRequiredService<IMyHandler>();
    await handler.ExecuteAsync();
});

在作用域中返回结果

using Asgard.PluginSdk;
using Microsoft.Extensions.DependencyInjection;

string result = await plugin.RunInScopeAsync(async services =>
{
    var handler = services.GetRequiredService<IMyHandler>();
    return await handler.GetResultAsync();
});

PluginObjectMapper

PluginObjectMapper 提供了通用对象映射能力，不再要求固定继承体系。只要属性名一致且类型兼容，即可直接进行映射。

对象到对象映射

using Asgard.PluginSdk;

UserDto dto = PluginObjectMapper.Map<UserEntity, UserDto>(entity);

将请求对象应用到现有实体

using Asgard.PluginSdk;

PluginObjectMapper.MapToExisting<UpdateUserRequest, UserEntity>(request, entity);

集合映射

using Asgard.PluginSdk;

IReadOnlyList<UserVo> users = PluginObjectMapper.MapList<UserDto, UserVo>(dtoList);

PluginWebAppDefaults

PluginWebAppDefaults 提供了插件 Web 应用推荐的宿主启动和中间件默认配置。

应用推荐中间件

using Asgard.PluginSdk;

app.UseRecommendedPluginDefaults();

默认会应用：

• UseAsgardExceptionHandler()
• UseHttpsRedirection()
• 由 Yggdrasil 管理的静态资源、CORS、鉴权、授权、限流和身份上下文能力

启动插件 Web 宿主

using Asgard.PluginSdk;

await PluginWebAppDefaults.RunAsync<DemoPlugin>(
    configPath: "config/app.yaml",
    configure: app =>
    {
        // Add custom middleware or endpoint mapping here when needed.
    });

推荐搭配

• 插件运行时：Asgard.Core
• 完整宿主：Asgard.Yggdrasil.AspNetCore
• Web 运行时：Asgard.AspNetCore.Core

相关资源

• 主仓库：BenLampson/Asgard
• 插件文档：06-如何写插件.md
• Asgard Skills 仓库：BenLampson/Asgard.Skills

Asgard.Skills 仓库中包含插件结构、插件生命周期、宿主项目等配套技能定义，可以直接作为 AI 协作开发 Asgard 插件时的规范输入。