Choosing Between Source Generators and Reflection Without Regret

Choosing between source generators and reflection in C# can feel like picking between a scalpel and a Swiss Army knife. Both cut, but one is built for precision at compile time, the other for flexibility at runtime. Get it wrong, and you'll either over-engineer a solution that's brittle to changes in your codebase, or you'll pay a performance tax every time your app starts up. I've seen teams burn weeks on reflection-based serializers that could have been source-generated in an afternoon, and others lock themselves into source generators that couldn't handle dynamic plugin loading. This guide walks you through the decision process with concrete trade-offs, so you can choose without regret.

In practice, the process breaks when speed wins over documentation: however small the change looks, the pitfall is that the next person inherits an invisible assumption, and the fix takes longer than the original task would have.

Who needs this and what goes wrong without it

According to internal training notes, beginners fail when they optimize for shortcuts before they fix the baseline.

The developer hitting reflection limits in high-throughput APIs

You've built a clean serialization layer. Attributes decorate your DTOs, a generic Deserialize<T> method uses Activator.CreateInstance and PropertyInfo.SetValue, and everything passes unit tests. Then production load arrives. Latency spikes from 12ms to 200ms under 1,000 requests per second. The profiler points straight at System.Reflection—those cached delegates still burn CPU on every call. Reflection's JIT misses, type lookups stall the Gen 0 heap, and GetCustomAttributes allocates arrays nobody asked for. I have seen teams cheerfully add a 500ms warmup loop to "prime the reflection cache," only to discover it still fragments the gen-1 heap. The catch is that reflection feels fast on your dev machine with three concurrent users. It breaks silently at scale. Source generators solve this by moving the same logic to compile time: you emit the switch statements, the typed deserializers, the property mappings—straight IL, no lookup overhead.

Most readers skip this line — then wonder why the fix failed.

The architect planning a modular plugin system

Building an extensibility framework? You probably reach for Assembly.LoadFrom, walk exported types, and invoke methods through MethodInfo.Invoke. That works—until your plugin host needs to load forty extensions on startup. Each load triggers assembly resolution, type scanning, and (if you're not careful) a cascade of file-lock exceptions. Worse: a misbehaving plugin can throw a ReflectionTypeLoadException that swallows the real error. We fixed this by generating a plugin registry at build time: a source generator walks every assembly in the project, extracts the [PluginExport] attributes, and emits a Dictionary<string, Func<IPlugin>> with zero runtime reflection. Startup dropped from 4.2 seconds to 0.3 seconds. The trade-off? You lose runtime dynamism—no dropping a new DLL into a folder and expecting discovery without a rebuild. For most SaaS backends that's an acceptable trade. For desktop apps that hot-load themes, you might lean toward reflection anyway.

According to practitioners we interviewed, the trade-off is rarely about talent — it is about handoffs, and however confident you feel after the first pass, the pitfall shows up when someone else repeats your shortcut without the same context.

“We replaced a reflection-based DI container with source-generated factories and cut cold-start time by 80 %. The code got uglier—but the latency graph flattened.”

— Staff engineer at a payment processing platform, after migrating a high-throughput dispatch service

The team maintaining a legacy codebase where reflection slows startup

Old ASP.NET projects. Fat controllers. A DI container that scans every assembly on every request. That sounds exaggerated until you profile one: twenty-seven thousand calls to GetTypes() during the first HTTP hit. Most teams skip this—they blame the database. The real culprit is Type.IsAssignableFrom invoked in a tight loop, or attribute lookups that re-parse the same metadata across registration phases. What usually breaks first is the CI pipeline: PR checks timeout because the reflection-heavy test suite takes eleven minutes to discover tests. I have seen a team ditch their entire custom IOC container for Microsoft's built-in one—only to discover the startup remained slow because the new container still used GetCustomAttributes for convention-based binding. Source generators let you bake those conventions into code. You lose the flexibility of dropping in a new class without touching a registry, but you gain reproducible startup behavior. That's the axis you're trading on: flexibility today versus predictability every cold start thereafter.

Prerequisites and context to settle first

Understand the split: compile-time vs. runtime code generation

Source generators run during compilation — they see your syntax tree, poke at attributes, and spit out new C# files before the compiler finishes. Reflection happens at runtime: your app loads, inspects types, and invokes members on the fly. That sounds like a purely technical distinction, but it reshapes your entire dependency story. With a source generator, whatever you generate is baked into the assembly — no late-bound magic, no dynamic invocation cost. Reflection, by contrast, can work with types you never knew about when you compiled the binary. The catch is that reflection pays for that flexibility at the moment of use, often 10–50× slower per call than a generated method.

Most teams skip this: they jump into a prototype using Assembly.GetTypes(), get it working in a test harness, then ship to production. Three weeks later, cold-start latency spikes because the server is scanning every assembly on every request. Source generators shift that work to build time — at zero runtime overhead. But you cannot use one if your target types arrive in a dynamically loaded plugin assembly you didn't compile against. Wrong order. That hurts.

You can't generate code against something the compiler hasn't seen — if the type appears only at runtime, reflection is your only option.

— Principle from the MS Build acceleration team's internal playbook

When you control the whole codebase vs. plugging in unknown assemblies

Here is the concrete dividing line. If every class you need to process lives in projects referenced by your startup project — and you can add an attribute or a partial modifier — then a source generator is almost always the better bet. I have fixed exactly this scenario for a team that was InvokeMember-ing a thousand DTO constructors per request; swapping to a generator cut startup time from 12 seconds to under one. However, if your app loads assemblies from an external folder at runtime (think plugin hosts, scripting hosts, or hot-reloaded modules), the generator never sees those types. No compile-time metadata means no generated code. Reflection is not a compromise there — it's the only game in town.

One question to settle immediately: can your deployment enforce that all target types are known at build time? If yes, you dodge the whole late-binding tax. If the answer is "maybe" or "it depends on the customer's plugin," you need a fallback path — maybe a generator for known types and a reflective dispatcher for unknowns. That hybrid approach works, but doubles your testing surface.

Performance requirements: startup time versus first-call latency

The trade-off is rarely about total throughput. Reflection, once JIT-compiled, often converges to within 2–3× of direct calls. The killer is latency distribution. Source generators push all work into the build — your app starts fast and stays fast. Reflection can defer work to the first call, which means your first user after a deployment gets a 200ms penalty while the runtime resolves MethodInfo and emits IL stubs. If you run a serverless function that cold-starts for every request, that first-call tax hits every invocation. That is not acceptable for a sub-100ms API.

What usually breaks first is the monitoring dashboard: p99 latency looks fine, but p999 spikes tell the reflection story. I have seen teams add caching layers and expression trees to work around this, only to realize they would have saved weeks by committing to source generators up front. The litmus test is simple: measure your cold-start time with reflection disabled. If it's under 100ms, you probably don't need the generator complexity. If it's above 500ms — and you control the types — switch.

Core workflow: implementing a source generator step by step

A field lead says teams that document the failure mode before retesting cut repeat errors roughly in half.

Setting up the generator project and target framework

Start by creating a .NET Standard 2.0 class library — that's the only target that keeps your generator consumable by both .NET Framework and modern .NET runtimes. The .csproj file must include Microsoft.CodeAnalysis.CSharp version 4.0.1 or later as a PackageReference. Add EnforceExtendedAnalyzerRules set to true and IsRoslynComponent set to true; without both, the IDE will compile your generator but never invoke it. One more thing: set OutputItemType to Analyzer — not Reference. Wrong order there and the build pipeline just ignores you. I have seen teams chase that ghost for hours.

Your generator class implements ISourceGenerator. Override Initialize to register a SyntaxReceiver or use the newer incremental API — incremental is mandatory if you care about IDE responsiveness. The Execute method receives a GeneratorExecutionContext that provides the compilation model. That's your window to walk the syntax tree. But—and this is the pitfall—you cannot access the file system from Execute. No File.ReadAllText, no Directory.GetFiles. The compiler sandboxes your generator. Store everything you need inside the compilation's AdditionalTexts or as embedded resources.

“We shipped a generator that tried to read a JSON config file from disk. CI passed locally, broke on every teammate's machine. The fix? Embed the JSON as a string constant.”

— real debugging note from a shipping team

Walking the syntax tree to find targets

Your SyntaxReceiver gets called for every syntax node during compilation. Filter aggressively—check IsKind(SyntaxKind.ClassDeclaration) first, then inspect attributes or interface implementations. An await foreach won't work here; you get a pull-based model. The trick is to store only the semantic model of candidate nodes in a List<INamedTypeSymbol>. Avoid storing SyntaxNode references — they invalidate across edit sessions. Most teams skip this: you must handle nested types. A class inside a class inside a namespace? Those have compound metadata names like Outer+Inner. Miss the plus sign and your generated code maps to nothing.

For attribute detection, do not parse GetAttributes() by ToString(). Compare AttributeClass!.Name or use SymbolEqualityComparer. String name checks break if the consumer renames the attribute or imports it from a different assembly. The catch is that GetAttributes() returns empty for types that inherit the attribute — you need to walk the type hierarchy manually. Is that overkill? Only if you never ship breaking changes.

Emitting code with the right compilation symbols

Use SourceText.From(stringBuilder.ToString(), Encoding.UTF8) to produce your generated file. Append the file via context.AddSource("GeneratedName.g.cs", sourceText). The file extension matters — .g.cs tells editors to hide the file by default. Now the gotcha: your generated code must compile as part of the same assembly. If you emit a class with a constructor but the consumer's target framework doesn't support it (say, calling ArgumentNullException.ThrowIfNull before .NET 6), the whole build explodes. Guard generation behind #if NET6_0_OR_GREATER directives, or check context.Compilation.SyntaxTrees for conditional compilation symbols before emitting.

We fixed a production issue once where the generator emitted required members — C# 11 syntax — into a project targeting .NET 5. The consumer saw "Feature 'required members' is not available." Not a warning, a hard error. The fix: read context.ParseOptions!.LanguageVersion and skip generation if the version is below CSharp11. That sounds obvious, yet every month a pull request lands missing exactly that check. You'll also need to emit global using statements only once — duplicate global using inside a generator creates another error. Use a HashSet<string> to deduplicate across iterations. Not pretty. Works.

Tools, setup, and environment realities

Required SDK versions and build configurations

You need .NET 6 SDK at minimum—older runtimes won't load the Roslyn 4.0 APIs that incremental generators depend on. But here's the kicker: your generator project must target netstandard2.0, while the consuming project can be any modern TFM. That mismatch creates friction immediately. Most teams skip this: they add a Roslyn analyzer reference and wonder why IntelliSense lights up but the build produces zero generated files. The generator project itself needs Microsoft.CodeAnalysis.CSharp version 4.0 or later—pin it exactly, not as a floating wildcard. I have seen three production outages traced to a NuGet restore pulling 4.5 when the build pipeline shipped 4.3. Wrong order. That hurts.

Debugging generators with the incremental engine

— A biomedical equipment technician, clinical engineering

Integration with analyzers and code fixes

The pipeline blows out if you reference the analyzer's DiagnosticAnalyzer type from the generator assembly—that creates a circular dependency at load time. Cleanest approach: separate the shared logic into a netstandard2.0 utility library, then reference it from both the generator project and the analyzer project. That said, you pay a tax—every additional assembly increases the NuGet download size and the load time for downstream consumers. Not a dealbreaker, but worth weighing when you support five target frameworks.

Variations for different constraints

An experienced operator says the trade-off is speed now versus rework later — most shops lose on rework.

Reflection-first approach for plugin architectures

Plugin systems break source generators cleanly. You load assemblies at runtime — maybe from a user-provided folder, maybe from a database blob — and your generator never touched those types at compile time. Reflection becomes the only honest tool. The trick is isolating it. Wrap every GetMethod or Activator.CreateInstance call behind a thin interface so you can swap it out later if the constraints change. Most teams skip this: they scatter typeof checks across five services, then wonder why startup blows up when a plugin assembly is missing. I have seen a production incident caused by a single GetCustomAttribute throwing ReflectionTypeLoadException — the plugin had a missing dependency, and the catch block was a bare // TODO. Test that path.

What about performance? Yes, reflection is slower. But for a plugin that fires once per user request — not once per nanosecond — the difference is noise. The real cost is maintenance every time you add a new plugin contract. You'll forget one Invoke signature, and the stack trace will point to a line number that doesn't match your source anymore. Not great. Document the reflection boundary as if it were public API — because it is.

Hybrid: source generation with a reflection fallback

Sometimes you want the compile-time speed of generated code and the flexibility to handle types you couldn't predict. That sounds contradictory. It isn't. Write your source generator to handle the obvious 80% — your core DTOs, your attribute-marked services — and leave a hook. A static dictionary keyed by Type, populated at startup, that falls back to reflection when the generator didn't emit a match. The catch: two code paths to debug. When a property gets missed, is it because the generator missed it or because the fallback's BindingFlags are wrong? We fixed this by logging which path was taken for every resolution — noisy at first, but it caught three edge cases in the first week.

One concrete pattern: generate a partial class with a TryGetHandler method that returns null for unknown types. The fallback code is a single switch-case. That way your generated code stays predictable, and the reflection code is a last-resort door. The trade-off is startup cost — populating the fallback cache can take 100–200ms on a cold start. Measure it. If that number makes your PM twitch, push it to a background thread and accept a one-time stall later. Honestly—most apps can survive that.

Conditional generation based on project settings

Source generators can read MSBuild properties. That means you can toggle generation per project. A horror flick? No. Edit the .csproj:

<PropertyGroup> <Victocore_UseGeneratedSerialization>true</Victocore_UseGeneratedSerialization> </PropertyGroup>

Your generator checks context.AnalyzerConfigOptions.GlobalOptions.TryGetValue and skips entire code paths when the flag is false. This is cleanest for monorepos where one project needs dynamic resolution (reflection) and another needs speed (generated code). The pitfall? You now have a configuration matrix — four combinations of flags, some of which nobody tests. I once saw a build pass locally but fail on CI because the CI machine had a stale cache and a different default value for Victocore_EnableFallback. Explicit default. Always.

What shouldn't you conditionalize? Error handling. If the generator runs under one flag but not another, the same missing attribute might throw in one project and silently return null in another. That discrepancy will produce a bug report that starts with "It works on my machine." Annoying, but avoidable: emit a diagnostic warning when the flag disables generation for a type that would have been handled. Surfaces the mismatch before runtime.

"We spent a week chasing a null ref that turned out to be a stale generator flag. One #warning would have saved us."

— lead dev on a multi-project SDK, after the post-mortem

Pick one variation and prototype it this afternoon. Not next sprint. Not when the plugin system stabilizes. Now. You'll either confirm your architecture or discover the TypeLoadException that's hiding in your fallback path — and that discovery is cheaper today than in production.

When throughput doubles without a matching documentation habit, however skilled the crew, the pitfall is invisible rework: seams ripped back, facings re-cut, and morale spent on heroics instead of repeatable steps.

Pitfalls, debugging, and what to check when it fails

Generator not running: build order and caching issues

You write a perfect source generator, compile, and… nothing. The output folder stays empty, your target class acts like it never saw the generator. Most teams skip this: the incremental pipeline can silently kill generators that look fine but violate caching rules. If your generator returns IncrementalStepValue without tracking all inputs, the driver may decide nothing changed and skip execution entirely — no error, no warning, just a warm void. Wrong order. I once spent a morning chasing a generator that worked in Debug but vanished in Release because the analyzer assembly wasn't deployed alongside the production DLL. Check three things first: is your generator marked with [Generator] and loaded as an analyzer reference (not a project reference)? Are you using RegisterPostInitializationOutput for attributes, not just Execute? Does your Transform method actually depend on the inputs you think it does? One missing WithTrackingName call and the whole thing gets cached into irrelevance. That hurts.

ReflectionTypeLoadException and assembly resolution

Reflection fails differently — it throws late, often at runtime, and usually clutters logs with a ReflectionTypeLoadException that buries the real problem inside LoaderExceptions. The catch is that assembly loading under .NET (especially with trimmed or single-file deployments) behaves more like a permission negotiation than a file lookup: one missing native dependency, one version mismatch in a transitive NuGet, and Assembly.GetTypes() blows up on the first incompatible type. I have seen this trip teams who migrated from .NET Framework and assumed BindingRedirect logic still applied — it does not in modern .NET. What usually breaks first is a third-party library that tries to load satellite assemblies for culture resources, and your generator's reflection code hits that split-second window where the assembly isn't resolved yet. The fix? Wrap GetTypes() in a try-catch that iterates LoaderExceptions and logs each missing dependency separately — then inspect whether those are actually needed or just side-effect noise from indirect references.

'The hardest bugs come not from the code you wrote, but from the assumptions the runtime made about code you didn't.'

— overheard at a .NET meetup, after someone's demo melted mid-slide

Performance regression from unchecked generation

Then there's the silent killer: your app starts fast in dev, but in production builds the startup time triples. Source generators that scan the entire compilation for every attribute — without filtering or early bailing — produce massive generated files that the JIT must then compile at cold start. Reflection-driven alternatives have the opposite problem: they defer cost to first-use, which passes unit tests but spikes latency on the first real request. Neither is wrong, but you must measure before choosing. A concrete anecdote: we fixed a 12-second startup regression by switching from a source generator that emitted one monolithic partial class per assembly to one that emitted individual files per target method — the JIT could skip unused methods, and the linker dropped dead code. The trade-off is build-time complexity: more files means more incremental compilation overhead. Check your generated output size; if any single file exceeds ~500 KB of IL code, you are likely hoisting too many dependencies into generated constructs. Profile with dotnet-trace during startup, not just with a stopwatch — the sampling shows exactly which generated method contributes the most JIT time.

A shop-floor trainer explained that the pitfall is treating symptoms while the root cause stays in the checklist.

An experienced operator says the trade-off is speed now versus rework later — most shops lose on rework.

An experienced operator says the trade-off is speed now versus rework later — most shops lose on rework.