NexusLabs.Needlr.Serilog 0.0.2-alpha-0064

Needlr

👁 CI
👁 Coverage
👁 NuGet

Needlr is an opinionated fluent dependency injection library for .NET that provides automatic service registration and web application setup through a simple, discoverable API. It's designed to minimize boilerplate code by defaulting to registering types from scanned assemblies automatically.

Needlr is source-generation-first: The default approach uses compile-time source generation for AOT compatibility and optimal performance. Reflection-based discovery is available as an explicit opt-in for dynamic scenarios.

Features

• Source Generation First: Compile-time type discovery for AOT/trimming compatibility
• Reflection as Opt-In: Dynamic type discovery available when needed
• Automatic Service Discovery: Automatically registers services from assemblies using conventions
• Fluent API: Chain-able configuration methods for clean, readable setup
• ASP.NET Core Integration: Seamless web application creation and configuration
• Plugin System: Extensible architecture for modular applications
• Multiple Type Registrars: Built-in support for default registration and Scrutor-based scanning
• Flexible Filtering: Control which types get registered automatically
• Decorator Pattern Support: Automatic decorator wiring with [DecoratorFor<T>] attribute, plus manual AddDecorator extension
• Post-Build Plugins: Execute configuration after the main service collection has been built
• Configuration Integration: Automatic IConfiguration registration and support
• Assembly Provider: Flexible assembly scanning with filtering and sorting options
• AI Integrations: First-class support for Semantic Kernel and Microsoft Agent Framework

📚 Documentation

- New to Needlr? Start here for a step-by-step introduction.

Additional documentation:

• - Set up NexusLabs.Needlr.Build for multi-project solutions
• - Understand the architecture and design
• - Auto-discovery of BackgroundService and IHostedService
• - Multiple implementations with different keys
• - Query your DI registrations at runtime
• - Create custom plugins to extend functionality
• - Complex scenarios and optimization techniques

Quick Start

Source Generation (Recommended)

For AOT-compatible applications with compile-time type discovery:

using NexusLabs.Needlr.AspNet;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.SourceGen;

var webApplication = new Syringe()
 .UsingSourceGen()
 .ForWebApplication()
 .BuildWebApplication();

await webApplication.RunAsync();

Reflection-Based (Dynamic Scenarios)

For applications that need runtime type discovery:

using NexusLabs.Needlr.AspNet;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.Reflection;

var webApplication = new Syringe()
 .UsingReflection()
 .ForWebApplication()
 .BuildWebApplication();

await webApplication.RunAsync();

Auto-Configuration (Bundle)

For convenience with automatic fallback from source-gen to reflection:

using NexusLabs.Needlr.AspNet;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.Bundle;

var webApplication = new Syringe()
 .UsingAutoConfiguration()
 .ForWebApplication()
 .BuildWebApplication();

await webApplication.RunAsync();

Installation

Add the core package and choose your discovery strategy:

<PackageReference Include="NexusLabs.Needlr.Injection" />


<PackageReference Include="NexusLabs.Needlr.Injection.SourceGen" />
<PackageReference Include="NexusLabs.Needlr.Build" PrivateAssets="all" />


<PackageReference Include="NexusLabs.Needlr.Injection.Reflection" />


<PackageReference Include="NexusLabs.Needlr.Injection.Bundle" />


<PackageReference Include="NexusLabs.Needlr.AspNet" />


<PackageReference Include="NexusLabs.Needlr.Injection.Scrutor" />


<PackageReference Include="NexusLabs.Needlr.Carter" />


<PackageReference Include="NexusLabs.Needlr.SignalR" />


<PackageReference Include="NexusLabs.Needlr.SemanticKernel" />


<PackageReference Include="NexusLabs.Needlr.AgentFramework" />

Core Concepts

Syringe

The Syringe class is the main entry point for configuring dependency injection in Needlr. It provides a fluent API for setting up:

• Discovery Strategy: Source generation (.UsingSourceGen()) or reflection (.UsingReflection())
• Type Registrars: How services are registered (default or Scrutor-based)
• Type Filterers: Which types should be registered automatically
• Assembly Providers: Which assemblies to scan for services

// Source generation approach (recommended)
var syringe = new Syringe()
 .UsingSourceGen()
 .UsingAssemblyProvider(builder => builder
 .MatchingAssemblies(x => x.Contains("MyApp"))
 .Build());

// Reflection approach (dynamic scenarios)
var syringe = new Syringe()
 .UsingReflection()
 .UsingScrutorTypeRegistrar()
 .UsingAssemblyProvider(builder => builder
 .MatchingAssemblies(x => x.Contains("MyApp"))
 .Build());

WebApplicationSyringe

For web applications, use ForWebApplication() to transition to web-specific configuration:

var webApp = new Syringe()
 .UsingSourceGen()
 .ForWebApplication()
 .UsingOptions(() => CreateWebApplicationOptions.Default)
 .BuildWebApplication();

Service Registration

Automatic Registration

Services are automatically registered based on conventions. By default, Needlr will:

• Register classes as both themselves and their interfaces
• Use appropriate lifetimes (Transient/Singleton based on type filtering)
• Skip types marked with [DoNotAutoRegister]

Preventing Auto-Registration

Use the [DoNotAutoRegister] attribute to exclude types from automatic registration. This is typically done when you need manual control over service registration:

[DoNotAutoRegister]
public class ManuallyRegisteredService
{
 // This won't be automatically registered
}

Custom Services

By default, a custom class you create (public or internal) will get picked up automatically and be available on the dependency container:

internal class WeatherProvider
{
 private readonly IConfiguration _config;
 
 public WeatherProvider(IConfiguration config)
 {
 _config = config;
 }
 
 public WeatherData GetWeather()
 {
 // Implementation
 }
}

The above class would be available for use in minimal APIs and can be injected into other types resolved from the dependency container.

Manual Service Registration

While Needlr automatically registers services by convention, you may need to manually register services for more complex scenarios like decorator patterns, conditional registration, or when you need precise control over service lifetimes and configurations.

Preventing Auto-Registration

Use the [DoNotAutoRegister] attribute to exclude types from automatic registration:

using NexusLabs.Needlr;

[DoNotAutoRegister]
public sealed class MyService : IMyService
{
 public void DoSomething()
 {
 Console.WriteLine("Hello, from Dev Leader!");
 }
}

Manual Registration with IServiceCollectionPlugin

Create a plugin that implements IServiceCollectionPlugin to manually configure services:

using Microsoft.Extensions.DependencyInjection;
using NexusLabs.Needlr;

internal sealed class MyPlugin : IServiceCollectionPlugin
{
 public void Configure(ServiceCollectionPluginOptions options)
 {
 // Register service manually as singleton
 options.Services.AddSingleton<IMyService, MyService>();
 }
}

Decorator Pattern Example

Here's a complete example showing manual registration with a decorator pattern:

using Microsoft.Extensions.DependencyInjection;
using NexusLabs.Needlr;
using NexusLabs.Needlr.Injection;

// Interface
public interface IMyService
{
 void DoSomething();
}

// Base service implementation
[DoNotAutoRegister]
public sealed class MyService : IMyService
{
 public void DoSomething()
 {
 Console.WriteLine("Hello, from Dev Leader!");
 }
}

// Decorator that adds additional behavior
[DoNotAutoRegister]
public sealed class MyDecorator(IMyService wrapped) : IMyService
{
 public void DoSomething()
 {
 Console.WriteLine("---BEFORE---");
 wrapped.DoSomething();
 Console.WriteLine("---AFTER---");
 }
}

// Plugin for manual registration
internal sealed class MyPlugin : IServiceCollectionPlugin
{
 public void Configure(ServiceCollectionPluginOptions options)
 {
 options.Services.AddSingleton<MyService>();
 options.Services.AddSingleton<IMyService, MyDecorator>(s => 
 new MyDecorator(s.GetRequiredService<MyService>()));
 }
}

// Usage (with source generation)
var serviceProvider = new Syringe()
 .UsingSourceGen()
 .BuildServiceProvider();
serviceProvider.GetRequiredService<IMyService>().DoSomething();
// Output:
// ---BEFORE---
// Hello, from Dev Leader!
// ---AFTER---

The IServiceCollectionPlugin is automatically discovered and registered by Needlr, so you don't need to manually register the plugin itself.

Manual Registration with Scrutor Decoration

When using Scrutor type registrar, you can leverage Scrutor's decoration extensions for cleaner decorator pattern implementation:

using Microsoft.Extensions.DependencyInjection;
using NexusLabs.Needlr;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.Scrutor;

// Interface and service implementations (same as above example)
// ...

// Plugin using Scrutor decoration extensions
internal sealed class MyScrutorPlugin : IServiceCollectionPlugin
{
 public void Configure(ServiceCollectionPluginOptions options)
 {
 // Register the base service first
 options.Services.AddSingleton<IMyService, MyService>();
 
 // Use Scrutor to decorate the service
 options.Services.Decorate<IMyService, MyDecorator>();
 }
}

// Usage with Scrutor type registrar (requires reflection)
var serviceProvider = new Syringe()
 .UsingReflection()
 .UsingScrutorTypeRegistrar()
 .BuildServiceProvider();

serviceProvider.GetRequiredService<IMyService>().DoSomething();
// Output:
// ---BEFORE---
// Hello, from Dev Leader!
// ---AFTER---

This approach is cleaner than manual decorator registration as Scrutor handles the complex dependency injection logic internally.

Using AddDecorator Extension

Needlr provides a convenient AddDecorator extension method that simplifies decorator registration:

using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.SourceGen;

var serviceProvider = new Syringe()
 .UsingSourceGen()
 .UsingPostPluginRegistrationCallback(services =>
 {
 // Register the base service
 services.AddSingleton<IMyService, MyService>();
 })
 .AddDecorator<IMyService, MyDecorator>()
 .BuildServiceProvider();

serviceProvider.GetRequiredService<IMyService>().DoSomething();
// Output:
// ---BEFORE---
// Hello, from Dev Leader!
// ---AFTER---

The AddDecorator extension automatically wraps the existing service registration with the decorator, preserving the original service's lifetime.

Automatic Decorators with [DecoratorFor<T>] (Recommended)

The simplest way to implement decorators is using the [DecoratorFor<TService>] attribute. Needlr automatically discovers and wires up decorators at startup:

using NexusLabs.Needlr;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.SourceGen;

public interface IMyService
{
 string GetValue();
}

public class MyService : IMyService
{
 public string GetValue() => "Original";
}

// Decorator applied first (closest to original service)
[DecoratorFor<IMyService>(Order = 1)]
public class LoggingDecorator : IMyService
{
 private readonly IMyService _inner;
 
 public LoggingDecorator(IMyService inner) => _inner = inner;
 
 public string GetValue()
 {
 Console.WriteLine("Calling GetValue...");
 return _inner.GetValue();
 }
}

// Decorator applied second (wraps the logging decorator)
[DecoratorFor<IMyService>(Order = 2)]
public class CachingDecorator : IMyService
{
 private readonly IMyService _inner;
 private string? _cached;
 
 public CachingDecorator(IMyService inner) => _inner = inner;
 
 public string GetValue() => _cached ??= _inner.GetValue();
}

// Usage - decorators are automatically discovered and applied
var serviceProvider = new Syringe()
 .UsingSourceGen() // or .UsingReflection()
 .BuildServiceProvider();

var result = serviceProvider.GetRequiredService<IMyService>().GetValue();
// Output: "Calling GetValue..."
// result = "Original"
// Chain: CachingDecorator → LoggingDecorator → MyService

Key points:

• Lower Order values are applied first (closer to the original service)
• Higher Order values wrap outer layers
• No plugin or manual registration needed
• Works with both source generation and reflection
• A class can decorate multiple services using multiple [DecoratorFor<T>] attributes

Plugin System

Needlr supports a plugin architecture for modular applications:

Web Application Plugins

internal sealed class WeatherPlugin : IWebApplicationPlugin
{
 public void Configure(WebApplicationPluginOptions options)
 {
 options.WebApplication.MapGet("/weather", (WeatherProvider weatherProvider) =>
 {
 return Results.Ok(weatherProvider.GetWeather());
 });
 }
}

Web Application Builder Plugins

public sealed class CarterWebApplicationBuilderPlugin : IWebApplicationBuilderPlugin
{
 public void Configure(WebApplicationBuilderPluginOptions options)
 {
 options.Logger.LogInformation("Configuring Carter services...");
 options.Builder.Services.AddCarter();
 }
}

Examples

Minimal Web API (Source Generation)

The following example has a custom type automatically registered and a minimal API that will consume it:

using NexusLabs.Needlr.AspNet;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.SourceGen;

var webApplication = new Syringe()
 .UsingSourceGen()
 .ForWebApplication()
 .BuildWebApplication();
await webApplication.RunAsync();

internal sealed class WeatherPlugin : IWebApplicationPlugin
{
 public void Configure(WebApplicationPluginOptions options)
 {
 options.WebApplication.MapGet("/weather", (WeatherProvider weatherProvider) =>
 {
 return Results.Ok(weatherProvider.GetWeather());
 });
 }
}

internal sealed class WeatherProvider(IConfiguration config)
{
 public object GetWeather()
 {
 var weatherConfig = config.GetSection("Weather");
 return new
 {
 TemperatureC = weatherConfig.GetValue<double>("TemperatureCelsius"),
 Summary = weatherConfig.GetValue<string>("Summary"),
 };
 }
}

Fluent Configuration (Reflection with Scrutor)

using NexusLabs.Needlr.AspNet;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.Reflection;
using NexusLabs.Needlr.Injection.Scrutor;

var webApplication = new Syringe()
 .UsingReflection()
 .UsingScrutorTypeRegistrar()
 .UsingAssemblyProvider(builder => builder
 .MatchingAssemblies(x =>
 x.Contains("NexusLabs", StringComparison.OrdinalIgnoreCase) ||
 x.Contains("MyApp", StringComparison.OrdinalIgnoreCase))
 .UseLibTestEntryOrdering()
 .Build())
 .UsingAdditionalAssemblies(additionalAssemblies: [])
 .ForWebApplication()
 .UsingOptions(() => CreateWebApplicationOptions
 .Default
 .UsingStartupConsoleLogger())
 .BuildWebApplication();

await webApplication.RunAsync();

Source Generation vs Reflection

Use Source Generation when:

• Building AOT-compiled applications
• Targeting trimmed/self-contained deployments
• You want faster startup times
• All plugins are known at compile time

Use Reflection when:

• Loading plugins dynamically at runtime
• Scanning assemblies not known at compile time
• Using Scrutor for advanced registration patterns

AI Integrations

Needlr provides first-class integrations for AI agent frameworks, handling function discovery, DI wiring, and factory lifecycle — so you focus on writing agent functions, not plumbing.

Both integrations follow a two-layer model:

• Layer 1 — Discovery (Needlr): identifying which types contain annotated methods. Source gen handles this at compile time (AOT-safe); reflection handles it at runtime (dev convenience, not AOT-safe).
• Layer 2 — Instantiation (upstream framework): building JSON schemas and wiring tools into agents/kernels. Both Microsoft.Extensions.AI and Microsoft.SemanticKernel use reflection here regardless of which Needlr path you choose — this is an upstream framework ceiling, not a Needlr limitation.

See the for a full explanation of the two-layer model, source gen setup, and the design direction for future multi-agent support.

Microsoft Agent Framework

Microsoft Agent Framework (built on Microsoft.Extensions.AI) is Microsoft's multi-agent orchestration framework. Needlr's NexusLabs.Needlr.AgentFramework integration auto-discovers methods marked with [AgentFunction] and wires them as AIFunction tools on any IChatClient.

using NexusLabs.Needlr.AgentFramework;
using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.Reflection;

// Mark methods as agent tools
internal sealed class WeatherTools
{
 [AgentFunction]
 [Description("Gets the current temperature for a city.")]
 public string GetTemperature(string city) => $"22°C in {city}";
}

// Wire everything up via Needlr
var agentFactory = new Syringe()
 .UsingReflection()
 .UsingAgentFramework(af => af
 .UsingChatClient(sp => sp.GetRequiredService<IChatClient>())
 .AddAgentFunctionsFromAssemblies())
 .BuildServiceProvider(configuration)
 .GetRequiredService<IAgentFactory>();

// Create a scoped agent — optionally restrict which function types it has access to
var agent = agentFactory.CreateAgent(opts =>
{
 opts.Instructions = "You are a helpful weather assistant.";
 opts.FunctionTypes = [typeof(WeatherTools)];
});

// Run with multi-turn session state
var session = await agent.CreateSessionAsync();
var response = await agent.RunAsync("What is the temperature in Tokyo?", session);
Console.WriteLine(response.Text);

Key features:

• [AgentFunction] attribute marks methods for discovery (static or instance)
• IAgentFactory is registered as a singleton — create as many agents as needed
• AgentFactoryOptions.FunctionTypes scopes tools per-agent from a shared pool
• Source generator (NexusLabs.Needlr.AgentFramework.Generators) enables compile-time discovery (Layer 1 AOT-safe)

Semantic Kernel

Needlr's NexusLabs.Needlr.SemanticKernel integration auto-discovers [KernelFunction]-attributed plugin classes and wires them into a Kernel via IKernelFactory.

using NexusLabs.Needlr.Injection;
using NexusLabs.Needlr.Injection.Reflection;
using NexusLabs.Needlr.SemanticKernel;

var kernelFactory = new Syringe()
 .UsingReflection()
 .UsingSemanticKernel(sk => sk
 .Configure(opts => opts.KernelBuilderFactory = sp =>
 Kernel.CreateBuilder()
 .AddAzureOpenAIChatCompletion(deploymentName, endpoint, apiKey))
 .AddKernelPluginsFromAssemblies())
 .BuildServiceProvider(configuration)
 .GetRequiredService<IKernelFactory>();

var kernel = kernelFactory.CreateKernel();
var result = await kernel.InvokePromptAsync("What is the weather today?");

Requirements

• .NET 10 or later
• C# 13.0 or later