Asgard.PluginSdk 7.2.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Asgard.PluginSdk --version 7.2.0
                    
NuGet\Install-Package Asgard.PluginSdk -Version 7.2.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="7.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Asgard.PluginSdk" Version="7.2.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 7.2.0
                    
#r "nuget: Asgard.PluginSdk, 7.2.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@7.2.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=7.2.0
                    
Install as a Cake Addin
#tool nuget:?package=Asgard.PluginSdk&version=7.2.0
                    
Install as a Cake Tool

Asgard.PluginSdk

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

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

适用场景

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

安装

dotnet add package Asgard.PluginSdk

当前公开 API

  • PluginConventions
  • PluginObjectMapper
  • PluginScopeExtensions
  • PluginWebAppDefaults

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

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

相关资源

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