The Discovery Strategy Decision
When you configure a dependency injection container to scan and register your types automatically, the first decision you face is how that scanning actually happens. Does it run at compile time, baking the registration logic directly into your assembly? Or does it happen at runtime, inspecting types through reflection as the application starts? Source generation vs reflection in Needlr represents two fundamentally different answers to this question, and understanding the tradeoffs is essential for choosing the right one for your project.
Needlr is an opinionated fluent DI library for .NET that provides both strategies behind a consistent API. You call .UsingSourceGen() for compile-time discovery, .UsingReflection() for runtime discovery, or .UsingAutoConfiguration() to let the library pick for you. The fluent surface is identical regardless of which strategy you choose, so the decision is really about deployment constraints, performance requirements, and whether your application needs to load types that are not known until runtime. If you are new to the broader concept of letting a container manage object creation for you, the primer on what is inversion of control covers the foundational ideas.
This article walks through both strategies in detail, compares their behavior under AOT publishing and trimming, and shows you when each one is the better choice. We will also look at the auto-configuration bundle that bridges the two and discuss concrete scenarios where the distinction matters.
How Source Generation Works in Needlr
Source generation in .NET uses Roslyn analyzers that run during compilation. Rather than inspecting types at runtime, a source generator reads the syntax trees and semantic models of your project at build time and emits additional C# code that gets compiled alongside your own. Needlr's source generation package uses this mechanism to discover every type in your scanned assemblies and produce explicit registration calls against IServiceCollection.
The practical consequence is that when your application starts, there is no scanning step at all. The registration code already exists as compiled IL in your assembly, just as if you had written every services.AddTransient<IFoo, Foo>() line by hand. The source generator did the tedious work for you during the build.
Advantages of Source Generation
- Zero Runtime Overhead: Registration code is compiled into your assembly
- AOT Compatible: Works with Native AOT and trimming
- Compile-Time Safety: Registration errors surface during build, not runtime
- Fast Startup: No reflection scanning delays application launch
- Trimming Safe: Works with .NET's linker for smaller deployments
To use this strategy, install the NexusLabs.Needlr.Injection and NexusLabs.Needlr.Injection.SourceGen NuGet packages. The setup is minimal:
using NexusLabs.Needlr;
// Create the Syringe entry point and choose source generation
var provider = new Syringe()
.UsingSourceGen() // Compile-time type discovery
.BuildServiceProvider(); // Build the service provider with discovered services
The call to .UsingSourceGen() tells Needlr to use the registration code that the Roslyn source generator produced at build time. When .BuildServiceProvider() executes, it is not iterating over assemblies and reflecting on types. It is calling the generated methods directly, which makes startup effectively instantaneous regardless of how many types exist in your project.
This is particularly valuable for applications where startup latency matters, such as serverless functions, CLI tools, or microservices that need to scale quickly. If you have worked with IServiceCollection in C# before, the generated code populates the same abstraction you are already familiar with, so nothing downstream changes.
How Reflection Works in Needlr
The reflection strategy takes a different approach. Instead of generating code at compile time, it examines your assemblies at runtime using the System.Reflection APIs. When your application starts, Needlr iterates over the types in the targeted assemblies, inspects their interfaces and base classes, and builds the registration calls dynamically.
To use reflection, install NexusLabs.Needlr.Injection and NexusLabs.Needlr.Injection.Reflection. The configuration code looks nearly identical:
using NexusLabs.Needlr;
// Create the Syringe entry point and choose reflection
var provider = new Syringe()
.UsingReflection() // Runtime type discovery via reflection
.BuildServiceProvider(); // Build the service provider with discovered services
The only line that differs is .UsingReflection() in place of .UsingSourceGen(). Everything else, including the fluent configuration methods for filtering assemblies, excluding types, and applying conventions, remains the same. This is intentional. Needlr's API is designed so that switching strategies is a one-line change, not a rewrite. Both strategies use .BuildServiceProvider() to create the configured service provider.
Reflection scanning does add a small amount of work to application startup. For most applications the overhead is negligible, measured in milliseconds even for large projects. The real cost of reflection is not performance but compatibility: reflection-based code cannot be trimmed safely by the .NET linker, and it is incompatible with ahead-of-time compilation in its default form. We will explore those constraints in the AOT section below.
When Reflection Is Necessary
- Dynamic Plugin Loading: Loading assemblies at runtime that are not known at compile time
- Prototyping: Quick iteration without waiting for source generator tooling
- Legacy Environments: Systems that do not support Roslyn source generators
- Scrutor Integration: Using Scrutor's advanced registration patterns requires reflection
- Runtime Assembly Discovery: Scanning assemblies loaded dynamically from disk or network
The Auto-Configuration Bundle
If you do not want to commit to a single strategy up front, or if you want the simplest possible setup, Needlr provides a bundle package called NexusLabs.Needlr.Injection.Bundle. This package includes both the source generation and reflection packages as dependencies and exposes the .UsingAutoConfiguration() method.
using NexusLabs.Needlr;
// Auto-configuration: tries source gen first, falls back to reflection
var provider = new Syringe()
.UsingAutoConfiguration() // Source gen preferred, reflection fallback
.BuildServiceProvider(); // Build the service provider with discovered services
The auto-configuration strategy attempts to use source generation first. If the generated code is available in the assembly (because the source gen package was included and the project was compiled with it), the bundle uses that path. If the generated code is not present, it falls back to reflection. This makes the bundle useful for library authors who want their code to work in both AOT and non-AOT consuming projects, or for teams that are transitioning from reflection to source generation incrementally.
The trade-off is that you take a dependency on both scanning packages, which increases the package footprint slightly. For applications that know which strategy they want, referencing the specific package directly is cleaner. But for cases where flexibility matters more than minimalism, the bundle is a practical choice.
AOT Compilation and Trimming Compatibility
Native AOT compilation and IL trimming are two related .NET features that reduce application size and improve startup performance by eliminating unused code. AOT compiles your application to native machine code ahead of time, removing the need for the JIT compiler at runtime. Trimming removes types and methods that the linker determines are unreachable.
Both features are hostile to reflection. When the linker analyzes your code, it cannot know which types will be accessed through reflection because those access patterns are determined at runtime. This means the linker may trim away types that your reflection-based scanner needs to discover, and AOT compilation may fail to generate the native code for dynamically invoked methods.
Source generation avoids these problems entirely. Because the registration code is generated at compile time as explicit, statically-typed method calls, the linker can see every type reference and preserve them correctly. AOT compilation handles the generated code just like any other compiled C# code. This is why .UsingSourceGen() is the recommended default for new projects, especially those targeting Native AOT.
Compatibility Comparison
Source Generation:
- ✅ Fully compatible with Native AOT
- ✅ Works with IL trimming
- ✅ No runtime reflection dependencies
- ✅ Compile-time type safety
Reflection:
- ❌ Not compatible with Native AOT (by default)
- ❌ Requires trimming annotations to work safely
- ⚠️ May trim away types needed at runtime
- ⚠️ Runtime reflection overhead
Here is what a typical publish command looks like for an AOT-compatible application using source generation:
<!-- In your .csproj file -->
<PropertyGroup>
<PublishAot>true</PublishAot>
<TrimMode>full</TrimMode>
</PropertyGroup>
dotnet publish -c Release -r linux-x64
With source generation configured, this publish command produces a fully trimmed, AOT-compiled binary that includes all of Needlr's registration logic without any reflection. The generated registration code survives trimming because it consists of direct method calls that the linker can trace statically.
If you attempt the same publish with .UsingReflection(), you will encounter trimming warnings during the build. The linker cannot guarantee that all types accessed via reflection will be preserved, and at runtime you may find that some registrations are missing because their types were trimmed away. You can suppress trimming for specific assemblies using TrimmerRootAssembly, but doing so defeats the purpose of trimming and increases your binary size.
The practical guidance is straightforward: if you are publishing with AOT or full trimming, use .UsingSourceGen(). If you are running on the standard CLR with JIT compilation and no trimming, either strategy works. The auto-configuration bundle handles this gracefully by preferring source generation when it is available.
When Reflection Is the Right Choice
Despite the advantages of source generation, there are legitimate scenarios where reflection is the better option. The most common is dynamic assembly loading, where your application loads plugins or extensions from disk at runtime. These assemblies do not exist at compile time, so the source generator cannot inspect them.
Consider a plugin host that discovers extensions from a directory:
using System.Reflection;
using System.Runtime.Loader;
using NexusLabs.Needlr;
// Load plugin assemblies dynamically at runtime
var pluginDir = Path.Combine(AppContext.BaseDirectory, "plugins");
var pluginAssemblies = new List<Assembly>();
foreach (var dll in Directory.GetFiles(pluginDir, "*.dll"))
{
var context = new AssemblyLoadContext(dll, isCollectible: true);
var assembly = context.LoadFromAssemblyPath(Path.GetFullPath(dll));
pluginAssemblies.Add(assembly);
}
// Reflection is required here because plugin types
// are not known at compile time
var provider = new Syringe()
.UsingReflection()
.UsingAdditionalAssemblies(pluginAssemblies.ToArray())
.BuildServiceProvider();
In this scenario, source generation cannot help. The plugin DLLs are not referenced by the project at compile time, so the Roslyn source generator has no visibility into them. Reflection is the only strategy that can discover types from assemblies loaded after compilation.
If you are building systems that support runtime extensibility, the article on plugin architecture design pattern explains the broader architectural considerations for this kind of design.
Other scenarios where reflection is appropriate include rapid prototyping where you want to avoid waiting for source generator tooling to update, working in IDEs or build environments that do not fully support Roslyn source generators, or maintaining legacy projects where adding a source generator would require significant build pipeline changes.
Comparing the Two Strategies Side by Side
Understanding the tradeoffs between source generation and reflection becomes clearer when you see them in a direct comparison. The two strategies differ in when they do their work, what they are compatible with, and what constraints they impose on your project structure.
Source generation performs all discovery at compile time. This means registration errors surface as build warnings or failures rather than runtime exceptions. If you rename an interface and forget to update an implementation, the source generator either handles it automatically or the build fails, both of which are preferable to a runtime InvalidOperationException when the missing service is first resolved. Reflection, by contrast, defers discovery to startup, which means misconfigurations only appear when the application runs.
From a performance perspective, source generation adds a small amount of time to your build but contributes zero overhead at application startup. Reflection adds zero time to the build but performs work during startup. For most applications the startup cost of reflection is small enough to be irrelevant, but for serverless workloads or CLI tools that start and stop frequently, the difference can accumulate.
The debugging experience also differs. With source generation, you can inspect the generated files in your IDE (typically under the Analyzers node in Solution Explorer) and see exactly what registration code will run. This makes it straightforward to verify that a specific type is being registered the way you expect. With reflection, debugging registration issues requires stepping through the scanner at runtime or adding logging to observe which types are discovered.
Both strategies share the same fluent API surface, which is one of Needlr's design strengths. You can start with reflection for its simplicity, validate that your registrations are correct, and then switch to source generation for production by changing a single method call. This incremental migration path lowers the risk of adopting either strategy. For teams evaluating their overall DI tooling, the comparison of Scrutor vs Autofac provides useful context on how other libraries in the .NET ecosystem approach similar problems.
Making the Decision for Your Project
Choosing between source generation and reflection is not a permanent architectural commitment. Because Needlr abstracts the strategy behind a fluent interface, switching later is low-cost. That said, starting with the right strategy saves you from unnecessary churn.
Use .UsingSourceGen() when you are targeting Native AOT or need your application to be fully trimmable, when startup latency matters and you want zero reflection overhead, when you want compile-time validation that your types are discoverable, or when you are building a new project with no dynamic assembly loading requirements. This covers the majority of .NET applications, which is why source generation is the recommended default.
Use .UsingReflection() when your application loads assemblies dynamically at runtime, such as a plugin host or an extensible platform, when you are working in a build environment that does not support Roslyn source generators, or when you are prototyping and want the fastest possible iteration cycle without waiting for generated code to update.
Use .UsingAutoConfiguration() when you are building a library that may be consumed in either AOT or non-AOT contexts, when you want a fallback mechanism that prefers source generation but does not fail without it, or when your team is migrating from reflection to source generation and needs both strategies available during the transition.
Understanding which approach fits your constraints is part of the broader question of how to design your application's architecture. If you want to explore the patterns that inform these decisions, the big list of design patterns provides a comprehensive overview.
Frequently Asked Questions
What is the difference between source generation and reflection in Needlr?
Source generation uses a Roslyn analyzer that runs during compilation to produce explicit C# registration code. This code is compiled into your assembly and executes as normal method calls at startup. Reflection uses the System.Reflection APIs at runtime to inspect assemblies and discover types dynamically. Both strategies produce the same registrations and share the same fluent API, but they differ in when the work happens, how they interact with AOT and trimming, and whether they can discover types from dynamically loaded assemblies.
Can I switch between source generation and reflection without rewriting my configuration?
Yes. Needlr's fluent API is the same for both strategies. The only change is the method call that selects the strategy: .UsingSourceGen(), .UsingReflection(), or .UsingAutoConfiguration(). All other configuration, including assembly filters, type exclusions, and plugin registrations, remains unchanged. This design makes it practical to start with one strategy and switch to the other as your requirements evolve.
Does source generation slow down my build?
Source generation adds a small amount of time to the compilation phase because the Roslyn analyzer must inspect your project's types and emit registration code. For most projects this overhead is negligible, typically a fraction of a second. The tradeoff is that you gain zero startup overhead at runtime, which is often a much more valuable optimization. Large solutions with many projects may see a slightly longer incremental build, but the impact is comparable to other common source generators in the .NET ecosystem.
Why does reflection not work with Native AOT?
Native AOT compiles your application to machine code ahead of time, which means there is no JIT compiler available at runtime to handle dynamically discovered types. Reflection relies on the runtime's ability to inspect metadata and invoke methods dynamically, which conflicts with AOT's static compilation model. When you use reflection with AOT, the linker cannot determine which types will be accessed at runtime, so it may trim them away. Source generation avoids this because all type references are explicit in the compiled code, allowing the linker to trace and preserve them.
What NuGet packages do I need for each strategy?
For source generation, install NexusLabs.Needlr.Injection and NexusLabs.Needlr.Injection.SourceGen. For reflection, install NexusLabs.Needlr.Injection and NexusLabs.Needlr.Injection.Reflection. For auto-configuration, install NexusLabs.Needlr.Injection.Bundle, which includes both strategies as dependencies. If you are building an ASP.NET Core application, add NexusLabs.Needlr.AspNet alongside whichever strategy package you chose.
Can I use both strategies in the same application?
The .UsingAutoConfiguration() method from the bundle package effectively does this by preferring source generation and falling back to reflection. If you need more granular control, you could configure separate Syringe instances with different strategies, though this is uncommon. The typical pattern is to choose one strategy for your main application and use reflection only for isolated scenarios like plugin loading, where the dynamically loaded assemblies are scanned separately.
How does Needlr compare to using Scrutor or Autofac for assembly scanning?
Scrutor provides assembly scanning on top of the built-in Microsoft DI container, using reflection to discover and register types at startup. Autofac offers its own module system with reflection-based scanning. Needlr differs by offering source generation as a first-class strategy, which neither Scrutor nor Autofac currently provides. This makes Needlr the better choice for AOT and trimming scenarios. For a detailed comparison of the reflection-based alternatives, the article on Scrutor vs Autofac covers the tradeoffs between those two libraries. If you are coming from an Autofac background specifically, dependency injection with Autofac explains the patterns that translate to Needlr's approach.
Wrapping Up
The choice between source generation and reflection in Needlr comes down to your project's deployment model and runtime requirements. Source generation gives you compile-time safety, AOT compatibility, and zero startup overhead, making it the right default for most new projects. Reflection gives you the flexibility to discover types from dynamically loaded assemblies, which is essential for plugin architectures and extensible platforms. The auto-configuration bundle bridges the two by preferring source generation with a reflection fallback.
Because Needlr abstracts both strategies behind the same fluent API, the decision is not irreversible. You can start with whichever strategy fits your current needs and switch later with a single line change. The important thing is to understand what each strategy does, when it does it, and what it means for your build and deployment pipeline, so that you can make an informed choice rather than relying on defaults.