#Roslyn In Depth

Analyzers, Source Generators, and Compiler-Powered Tooling

Roslyn In Depth cover

##The C# compiler is a library

csc is not a sealed executable that swallows .cs files and spits out a DLL. It is a set of NuGet packages you can reference from a console application, and every intermediate result it computes on the way from text to IL is a public API you are allowed to call: the token stream, the syntax tree, the symbol table, the bound operations, and the diagnostics.

That design decision is why your editor can rename a symbol across a solution without regular expressions, why a NuGet package can add a compile error to your build, and why a library can write code for you at compile time instead of doing reflection at run time. This book is about building those things yourself.

##What you will build

Separate, self-contained samples rather than one product grown chapter by chapter:

  • Analyzers that report a problem as the user types, on the right span, with no false positives, and that cost almost nothing on projects they do not apply to
  • A code fix that repairs the problem without destroying the surrounding formatting, and that survives "Fix all occurrences in solution"
  • A refactoring offered at the cursor, and a suppressor that silences someone else's rule when you have context they do not
  • Incremental source generators whose pipelines stay cached between keystrokes, with tests that prove it
  • A NuGet package carrying an analyzer, its code fix, and a generator, with a consumer test that restores the real package, and a second package that ships one analyzer built against more than one Roslyn version
  • Two solution-wide tools on MSBuildWorkspace: one that answers a question about every project in a real solution, and one that rewrites it and hands you a reviewable diff

##Beyond your first analyzer

Getting a first analyzer to fire is the easy half. This book spends its length on the half that decides whether anyone keeps your component installed: the registration model and what each hook costs, diagnostic design and false positives, configuration, real test suites, measured performance, the equality rules without which a generator silently stops being incremental, packaging, and versioning against a compiler you do not control.

##Who this book is for

You are comfortable in C#. You have used analyzers and generators as a consumer: you have seen a CA warning, and you have used a generator that shipped with a library. Now you want to be on the other side of that line. No compiler background is needed: the book teaches the parts of the pipeline it needs, when it needs them. There is no chapter on parser theory, because writing an analyzer does not require one. No MSBuild knowledge is assumed either.

Eight parts, 38 chapters, and nine appendices, including reading paths for each kind of component, a troubleshooting chapter organized by symptom, cheat sheets for syntax, symbols, and IOperation, and a Roslyn version matrix. Samples target the .NET 10 SDK.

##Table of contents

Part I: The Compiler as a Library

  1. What Is Roslyn?
  2. The Compilation Pipeline and the Object Model
  3. The Syntax API
  4. The Semantic API
  5. The IOperation API and Flow Analysis
  6. Diagnostics: The Common Currency

Part II: Choosing the Right Extension Point

  1. What You Can Build with Roslyn (and What You Can't)

Part III: Production Analyzers

  1. Your First Analyzer
  2. The Registration Model in Depth
  3. Designing Diagnostics That People Keep Enabled
  4. Configuring Compiler Components: EditorConfig, MSBuild, and AdditionalFiles
  5. Testing Analyzers
  6. Analyzer Performance
  7. Suppression: #pragma, Attributes, and DiagnosticSuppressor

Part IV: Fixes and Refactorings

  1. Code Fixes
  2. Editing Code Without Breaking It
  3. Refactorings
  4. Testing Fixes and Refactorings

Part V: Source Generators

  1. Source Generators: The Model
  2. Incremental Generators in Depth
  3. Caching and Equality
  4. Emitting Good Code
  5. Generator Diagnostics and Failure Modes
  6. Testing and Debugging Generators
  7. Beyond Generation: Interceptors

Part VI: Shipping and Adoption

  1. Packaging Analyzers and Generators as NuGet Packages
  2. Versioning Against Roslyn
  3. Release Tracking, Documentation, and Analyzer Hygiene
  4. Consuming Analyzers at Scale

Part VII: Workspaces and Solution Tools

  1. The Workspaces API
  2. MSBuildWorkspace: Loading a Real Solution
  3. Analyzing a Whole Solution
  4. Rewriting a Whole Solution
  5. Formatting and Code Style, Programmatically
  6. Compiling and Running C# at Run Time

Part VIII: Hosts, Recipes, and Troubleshooting

  1. Roslyn Inside the Tools
  2. Recipes and Case Studies
  3. Anti-Patterns and Pitfalls

Appendices

  • Appendix A: Syntax Cheat Sheet
  • Appendix B: Symbol API Cheat Sheet
  • Appendix C: IOperation Quick Reference
  • Appendix D: The Version Matrix
  • Appendix E: Component Template Pieces
  • Appendix F: Diagnostic ID Prefixes
  • Appendix G: Tooling
  • Appendix H: Glossary
  • Appendix I: Further Resources

##Get the book