Enforce analyzer best practices

n="3.3.4" PrivateAssets="all" /> </ItemGroup> </Project>

### Step 2: Implement the Incremental Generator

Modern generators must implement `IIncrementalGenerator`. The incremental pipeline caches syntax, semantic, and emission stages, ensuring only changed files trigger regeneration.

```csharp
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using Microsoft.CodeAnalysis.Text;
using System.Collections.Immutable;
using System.Linq;
using System.Text;

[Generator]
public class NotifyPropertyChangedGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // Stage 1: Filter classes with [Observable] attribute
        var candidateClasses = context.SyntaxProvider
            .CreateSyntaxProvider(
                predicate: static (node, _) => node is ClassDeclarationSyntax { AttributeLists.Count: > 0 },
                transform: static (ctx, _) => GetTargetClass(ctx))
            .Where(static m => m is not null);

        // Stage 2: Combine with compilation for semantic validation
        var compilationAndClasses = context.CompilationProvider.Combine(candidateClasses.Collect());

        // Stage 3: Generate source
        context.RegisterSourceOutput(compilationAndClasses,
            static (spc, source) => Execute(source.Left, source.Right!, spc));
    }

    private static ClassDeclarationSyntax? GetTargetClass(GeneratorSyntaxContext ctx)
    {
        var classNode = (ClassDeclarationSyntax)ctx.Node;
        foreach (var attributeList in classNode.AttributeLists)
        {
            foreach (var attribute in attributeList.Attributes)
            {
                if (ctx.SemanticModel.GetSymbolInfo(attribute).Symbol is IMethodSymbol methodSymbol)
                {
                    var attrClass = methodSymbol.ContainingType;
                    if (attrClass.ToDisplayString() == "ObservableAttribute")
                        return classNode;
                }
            }
        }
        return null;
    }

    private static void Execute(Compilation compilation, ImmutableArray<ClassDeclarationSyntax?> classes, SourceProductionContext context)
    {
        foreach (var classNode in classes)
        {
            if (classNode is null) continue;

            var semanticModel = compilation.GetSemanticModel(classNode.SyntaxTree);
            var classSymbol = semanticModel.GetDeclaredSymbol(classNode);
            if (classSymbol is null) continue;

            var namespaceName = classSymbol.ContainingNamespace.IsGlobalNamespace
                ? null
                : classSymbol.ContainingNamespace.ToDisplayString();

            var className = classSymbol.Name;
            var properties = classSymbol.GetMembers()
                .OfType<IPropertySymbol>()
                .Where(p => p.DeclaredAccessibility == Accessibility.Public && !p.IsStatic);

            var sb = new StringBuilder();
            sb.AppendLine("using System.ComponentModel;");
            sb.AppendLine("using System.Runtime.CompilerServices;");
            sb.AppendLine();

            if (namespaceName is not null)
            {
                sb.AppendLine($"namespace {namespaceName};");
                sb.AppendLine();
            }

            sb.AppendLine($"public partial class {className} : INotifyPropertyChanged");
            sb.AppendLine("{");
            sb.AppendLine("    public event PropertyChangedEventHandler? PropertyChanged;");
            sb.AppendLine();
            sb.AppendLine("    protected void OnPropertyChanged([CallerMemberName] string? propertyName = null)");
            sb.AppendLine("    {");
            sb.AppendLine("        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));");
            sb.AppendLine("    }");
            sb.AppendLine();

            foreach (var prop in properties)
            {
                var propName = prop.Name;
                var backingField = $"_{char.ToLowerInvariant(propName[0])}{propName.Substring(1)}";
                var type = prop.Type.ToDisplayString();

                sb.AppendLine($"    private {type} {backingField};");
                sb.AppendLine($"    public {type} {propName}");
                sb.AppendLine("    {");
                sb.AppendLine($"        get => {backingField};");
                sb.AppendLine("        set");
                sb.AppendLine("        {");
                sb.AppendLine($"            if (!Equals({backingField}, value))");
                sb.AppendLine("            {");
                sb.AppendLine($"                {backingField} = value;");
                sb.AppendLine($"                OnPropertyChanged();");
                sb.AppendLine("            }");
                sb.AppendLine("        }");
                sb.AppendLine("    }");
                sb.AppendLine();
            }

            sb.AppendLine("}");

            var hintName = $"{namespaceName ?? "Global"}.{className}.Observable.g.cs";
            context.AddSource(hintName, SourceText.From(sb.ToString(), Encoding.UTF8));
        }
    }
}

Step 3: Define the Marker Attribute

The generator targets classes explicitly decorated with a marker attribute. This prevents accidental transformation of unrelated types.

[System.AttributeUsage(System.AttributeTargets.Class, Inherited = false)]
public sealed class ObservableAttribute : System.Attribute { }

Step 4: Consume in Consumer Project

Reference the generator project as an analyzer reference. The generator executes automatically during compilation.

<ItemGroup>
  <ProjectReference Include="..\NotifyGenerator\NotifyGenerator.csproj"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
</ItemGroup>

Usage:

[Observable]
public partial class UserViewModel
{
    public string Name { get; set; } = string.Empty;
    public int Age { get; set; }
}

The compiler produces a partial class implementing INotifyPropertyChanged with backing fields and change notification logic. No runtime reflection, no manual boilerplate, full IDE support.

Architecture Decisions

• Incremental over Standard: IIncrementalGenerator is mandatory for production. The standard ISourceGenerator runs on every compilation change, causing full rebuilds and IDE lag.
• Semantic Validation: Filtering by attribute alone is insufficient. Combining syntax candidates with the compilation provider ensures referenced types resolve correctly and prevents false positives across project boundaries.
• Partial Class Requirement: Generated code must merge with user code. Enforcing partial on target classes prevents compilation conflicts and allows manual method additions.
• Source Text Encoding: Explicit UTF-8 encoding prevents BOM-related parsing issues in cross-platform CI environments.

Pitfall Guide

1. Using ISourceGenerator Instead of IIncrementalGenerator The legacy interface bypasses caching, forcing Roslyn to re-execute the generator on every keystroke or file change. This causes IDE freezes and CI timeouts. Always implement IIncrementalGenerator and structure the pipeline with CreateSyntaxProvider, Combine, and RegisterSourceOutput.

2. Generating Duplicate or Conflicting Code If multiple projects reference the same generator without proper isolation, or if users manually implement methods that overlap with generated ones, compilation fails. Mitigate by generating into unique hint names, enforcing partial classes, and avoiding method overloads that conflict with user code.

3. Ignoring Compilation Context and Semantic Models Syntax-only analysis misses type resolution, accessibility modifiers, and generic constraints. Always pull the SemanticModel from the compilation provider to validate symbols, resolve namespaces, and handle inheritance correctly.

4. Skipping Diagnostic Reporting Silent generator failures produce confusing compiler errors downstream. Register DiagnosticDescriptor instances and report warnings/errors when target classes lack partial, use unsupported types, or violate generator constraints. This surfaces issues at the correct location.

5. Treating Generators as Runtime Logic Source generators execute once during compilation. They cannot replace runtime factories, dependency injection containers, or dynamic proxies. Use them for static boilerplate, contract generation, or compile-time validation. Runtime behavior requires traditional patterns.

6. Overcomplicating Syntax Walking Custom SyntaxWalker implementations often miss edge cases like nested classes, partial declarations across files, or XML documentation nodes. Prefer CreateSyntaxProvider with targeted predicates and let Roslyn handle traversal. Validate with Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.

7. Neglecting Incremental Pipeline Caching Failing to use .Collect(), .Combine(), or .Select() breaks the incremental chain. Roslyn cannot cache intermediate results, forcing full regeneration. Structure pipelines as: Syntax → Semantic → Emission, with explicit caching at each stage.

Production Bundle

Action Checklist

• Replace ISourceGenerator with IIncrementalGenerator and implement the three-stage pipeline
• Define explicit marker attributes to scope generator targets and prevent accidental transformations
• Validate semantic symbols using CompilationProvider instead of relying on syntax-only filters
• Register DiagnosticDescriptor instances to report generator-specific warnings and errors
• Enforce partial class requirements and verify no naming collisions with user code
• Add unit tests using Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing to validate output
• Configure consumer projects with OutputItemType="Analyzer" and ReferenceOutputAssembly="false"

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Static boilerplate (INotifyPropertyChanged, DTOs, serialization)	Source Generator	Compile-time generation, zero runtime overhead, full IDE support	Low build time, high maintainability
Dynamic runtime behavior (factories, proxies, AOP)	Runtime Reflection / IL Emit	Requires runtime type inspection, dynamic invocation	Medium runtime overhead, complex debugging
Legacy build pipelines without Roslyn SDK	T4 Templates	Compatible with older toolchains, file-based output	High maintenance, poor IDE integration
Cross-language or framework-agnostic generation	External CLI / Build Tool	Language-agnostic, integrates with CI/CD pipelines	Medium operational cost, separate deployment

Configuration Template

Consumer project .csproj setup for analyzer integration:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\MyGenerator\MyGenerator.csproj"
                      OutputItemType="Analyzer"
                      ReferenceOutputAssembly="false" />
  </ItemGroup>

  <ItemGroup>
    <!-- Optional: Inspect generated files during debugging -->
    <None Include="$(CompilerGeneratedFilesOutputPath)\**\*.cs" Visible="false" />
  </ItemGroup>
</Project>

Generator project .editorconfig for analyzer rules:

[*.cs]
# Enforce analyzer best practices
is_external_init = true
dotnet_diagnostic.CS8600.severity = warning
dotnet_diagnostic.CS8603.severity = warning

Quick Start Guide

1. Create a new class library targeting .NET 8.0. Add Microsoft.CodeAnalysis.CSharp and Microsoft.CodeAnalysis.Analyzers packages. Set <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>.
2. Implement IIncrementalGenerator with a syntax predicate, semantic validation, and RegisterSourceOutput. Define a marker attribute to scope targets.
3. Create a consumer project. Reference the generator using OutputItemType="Analyzer" and ReferenceOutputAssembly="false". Apply the marker attribute to a partial class.
4. Build the solution. Inspect generated code via EmitCompilerGeneratedFiles or the IDE's "View Generated Files" feature. Validate output matches expected boilerplate.
5. Add unit tests using SourceGeneratorTest framework to verify syntax filtering, semantic validation, and edge cases. Commit and integrate into CI pipeline.