Article series
- Code sharing of the future
- Better experience through Roslyn Analyzers and Code Fixes
- Testing Source Generators, Roslyn Analyzers and Code Fixes
- Increasing Performance through Harnessing of the Memoization
- Adapt Code Generation Based on Project Dependencies
- Using 3rd-Party Libraries
- Using Additional Files
- High-Level API – ForAttributeWithMetadataName
- Reduction of resource consumption in IDE
- Configuration ⬅
- Logging
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. 🙂
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
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);
}
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.
