Drop-In Replacement System

Relevant source files

• README.md

The Drop-In Replacement System transparently redirects System.Linq calls to ZLinq's zero-allocation equivalents. A Roslyn source generator (ZLinq.DropInGenerator) emits type-specific extension methods for standard .NET collection types (T[], List<T>, Span<T>, IEnumerable<T>, etc.) that delegate to ZLinq's ValueEnumerable operations. No call-site changes are required.

The key mechanism is method resolution priority: C# selects more specific extension methods over generic ones. A generated extension for T[] takes precedence over System.Linq's extension for IEnumerable<T>, even when both namespaces are in scope.

Sub-page	Content
Configuration and Usage	ZLinqDropInAttribute, DropInGenerateTypes flags, ZLinqDropInExtensionAttribute, ZLinqDropInExternalExtensionAttribute
Code Generation Implementation	DropInGenerator internals, template processing pipeline, FileGen.DropInGen tool

For the core ZLinq architecture that these operations delegate to, see Core Architecture.

System Overview

Two-Phase Architecture

The Drop-In system operates in two distinct phases:

Title: Drop-In System Two-Phase Architecture

• Phase 1: The FileGen.DropInGen tool reflects over ValueEnumerableExtensions and generates C# template files per collection type (Array.cs, List.cs, Span.cs, etc.). These templates are committed to source control and embedded in the generator assembly.
• Phase 2: At user compile time, DropInGenerator (a Roslyn IIncrementalGenerator) reads the ZLinqDropInAttribute from the user's assembly attributes, selects the appropriate templates, and emits .g.cs extension files into the compilation.

Sources: src/FileGen/DropinGen.cs8-88 README.md224-254

Method Resolution Mechanism

Title: How C# Selects ZLinq Over System.Linq

The generated extension for int[] is more specific than System.Linq's extension for IEnumerable<int>. C# always prefers the most specific applicable method, ensuring ZLinq is selected even when both using System.Linq; and using ZLinq; are in scope.

For IEnumerable<T> (the Enumerable flag), the namespace of the generated class controls resolution — code within the configured namespace sees the ZLinq overload first. See Configuration and Usage for the namespace strategy details.

Sources: README.md224-297

Collection Type Mapping

The DropInGen class defines mappings between .NET collection types and their corresponding ZLinq converters. These become the template files embedded in the generator assembly.

Collection Type	Template File	ZLinq Enumerator Struct	DropInGenerateTypes Flag
T[]	Array.cs	FromArray<T>	Array
List<T>	List.cs	FromList<T>	List
Span<T>	Span.cs	FromSpan<T>	Span
ReadOnlySpan<T>	ReadOnlySpan.cs	FromSpan<T>	Span
Memory<T>	Memory.cs	FromMemory<T>	Memory
ReadOnlyMemory<T>	ReadOnlyMemory.cs	FromMemory<T>	Memory
IEnumerable<T>	IEnumerable.cs	FromEnumerable<T>	Enumerable

Sources: src/FileGen/DropinGen.cs23-38

Title: Attribute Flags to Generated Files Mapping

Each generated extension follows a consistent three-step pattern:

1. Null-check the source (for reference types)
2. Call AsValueEnumerable() to create the typed ValueEnumerable<TEnumerator, T>
3. Delegate to the ZLinq operator

See src/FileGen/DropIn/Array.cs15-25 for the array template and Code Generation Implementation for full details on the FileGen.DropInGen tool and DropInGenerator internals.

Sources: src/FileGen/DropinGen.cs23-38 src/FileGen/DropIn/Array.cs15-25

Usage Patterns

Three Entry Points

The system provides three ways to register drop-in support:

Attribute	Purpose	Where declared
ZLinqDropInAttribute	Standard collection types (T[], List<T>, etc.)	Assembly level
ZLinqDropInExternalExtensionAttribute	Third-party types (by fully-qualified name)	Assembly level
ZLinqDropInExtensionAttribute	Custom types in your own assembly	On the type itself

Sources: README.md224-453

Namespace Strategy for IEnumerable<T>

For standard collection types (Array, List, Span, Memory), method resolution is unambiguous — the generated extension receiver type is more specific than IEnumerable<T>. For the Enumerable flag, the generated class's namespace controls which code sees the ZLinq overload.

Title: Namespace Strategy for IEnumerable Drop-In

• Strategy A (recommended when targeting Enumerable): use your app's root namespace so that only your code sees the ZLinq overload; library consumers and code in other namespaces are unaffected.
• Strategy B: use empty string "" to redirect all LINQ calls in every namespace.

Sources: README.md246-297

External and Custom Type Support

• External types: ZLinqDropInExternalExtensionAttribute accepts the metadata name of a type (e.g., "System.Collections.Generic.IReadOnlyCollection\1"). An optional third parameter specifies a concrete IValueEnumeratorstruct for optimized enumeration (e.g.,"ZLinq.Linq.FromImmutableArray`1"`).
• Custom types: ZLinqDropInExtensionAttribute placed on a type generates a {TypeName}ZLinqDropInExtensions partial class in the same namespace. The type may implement IEnumerable<T> (falls back to FromEnumerable<T>) or IValueEnumerable<TEnumerator, T> (uses the custom enumerator for zero-allocation).

See Configuration and Usage for full attribute reference.

Sources: README.md351-453

Generated Code Structure

Standard Extension Pattern

All generated extensions follow a consistent pattern that validates the source and delegates to ZLinq:

Conditional Compilation

The generator includes conditional compilation directives for framework-specific features:

Sources: src/FileGen/DropIn/Array.cs233-240

Constraint Handling

For generic constraints, the generator properly propagates them from the original ZLinq methods:

Sources: src/FileGen/DropIn/Array.cs34-39

Integration with Build System

The Drop-In Generator integrates seamlessly with MSBuild through the standard Roslyn source generator mechanism. The generator assembly includes appropriate MSBuild metadata to ensure it's recognized as an analyzer.

Sources: src/ZLinq.DropInGenerator/bin/Debug/netstandard2.0/ZLinq.DropInGenerator.dll.meta