ANcpLua.Roslyn.Utilities 2.2.27

👁 NuGet
👁 .NET Standard 2.0

ANcpLua.Roslyn.Utilities

A focused utility library for writing Roslyn source generators, analyzers, and code-fix providers. The shape is opinionated: the types here are the ones that make an incremental generator actually cache, a symbol comparison actually readable, and a code emission actually deterministic.

Agent test doubles, MAF conformance suites, and workflow fixtures live in the sibling ANcpLua.Agents package. This repo focuses on Roslyn/MSBuild/OTel-for-analyzer-authors.

The library is the author's own. Use it, improve it (the upstream is this repo), or propose switching directions — don't reinvent locally.

Packages

Quickstart — writing a source generator

dotnet add package ANcpLua.Roslyn.Utilities.Sources

A canonical incremental generator is ~25 lines when the utilities do their job — see src/ANcpLua.AotReflection/AotReflectionGenerator.cs in this repo for the reference shape:

[Generator]
public sealed class MyGenerator : IIncrementalGenerator
{
 public void Initialize(IncrementalGeneratorInitializationContext context)
 {
 var flows = context.SyntaxProvider.ForAttributeWithMetadataName(
 "MyNamespace.TracedAttribute",
 static (node, _) => node is ClassDeclarationSyntax,
 static (ctx, ct) => TypeExtractor.Extract(ctx, ct));

 var types = flows.ReportAndStop(context);

 var files = types
 .Select(static (m, _) => OutputGenerator.Generate(m))
 .CollectAsEquatableArray();

 files.AddSources(context);
 }
}

What the library provides at each step:

• ForAttributeWithMetadataName — filter syntax before expensive semantic work (Roslyn built-in; the library wraps for ergonomics)
• DiagnosticFlow<T> — railway-oriented pipeline carrying value + accumulated diagnostics, value-equatable for incremental caching
• ReportAndStop — drain the flow into ReportDiagnostic and yield values
• CollectAsEquatableArray / ToEquatableArray / ToEquatableArrayOrDefault — value-equatable collections so the generator cache actually hits
• AddSources — emit FileWithName records without boilerplate
• Match.Type() / Match.Method() — fluent symbol matching, no string comparisons
• IndentedStringBuilder — BeginBlock()/EndBlock() scopes, no hardcoded indentation strings
• GeneratedCodeHelpers — <auto-generated/> headers, #nullable enable, pragma helpers

Testing an agent or a MAF workflow

Agent test doubles (FakeChatClient, FakeReplayAgent, ActivityCollector), the provider-agnostic MAF conformance suite (RunTests, RunStreamingTests, ChatClientAgentRunTests, StructuredOutputRunTests), reference fixtures for OpenAI / Azure / Anthropic / Ollama / Gemini / OpenRouter, and the WorkflowFixture<TInput> harness ship in the sibling ANcpLua.Agents package.

What's in the box

Incremental pipeline (generator authors)

• DiagnosticFlow<T> + DiagnosticFlowReportingExtensions — railway-oriented flow with value + accumulated DiagnosticInfo
• IncrementalValuesProviderExtensions — ReportAndStop, CollectAsEquatableArray, AddSources, and other pipeline verbs
• SyntaxValueProviderExtensions — ergonomic ForAttributeWithMetadataName wrappers
• SourceProductionContextExtensions — context helpers
• EquatableArray<T> + EquatableArrayExtensions (.ToEquatableArray, .ToEquatableArrayOrDefault, .AsEquatableArray) — value equality so the cache actually hits
• FileWithName — record for emitted-file payload
• DiagnosticInfo + LocationInfo + EquatableMessageArgs — value-equatable diagnostic carriers; IsDefault/IsError predicates let pipeline code skip default sentinels at the boundary instead of NRE'ing inside Roslyn
• ResultWithDiagnostics<T> — result payload paired with diagnostics, with HasResult distinguishing a successful null from a no-result envelope. Pair with SelectAndCaptureExceptions (side-effect-free) or SelectAndReportExceptions (chains capture + register-source-output) on IncrementalValuesProviderExtensions.

Symbol analysis & matching

• Match fluent DSL — Match.Type() / Match.Method() / Match.Property() / Match.Field() / Match.Parameter() with the per-kind matchers under Matching/ (MethodMatcher, TypeMatcher, etc.)
• Invoke / InvocationMatcher — invocation-shape matching
• SymbolExtensions, TypeSymbolExtensions, MethodSymbolExtensions, NamespaceExtensions — IsEqualTo, Implements, InheritsFrom, IsOrImplements, GetMetadataName (overloaded for type and namespace symbols), and the usual suspects. Symbol identity beats ToDisplayString() for predicate hot paths — see IsSpanType/IsMemoryType/IsTaskType for the pattern.
• AttributeExtensions — GetAttribute, HasAttribute, TryGetAttribute with constructor-arg accessors
• InvocationExtensions / OperationExtensions / OperationHelper — IInvocationOperation analysis helpers
• SemanticGuard<T> + SemanticGuard — chain semantic predicates with early-exit
• SemanticModelExtensions / CompilationExtensions / SyntaxExtensions

Code emission

• IndentedStringBuilder + IndentScope — BeginBlock()/EndBlock() scopes, no hardcoded indentation
• GeneratedCodeHelpers — <auto-generated/> header, nullable/pragma directives
• ValueStringBuilder — stack-allocated StringBuilder for hot paths
• SyntaxBuilders (Analyzers/) — fluent builders for common code-fix patterns (ExtensionCall, StaticCall, NameOf)

Analyzer authoring

Reusable infrastructure for writing analyzers and code fixes — concrete rules (e.g. AL0126) intentionally ship in ANcpLua.Analyzers.

• DiagnosticAnalyzerBase — convention base class
• DiagnosticCategories / DiagnosticSeverities — category/severity constants
• DeprecatedOtelAttributes — 50+ attribute-name mappings synced to OTel GenAI semconv 1.40 (catches gen_ai.system and friends during analysis)
• IncrementalPipelineHelpers — pipeline wiring utilities
• MappingRegistry / TypeCache<TEnum> — cached lookups for analyzer hot paths

Async & time

• AsyncSequenceExtensions — LINQ-ish operators over IAsyncEnumerable<T>
• ParallelAsyncExtensions — SelectParallel (completion order) / SelectParallelOrdered (source order), channel-based fan-out with linked-CTS cancellation so a single selector exception cancels every sibling worker
• ExpiringCache<TKey,TValue> — access-order LRU with single-flight factory invocation via Lazy<TValue?> (no thundering herd on concurrent misses for the same key)
• TimeConversions — OTel nanosecond helpers

Dictionary & collection ergonomics

• DictionaryExtensions — GetOrInsert(key, context, factory) (closure-free, hot-path), GetOrAdd(key) / GetOrAdd(key, factory) (ergonomic), MapIfAbsent(src, dst, transform) (cross-key copy for vendor-adapter telemetry mappers)
• EnumerableExtensions — dedup, partition, chunking, MinBy/MaxBy
• ListExtensions — in-place mutation helpers

Guards & null handling

• Guard — null / range / path / type guards
• NullableExtensions — Map-style combinators for T?
• TryExtensions — TryParseX (every overload pinned to CultureInfo.InvariantCulture so a German dev's "1,5" doesn't silently parse as 1.5 in production), dictionary GetOrNull / GetOrDefault / GetOrElse

Models & OTel enums

• SpanKind, SpanStatusCode — OTel enums
• PagedResult<T> — standard paginated response shape

Polyfills

Language and API backports for netstandard2.0 consumers (via the separate .Polyfills package):

Disable all at once: <InjectAllPolyfillsOnLegacy>false</InjectAllPolyfillsOnLegacy>

Testing — what ships in .Testing

Generator, analyzer, codefix, refactoring, MSBuild integration, and cross-framework web testing.

• Generator tests: Test<TGenerator> (fluent entry), GeneratorTestHelper.RunGenerator<TGenerator>() (assertion-oriented one-liners), GeneratorCachingReport (compares two runs, detects cache hits), Compile / CompileResult (dynamic compilation with Shouldly-style assertions)
• Analyzer / CodeFix / Refactoring tests: AnalyzerTest<TAnalyzer>, CodeFixTest<TAnalyzer,TCodeFix>, CodeFixTestWithEditorConfig<TAnalyzer,TCodeFix>, RefactoringTest<TRefactoring>, SolutionRefactoringTest<TRefactoring>, LogAssert
• MSBuild integration tests: ProjectBuilder, PackageProjectBuilder, PackageTestBase<TFixture> / NuGetPackageTestBase, NuGetPackageFixture, BuildResult + BuildResultAssertions, SarifFile parsers, DotNetSdkHelpers / NetSdkVersion, MSBuildConstants
• Web testing — one base per framework:
  • xUnit (root): IntegrationTestBase<TProgram>, KestrelTestBase<TProgram>
  • WebTesting/NUnit/, WebTesting/TUnit/, WebTesting/Bunit/ — per-framework equivalents
  • Plus FakeLoggerExtensions for structured log capture
• OTel instrumentation: ActivityInstrumentation, MetricsInstrumentation, LoggingConventions, LogEnricherInfrastructure, DataClassificationHelpers (PII/Secret redaction)

AOT testing — what ships in .Testing.Aot

Separate package (netstandard2.0, zero runtime deps). Attributes + MSBuild props for verifying AOT/trim behavior.

• [AotTest], [AotSafe], [AotUnsafe] — mark methods as AOT-verified or AOT-excluded
• [TrimTest], [TrimSafe], [TrimUnsafe] — same for IL trimming; TrimMode enum selects Partial / Full
• TrimAssert.TypePreserved(...) / TypeRemoved(...) — runtime assertions against the trimmed binary
• FeatureSwitches — constants for common AOT feature switches (e.g. JsonReflection)
• AotRuntime — runtime AOT/trim detection
• MSBuild orchestration (build/*.props + *.targets + ProjectTemplate.csproj.txt) ships inside the package itself; no external SDK dependency

Separate: AOT reflection generator

This repo also ships ANcpLua.Analyzers.AotReflection — an incremental source generator that replaces runtime typeof(T).GetProperties() with compile-time metadata, making types NativeAOT- and trim-safe. Mark a type [AotReflection] and a generated FooMetadata class appears with strongly-typed getter/setter/invoker delegates. Pair with ANcpLua.Roslyn.Utilities.Testing.Aot to verify the output survives PublishAot=true and PublishTrimmed=true.

Design principles

• Compile-time over runtime reflection. EquatableArray<T> for generator caching, DiagnosticFlow<T> for pipeline error accumulation, IndentedStringBuilder for emission — the shape of an incremental generator the compiler cache actually likes.
• Allocation-conscious in analyzer hot paths. ValueStringBuilder for stack-allocated string building, Boxes for cached boxed primitives, closure-free GetOrInsert<TContext> for dictionary inserts.
• OTel semconv 1.40 native. DeprecatedOtelAttributes catches gen_ai.system and 50+ other deprecated attribute names during analysis.
• Test discipline. GeneratorCachingReport over hand-rolled cache assertions. Test<TGenerator> fluent runner over hand-rolled CSharpGeneratorDriver plumbing. The shipped-internally ForbiddenTypeAnalyzer catches ISymbol/Compilation snuck into pipeline models. Agent-specific test doubles live in the sibling ANcpLua.Agents package.
• Source-only delivery for generators. The .Sources package rewrites the utilities to internal via a pack-time PowerShell transform (Transform-Sources.ps1), because source generators can't load NuGet DLLs at runtime.

Documentation

ancplua.mintlify.app/utilities — full API reference with examples.

Related

• ANcpLua.NET.Sdk — opinionated .NET SDK wrapper built on the same conventions
• ANcpLua.Analyzers — the author's analyzer catalogue, built on these utilities
• ANcpLua.Agents — agent test doubles, MAF conformance, workflow fixtures

License

MIT © Alexander Nachtmann