Roslyn Source Generators: Configuration – Part 10

.NET, .NET CORE

In this article we will see how to pass configuration parameters to a Roslyn Source Generator to control the output or enable/disable features.

Roslyn Source Generators: Configuration – Part 10

Pawel Gerr

Pawel Gerr is architect consultant at Thinktecture. He focuses on backends with .NET Core and knows Entity Framework inside out.

Article series

More information about the Smart Enums and the source code can be found on GitHub:

Smart Enums
Source Code (see commits starting with message “Part 10”)

In the previous article we talked about reduction of the resource consumption by a Source Generator when running inside an IDE. Today’s topic is a basic one – the configuration of a Roslyn Source Generator.

Enable/Disable the Counter

Since part 4 of this series the Source Generator renders a counter into the output to see whether the code is regenerated or not. Although this counter is helpful for debugging purposes, still, it shouldn’t be in production-ready code.

				
					// <auto-generated />
#nullable enable

// generation counter: 4

using System.Collections.Generic;
using DemoLibrary;

namespace DemoConsoleApplication
{
   partial class ProductCategory
   {
       ...

Project-wide Configuration

Roslyn provides 2 alternatives to pass parameters to a Source Generator. One way is to use the .editorconfig, which is being use by Analyzers as well. The other option is to use MSBuild properties, which can be defined in a .csproj-file or Directory.Build.props.

I prefer the approach with MSBuild properties to change the parameters per project. The corresponding parameter name will be DemoSourceGenerator_Counter and the values to activate the feature are enable, enabled, and true. I’m using more than 1 value because I can’t remember myself which one it was to activate the feature. 🙂

To activate the feature in DemoConsoleApplication, we have to make 2 entries in .csproj-file. First, define DemoSourceGenerator_Counter in the PropertyGroup. Second, define CompilerVisibleProperty so our custom parameter is passed to the Source Generator.

We will take care of CompilerVisibleProperty later, so the developers don’t have to define this property when installing our NuGet package.

				
					<Project Sdk="Microsoft.NET.Sdk">

   <PropertyGroup>
      ...
      <DemoSourceGenerator_Counter>enable</DemoSourceGenerator_Counter>
   </PropertyGroup>

   <ItemGroup>
      <CompilerVisibleProperty Include="DemoSourceGenerator_Counter" />
   </ItemGroup>

Receive Parameters with AnalyzerConfigOptionsProvider

The configuration parameters can be received from the AnalyzerConfigOptionsProvider. The MSBuild properties are prefixed with build_property, i.e. the parameter name is build_property.DemoSourceGenerator_Counter.

				
					   public void Initialize(IncrementalGeneratorInitializationContext context) 
   { 
      var enumTypes = context.SyntaxProvider
                             ...;

 
      var options = GetGeneratorOptions(context); 

      ...
   } 
   
   protected static IncrementalValueProvider<GeneratorOptions> GetGeneratorOptions(
       IncrementalGeneratorInitializationContext context) 
   { 
      return context.AnalyzerConfigOptionsProvider
                    .Select((options, _) => 
                           { 
                              var counterEnabled = options.GlobalOptions 
                                  .TryGetValue("build_property.DemoSourceGenerator_Counter",
                                               out var counterEnabledValue)
                                  && IsFeatureEnabled(counterEnabledValue); 
 
                               return new GeneratorOptions(counterEnabled); 
                           }); 
   } 
 
   private static bool IsFeatureEnabled(string counterEnabledValue) 
   { 
      return StringComparer.OrdinalIgnoreCase.Equals("enable", counterEnabledValue) 
             || StringComparer.OrdinalIgnoreCase.Equals("enabled", counterEnabledValue) 
             || StringComparer.OrdinalIgnoreCase.Equals("true", counterEnabledValue); 
   }

The GeneratorOptions must be read-only and implement Equals and GetHashCode to prevent unnecessary re-generation of the code.

				
					namespace DemoSourceGenerator; 
 
public sealed class GeneratorOptions : IEquatable<GeneratorOptions> 
{ 
   public bool CounterEnabled { get; } 
 
   public GeneratorOptions(bool counterEnabled) 
   { 
      CounterEnabled = counterEnabled; 
   } 
 
   // Equals and GetHashCode
}

Passing Options to Code Generation

The options must be combined with the existing pipeline to receive them in GenerateCode.

				
					   public void Initialize(IncrementalGeneratorInitializationContext context) 
   { 
      var enumTypes = context.SyntaxProvider 
                             ...; 
 
      var generators = context.GetMetadataReferencesProvider() 
                              ...;
 
      var options = GetGeneratorOptions(context); 
 
      context.RegisterSourceOutput(enumTypes.Combine(generators).Combine(options), GenerateCode); 
   }
   
   private static void GenerateCode( 
      SourceProductionContext context, 
      ((DemoEnumInfo, ImmutableArray<ICodeGenerator>), GeneratorOptions)  args) 
   { 
      var ((enumInfo, generators), options) = args; 
 
      if (generators.IsDefaultOrEmpty) 
         return; 
 
      foreach (var generator in generators.Distinct()) 
      { 
         var ns = enumInfo.Namespace is null ? null : $"{enumInfo.Namespace}."; 
         var code = generator.Generate(enumInfo, options); 
 
         if (!String.IsNullOrWhiteSpace(code)) 
            context.AddSource($"{ns}{enumInfo.Name}{generator.FileHintSuffix}.g.cs", code); 
      } 
   }

The property CounterEnabled is evaluated in the code generator to determine whether to render the counter or not.

				
					public sealed class DemoCodeGenerator : ICodeGenerator 
{ 
   ...
  
   public string Generate(DemoEnumInfo enumInfo, GeneratorOptions options) 
   { 
      var ns = enumInfo.Namespace; 
      var name = enumInfo.Name; 
 
      var sb = new StringBuilder(@"// <auto-generated /> 
#nullable enable"); 
 
      if (options.CounterEnabled) 
      { 
         sb.Append($@" 
 
// generation counter: {Interlocked.Increment(ref _counter)}"); 
      } 
 
      sb.Append($@" 
 
using System.Collections.Generic; 
using DemoLibrary;

Packaging of CompilerVisibleProperty

As previously mentioned, the CompilerVisibleProperty can be provided by a NuGet package, so the developers don’t have to do that manually.

In order to do that, create a new file DemoLibrary.props in the project DemoLibrary (right besides DemoLibrary.csproj) with the following content:

				
					<Project> 
 
   <ItemGroup> 
      <CompilerVisibleProperty Include="DemoSourceGenerator_Counter" /> 
   </ItemGroup> 
 
</Project>

The DemoLibrary.props must be put into folder build in order to be included by MSBuild automatically.

				
					<Project Sdk="Microsoft.NET.Sdk">

   ...

   <ItemGroup>
      <ProjectReference Include="..\DemoSourceGenerator\DemoSourceGenerator.csproj"
                        PrivateAssets="contentfiles;build"
                        SetTargetFramework="TargetFramework=netstandard2.0" />
      <None Update="DemoLibrary.props" Pack="true" PackagePath="build" />
   </ItemGroup>

</Project>

Summary

Use MSBuild properties to pass generall, project-wide parameters and use AnalyzerConfigOptionsProvider to receive them.

Current articles, screencasts and interviews by our experts

Don’t miss any content on Angular, .NET Core, Blazor, Azure, and Kubernetes and sign up for our free monthly dev newsletter.

.NET

Roslyn Source Generators: Logging – Part 11

In previous part we lerned how to pass parameters to a Source Generator. In this article we need this knowledge to pass futher parameters to implement logging.

read article >

29.08.2023

| Pawel Gerr

.NET