Asgard.Yggdrasil.AspNetCore 4.0.0-preview.7

Asgard.Yggdrasil.AspNetCore

Asgard.Yggdrasil.AspNetCore is the ASP.NET Core host package for Asgard.

For application teams, this is the package to install when they want to:

• build their own web host
• keep control over Program.cs
• use Asgard infrastructure and lifecycle hooks
• treat their own business module as a built-in plugin

Runtime directory scanning is still supported, but it is now an optional extension path for drop-in plugins, hot-plug scenarios, and deployment-time customization. It is not the primary integration model for normal application teams.

Install

dotnet add package Asgard.Yggdrasil.AspNetCore

Recommended Model

The recommended integration model is:

1. Create your own ASP.NET Core app.
2. Reference Asgard.Yggdrasil.AspNetCore.
3. Start the host with YggdrasilHost.
4. Put your business module into one or more built-in plugins.

That keeps the application in control while still letting Asgard manage service registration, plugin lifecycle, middleware composition, and infrastructure capabilities.

Quick Start

Program.cs

using Asgard.Yggdrasil.AspNetCore;
using Asgard.Abstractions.AspNetCore.Extensions;
using Microsoft.AspNetCore.Builder;

var builder = YggdrasilHost.CreateBuilder("config/app.yaml")
    .UseBuiltInPlugin<MyBusinessPlugin>()
    .ConfigureMiddleware(app =>
    {
        app.UseAsgardExceptionHandler()
           .UseHttpsRedirection();
    })
    .AfterHostBuild(_ =>
    {
        Console.WriteLine("[OK] Asgard Yggdrasil host started");
    });

var app = builder.Build();
await app.RunAsync();

If YggdrasilHost is not visible in your project, first make sure both of these are true:

1. The project references Asgard.Yggdrasil.AspNetCore
2. Program.cs includes using Asgard.Yggdrasil.AspNetCore;

Minimal package install command:

dotnet add package Asgard.Yggdrasil.AspNetCore

Built-in Plugin

using Asgard.Core.Plugin;
using Asgard.Abstractions.Plugin;

public sealed class MyBusinessPlugin : PluginBase
{
    public override string Id => "member-center";

    public override string Name => "Member Center";

    public override Version Version => new(1, 0, 0);

    protected override Task OnConfigureServicesAsync(
        IPluginServiceConfigurationContext context,
        CancellationToken cancellationToken)
    {
        context.Services.AddScoped<IMemberService, MemberService>();
        return Task.CompletedTask;
    }

    protected override Task OnConfigureMiddlewareAsync(
        IPluginMiddlewareConfigurationContext context,
        CancellationToken cancellationToken)
    {
        context.App.MapControllers();
        return Task.CompletedTask;
    }
}

Built-in Plugin APIs

Use one of these host builder APIs depending on how explicit you want startup to be:

• UseBuiltInPlugin<TPlugin>()
• UseBuiltInPluginsFromAssembly(Assembly assembly)
• UseEntryAssemblyPlugins()

UseBuiltInPlugin<TPlugin>() is the most explicit and recommended option for normal applications.

Configuration

The current host API still expects a configuration file path, typically:

config/app.yaml

A minimal setup usually includes:

host:
  application:
    name: "MyApp"
    version: "1.0.0"
    environment: "Development"
  kestrel:
    endpoints:
      http:
        url: "http://127.0.0.1:5000"
  staticFiles:
    enabled: true
    webRootPath: "wwwroot"
    requestPath: ""
  auth:
    enabled: false
    jwt:
      secretKey: "12345678901234567890123456789012"
      issuer: "Asgard"
      audience: "Asgard.Users"
  healthCheck:
    enabled: true
  rateLimiting:
    enabled: false

Asgard:
  Encryption:
    Key: "your-base64-key"
    Iv: "your-base64-iv"

logging:
  minimumLevel: Debug
  console:
    enabled: true
  file:
    enabled: false

caching:
  enabled: false

database:
  enabled: false

messaging:
  enabled: false

job:
  enabled: false
  jobs: []

plugin:
  enabled: false

Only the host.* tree is used for host-level settings. Do not place host settings under top-level Application or Kestrel nodes, because the current host builder does not read those paths.

When you register built-in plugins in code, the host will enable the plugin system automatically for that application instance.

Static Files

Static files are configured through host.staticFiles.

host:
  staticFiles:
    enabled: true
    webRootPath: "wwwroot"
    requestPath: "/assets"

Behavior:

• enabled: true enables static file hosting
• webRootPath can be relative or absolute
• relative paths are resolved from the application content root
• requestPath: "" serves files from the site root
• requestPath: "/assets" serves files from /assets/*

When you configure middleware manually, keep custom middleware focused on business concerns. Static files, CORS, authentication, authorization, rate limiting, and health endpoints are managed by the host from host.*.

Optional Runtime Plugin Discovery

Filesystem-based plugin discovery is still available when you need external plugins:

plugin:
  enabled: true
  scanDirectories:
    - path: "plugins"
      enabled: true
      recursive: false
      entryPointPattern: "*.Plugin.dll"

Use this mode for:

• deployment-time drop-in extensions
• hot-plug operational scenarios
• private plugin marketplaces
• tenant- or environment-specific external modules

Do not use it as the default integration path for an application that already references your packages directly.

Package Guidance

• Application host: install Asgard.Yggdrasil.AspNetCore
• Reusable runtime plugin implementation: depend on Asgard.Core
• Contracts-only integration: depend on Asgard.Abstractions or Asgard.Abstractions.AspNetCore

Related Packages

• Asgard.Yggdrasil.AspNetCore
• Asgard.AspNetCore.Core
• Asgard.Core
• Asgard.Abstractions
• Asgard.Abstractions.AspNetCore