NexusLabs.Needlr.Injection 0.0.1-alpha-0008

Needlr

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.

Features

• 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

Quick Start

Basic Web Application

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

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

Advanced Configuration with Scrutor

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

var webApplication = new Syringe()
    .UsingScrutorTypeRegistrar()
    .UsingAssemblyProvider(builder => builder
        .MatchingAssemblies(x => x.Contains("MyApp"))
        .Build())
    .ForWebApplication()
    .BuildWebApplication();

await webApplication.RunAsync();

Installation

// TODO: COMING SOON Add the core package and any additional packages you need:

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


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


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


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


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

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:

• 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

var syringe = new Syringe()
    .UsingScrutorTypeRegistrar()
    .UsingDefaultTypeFilterer()
    .UsingAssemblyProvider(builder => builder
        .MatchingAssemblies(x => x.Contains("MyApp"))
        .Build());

WebApplicationSyringe

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

var webAppSyringe = new Syringe()
    .UsingScrutorTypeRegistrar()
    .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:

[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.

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

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;

var webApplication = new Syringe().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

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

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

await webApplication.RunAsync();

Requirements

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