Netloji.PluginService.Abstractions 1.0.0-preview.2

Netloji.PluginService

A .NET plugin system with isolated AssemblyLoadContext, hot-reload, and first-class DI integration. Bir .NET eklenti sistemi — izole AssemblyLoadContext, sıcak yükleme ve birinci sınıf DI desteği.

🇬🇧 English

Overview

Netloji.PluginService is a modular, production-ready plugin framework for .NET 10+ (with netstandard2.1 support for abstractions). It provides:

• Isolated loading — each plugin runs in its own AssemblyLoadContext with dependency resolution
• Hot-reload — watch plugin directories and load/unload without restarting the host
• DI-first — plugins integrate with IServiceProvider, ILogger, IConfiguration, HttpClient
• Event bus — built-in publish/subscribe for inter-plugin communication
• REST API — optional ASP.NET Core hosting with management endpoints
• Integrity checks — SHA-256 hashing for plugin assemblies
• Packaging — .netpkg binary format for distribution
• Collectible contexts — unload plugins fully when no longer needed (.NET 10+)

Packages

Package	NuGet	Description
Netloji.PluginService.Abstractions		Interfaces (IPlugin, IPluginContext), attributes (PluginAttribute), base classes (PluginBase) and models
Netloji.PluginService		Runtime: PluginManager, PluginRegistry, PluginLoadContext, watcher, packaging, hasher
Netloji.PluginService.Hosting		ASP.NET Core hosting: PluginHostedService, REST API endpoints, DI extensions

Quick Start

1. Install

dotnet add package Netloji.PluginService
dotnet add package Netloji.PluginService.Hosting   # optional, for ASP.NET Core

2. Register in your host

// Program.cs
builder.Services.AddNetlojiPlugins(builder.Configuration, opts =>
{
    opts.PluginDirectory = "Plugins";
    opts.PluginFilePattern = "MyCompany.Plugins.*.dll";
    opts.WatchForChanges = true;          // hot-reload enabled
    opts.EnableUnload = true;             // collectible ALC
    opts.HttpClientTimeout = TimeSpan.FromSeconds(60);
});

// Optional: map the REST API
app.MapNetlojiPluginApi("/api/plugins");

3. Create a plugin

Create a new class library project:

dotnet new classlib -o MyCompany.Plugins.Greeter

using Netloji.PluginService.Abstractions;
using Microsoft.Extensions.Logging;

[Plugin("mycompany.greeter", "1.0.0", "Greeter Plugin",
    Description = "A friendly greeting plugin",
    Author = "You",
    Tags = new[] { "example", "greeter" },
    Capabilities = new[] { PluginCapability.Source })]
public class GreeterPlugin : PluginBase
{
    public override PluginMetadata Metadata { get; }

    public override async Task OnLoadedAsync(IPluginContext ctx, CancellationToken ct)
    {
        ctx.Log(LogLevel.Information, "GreeterPlugin loaded!");

        var client = ctx.Http;
        var config = ctx.GetSection("Greeter");
        var greeting = config["Message"] ?? "Hello from plugin!";

        ctx.Log(LogLevel.Information, greeting);
    }

    public override Task OnUnloadedAsync(CancellationToken ct)
    {
        Context?.Log(LogLevel.Information, "Goodbye from plugin!");
        return Task.CompletedTask;
    }
}

4. Build and run

dotnet build -c Release
# Copy the plugin DLL to your host's Plugins/ directory
# The host loads it automatically on startup (or via hot-reload)

Plugin Lifecycle

Discovery → LoadAssembly → Create PluginLoadContext
    → Scan for [Plugin] types → Instantiate via DI
    → Call OnLoadedAsync(context) → Register in PluginRegistry
    → [Runtime] → Call OnUnloadedAsync() → Unload ALC

REST API (Hosting package)

Project Structure

Netloji.PluginService/
├── src/
│   ├── Netloji.PluginService.Abstractions/   # Contracts & models
│   ├── Netloji.PluginService/                 # Runtime engine
│   └── Netloji.PluginService.Hosting/         # ASP.NET Core hosting
├── tests/
│   ├── Abstractions.Tests/
│   ├── Tests/
│   └── IntegrationTests/
├── samples/
│   ├── Hello.Plugin/
│   ├── DataSource.Plugin/
│   └── Composite.Host/
└── docs/

Requirements

• .NET 10 SDK or later
• ASP.NET Core 10.0+ (for Hosting package)

🇹🇷 Türkçe

Genel Bakış

Netloji.PluginService, .NET 10+ için geliştirilmiş, üretime hazır bir eklenti (plugin) altyapısıdır. Temel özellikler:

• İzole yükleme — her eklenti kendi AssemblyLoadContext'inde bağımlılıklarıyla birlikte çalışır
• Sıcak yükleme — uygulamayı durdurmadan eklenti yükleme/kaldırma, dosya değişikliklerini izleme
• DI desteği — IServiceProvider, ILogger, IConfiguration, HttpClient ile tam uyum
• Olay iletisi — eklentiler arası publish/subscribe mekanizması
• REST API — ASP.NET Core ile isteğe bağlı yönetim endpoint'leri
• Bütünlük denetimi — SHA-256 ile eklenti bütünlük sağlama
• Paketleme — .netpkg binary formatı ile dağıtım
• Toplanabilir context — eklentiler tamamen bellekten atılabilir (.NET 10+)

Paketler

Paket	NuGet	Açıklama
Netloji.PluginService.Abstractions		Arayüzler (IPlugin, IPluginContext), nitelikler (PluginAttribute), temel sınıflar (PluginBase) ve modeller
Netloji.PluginService		Çalışma zamanı: PluginManager, PluginRegistry, PluginLoadContext, dosya izleyici, paketleme
Netloji.PluginService.Hosting		ASP.NET Core hosting: PluginHostedService, REST API endpoint'leri, DI eklentileri

Hızlı Başlangıç

1. Paketleri ekleyin

dotnet add package Netloji.PluginService
dotnet add package Netloji.PluginService.Hosting   # ASP.NET Core için isteğe bağlı

2. Host'a kaydedin

// Program.cs
builder.Services.AddNetlojiPlugins(builder.Configuration, opts =>
{
    opts.PluginDirectory = "Plugins";
    opts.PluginFilePattern = "MyCompany.Plugins.*.dll";
    opts.WatchForChanges = true;
    opts.EnableUnload = true;
    opts.HttpClientTimeout = TimeSpan.FromSeconds(60);
});

// REST API'yi aktif edin
app.MapNetlojiPluginApi("/api/plugins");

3. Bir eklenti yazın

[Plugin("mycompany.greeter", "1.0.0", "Greeter Plugin",
    Description = "Örnek bir eklenti",
    Author = "Adınız",
    Tags = new[] { "ornek", "greeter" },
    Capabilities = new[] { PluginCapability.Source })]
public class GreeterPlugin : PluginBase
{
    public override PluginMetadata Metadata { get; }

    public override async Task OnLoadedAsync(IPluginContext ctx, CancellationToken ct)
    {
        ctx.Log(LogLevel.Information, "GreeterPlugin yüklendi!");
        var greeting = ctx.GetSection("Greeter")["Message"] ?? "Merhaba!";
        ctx.Log(LogLevel.Information, greeting);
    }

    public override Task OnUnloadedAsync(CancellationToken ct)
    {
        Context?.Log(LogLevel.Information, "Eklenti kaldırılıyor...");
        return Task.CompletedTask;
    }
}

4. Derleyin ve çalıştırın

dotnet build -c Release
# Çıkan DLL'i host uygulamasının Plugins/ klasörüne kopyalayın
# Host, eklentiyi başlangıçta veya sıcak yükleme ile otomatik alır

Eklenti Yaşam Döngüsü

Keşif → Assembly Yükle → PluginLoadContext oluştur
    → [Plugin] tiplerini tara → DI ile örnekle
    → OnLoadedAsync(context) çağır → PluginRegistry'e kaydet
    → [Çalışma Zamanı] → OnUnloadedAsync() çağır → ALC'yi kaldır

REST API (Hosting paketi)

Gereksinimler

• .NET 10 SDK veya üzeri
• ASP.NET Core 10.0+ (Hosting paketi için)

License / Lisans

This project is licensed under the MIT License. See LICENSE for details. Bu proje MIT lisansı ile lisanslanmıştır. Detaylar için LICENSE dosyasına bakın.