Asgard.PluginSdk 8.1.0

dotnet add package Asgard.PluginSdk --version 8.1.0
                    
NuGet\Install-Package Asgard.PluginSdk -Version 8.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Asgard.PluginSdk" Version="8.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Asgard.PluginSdk" Version="8.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Asgard.PluginSdk" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Asgard.PluginSdk --version 8.1.0
                    
#r "nuget: Asgard.PluginSdk, 8.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Asgard.PluginSdk@8.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Asgard.PluginSdk&version=8.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Asgard.PluginSdk&version=8.1.0
                    
Install as a Cake Tool

Asgard.PluginSdk

Asgard.PluginSdk 为业务插件提供服务和仓储注册、plugin.yaml 配置绑定、作用域及对象映射。插件项目引用此包后可以使用框架控制器基类。

安装

dotnet add package Asgard.PluginSdk

当前公开 API

  • PluginConventions
  • PluginObjectMapper
  • PluginScopeExtensions

PluginConventions

PluginConventions 在服务注册阶段扫描仓储与服务,并从宿主为当前插件选定的清单加载强类型配置。重复扫描同一程序集不会重复注册相同实现。

注册默认约定并加载配置

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

public sealed class DemoPluginConfig : ISystemConfig
{
    [ConfigPath("name")]
    public string Name { get; set; } = "demo";
    public void Validate() { }
}

public sealed class DemoPlugin : PluginBase
{
    public override string Id => "demo";
    public override string Name => "Demo";
    public override Version Version => new(1, 0);

    protected override Task OnConfigureServicesAsync(IPluginServiceConfigurationContext context, CancellationToken cancellationToken)
    {
        _ = context.AddPluginConventions<DemoPlugin, DemoPluginConfig>();
        return Task.CompletedTask;
    }
}

注入和读取插件配置

服务、仓储或作业直接注入 DemoPluginConfig。此类型通过 ISystemConfig.Validate() 校验后以具体实例注册。SDK 拒绝对该类型使用 IOptions<T>、IOptionsSnapshot<T> 和 IOptionsMonitor<T>,避免容器另外生成默认实例。业务服务的改法是把 IOptions<DemoPluginConfig> options 改成 DemoPluginConfig config,直接使用 config.Name。

宿主按插件 ID 选定一份清单快照,供强类型配置和自动作业共同使用。优先 plugin.<插件 ID>.yaml;单插件目录也可使用 plugin.yaml。清单必须与部署一起交付时,注册约定传入 requireManifest: true。

已装配插件通过 plugin.LoadPluginConfig<DemoPluginConfig>() 读取同一份快照。脱离宿主的工具显式指定文件:

using Asgard.Core.SystemConfig;

var config = YamlConfigLoader.LoadPluginConfigFromFile<DemoPluginConfig>(manifestPath);

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);

启动插件

从 8.0.0 起,在可执行的 Starter 中添加 Asgard.Yggdrasil.AspNetCore 包引用。PluginWebAppDefaults 由该包提供,原有调用方式可以继续使用。

using Asgard.PluginSdk;

await PluginWebAppDefaults.RunAsync<DemoPlugin>("config/app.yaml");

推荐搭配

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

相关资源

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

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
8.1.0 0 11/19/2026
8.0.0 8 11/19/2026
7.2.0 68 11/17/2026
7.1.0 68 11/17/2026
7.0.0 72 11/13/2026
6.1.0 113 11/6/2026
6.0.4 128 10/24/2026
6.0.3 136 10/11/2026
6.0.2 116 10/8/2026
6.0.1 99 10/8/2026
6.0.0 108 10/1/2026
5.3.0 155 10/1/2026
5.2.3 107 10/1/2026
5.2.2 124 9/1/2026
5.2.1 121 8/26/2026
5.2.0 181 8/6/2026
5.1.5 123 8/4/2026
5.1.4 135 8/3/2026
5.1.3 128 7/26/2026
5.1.2 162 7/20/2026
Loading failed