Skip to content

Latest commit

 

History

History
31 lines (24 loc) · 2.3 KB

source-generator-guidelines.md

File metadata and controls

31 lines (24 loc) · 2.3 KB

Recommended reading to better understand source generators, Roslyn Source Generators Cookbook.

Project guidance

Packaging guidance

Source Generator Best Practices

DOs

  • DO generate code that looks as if a developer would write it manually.
  • DO emit strings rather than using the Roslyn Syntax API for better performance.
  • DO use consistent indentation and formatting in generated code.
  • DO generators should use the IIncrementalGenerator interface.
  • DO set <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules> in the source generator project and then don't use any of the banned APIs it lists.
  • DO set <IsRoslynComponent>true</IsRoslynComponent> in the source generator project to enable debugging support in Visual Studio.
  • DO disable the following Roslyn warning, RS2008, in the source generator project (that is, <NoWarn>$(NoWarn);RS2008</NoWarn>). The reported issue is handled differently in the runtime repo.
  • DO emit diagnostics from a separate analyzer. The analyzer and source generator can be in the same assembly.
  • DO cache intermediate results to avoid redundant computation.
  • DO consider the impact on build time and optimize accordingly.
  • DO have separate projects for testing the generator and testing the code generated by the generator.
  • DO use the Roslyn Testing SDK to test the generator (and any corresponding analyzers).

DON'Ts

  • DON'T use the Roslyn Syntax API for emitting source code.
  • DON'T perform expensive operations during the generation process unless absolutely necessary.
  • DON'T emit code that introduces runtime dependencies not explicitly referenced by the project.
  • DON'T emit code that would trigger compiler warnings in normal usage scenarios.
  • DON'T emit diagnostics from the generator itself, emit them from an analyzer.