needlr

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.

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.

AI and agentic runtime, evaluation, and provider integrations are developed in Foundry, including Foundry's optional Needlr integration packages.

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

📚 Documentation

Getting Started Guide → - New to Needlr? Start here for a step-by-step introduction.

Additional documentation:

• Solution-Wide Source Generation - Set up NexusLabs.Needlr.Build for multi-project solutions
• Local CI Runners - Route trusted Linux jobs through PitCrew
• Core Concepts - Understand the architecture and design
• Hosted Services - Auto-discovery of BackgroundService and IHostedService
• Keyed Services - Multiple implementations with different keys
• Service Catalog - Query your DI registrations at runtime
• Plugin Development - Create custom plugins to extend functionality
• Advanced Usage - 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:

<!-- Core dependency injection (abstractions only) -->
<PackageReference Include="NexusLabs.Needlr.Injection" />

<!-- CHOOSE ONE: Source Generation (recommended for AOT) -->
<PackageReference Include="NexusLabs.Needlr.Injection.SourceGen" />
<PackageReference Include="NexusLabs.Needlr.Build" PrivateAssets="all" />

<!-- CHOOSE ONE: Reflection (for dynamic scenarios) -->
<PackageReference Include="NexusLabs.Needlr.Injection.Reflection" />

<!-- CHOOSE ONE: Bundle (includes both with auto-fallback) -->
<PackageReference Include="NexusLabs.Needlr.Injection.Bundle" />