ktsu.SourceGeneratorToolkit

Introduction

Features

Installation

Package Manager Console

Install-Package ktsu.SourceGeneratorToolkit
Install-Package ktsu.SourceGeneratorToolkit.Testing

.NET CLI

dotnet add package ktsu.SourceGeneratorToolkit
dotnet add package ktsu.SourceGeneratorToolkit.Testing

Package Reference

<PackageReference Include="ktsu.SourceGeneratorToolkit" Version="x.y.z" />
<PackageReference Include="ktsu.SourceGeneratorToolkit.Testing" Version="x.y.z" />

Usage Examples

Basic Example

using ktsu.SourceGeneratorToolkit;
using Microsoft.CodeAnalysis;

public static class MyDiagnostics
{
	public const string Copyright = "Copyright (c) 2026 contributors";

	public static DiagnosticCatalog Catalog { get; } = new("MYG", "MyProject.Generators");

	public static DiagnosticDescriptor MetadataFileMissing { get; } = Catalog.Warning(
		1,
		"A metadata file is missing from the compilation",
		"Metadata file '{0}' was not supplied as an AdditionalFile.");

	public static DiagnosticDescriptor MetadataParseFailed { get; } = Catalog.Error(
		2,
		"A metadata file could not be parsed",
		"Metadata file '{0}' could not be parsed: {1}");
}

using ktsu.CodeBlocker;
using ktsu.CodeBlocker.Templates;
using ktsu.SourceGeneratorToolkit;
using Microsoft.CodeAnalysis;

[Generator]
public sealed class ThingsGenerator() : GeneratorBase<ThingsMetadata>("things.json")
{
	protected override DiagnosticCatalog Diagnostics => MyDiagnostics.Catalog;

	protected override DiagnosticDescriptor MetadataFileMissing => MyDiagnostics.MetadataFileMissing;

	protected override DiagnosticDescriptor MetadataParseFailed => MyDiagnostics.MetadataParseFailed;

	protected override void Generate(SourceProductionContext context, ThingsMetadata metadata, CodeBlocker codeBlocker)
	{
		SourceFileTemplate file = new() { Namespace = "Generated" };

		foreach (ThingDefinition thing in metadata.Things)
		{
			file.Classes.Add(new ClassTemplate
			{
				Name = thing.Name,
				Kind = TypeKind.Class,
				Keywords = { CSharpKeywords.Public },
			});
		}

		WriteSourceFile(codeBlocker, file, MyDiagnostics.Copyright);
		context.AddSource("Things.g.cs", codeBlocker.ToString());
	}
}

<ItemGroup>
  <AdditionalFiles Include="Metadata/*.json" />
</ItemGroup>

Reading More Than One Metadata File

[Generator]
public sealed class PairGenerator : GeneratorBase
{
	protected override IReadOnlyList<string> MetadataFileNames => ["things.json", "units.json"];

	protected override DiagnosticCatalog Diagnostics => MyDiagnostics.Catalog;

	protected override DiagnosticDescriptor MetadataFileMissing => MyDiagnostics.MetadataFileMissing;

	protected override DiagnosticDescriptor MetadataParseFailed => MyDiagnostics.MetadataParseFailed;

	protected override void Generate(SourceProductionContext context, MetadataSet metadata)
	{
		ThingsMetadata? things = metadata["things.json"]?.Deserialize<ThingsMetadata>(context, MetadataParseFailed);
		UnitsMetadata? units = metadata["units.json"]?.Deserialize<UnitsMetadata>(context, MetadataParseFailed);

		if (things is null || units is null)
		{
			return;
		}

		using CodeBlocker codeBlocker = CreateCodeBlocker();
		// ... emit
	}
}

Pointing a Diagnostic at the Metadata

MetadataFile? file = metadata["things.json"];

// The first occurrence — right when the name is a typo, which occurs once.
context.ReportAt(MyDiagnostics.UnknownReference, file?.FindLocation(name), name);

// Anchored on the surrounding entry — right when the name is spelled correctly in dozens of
// places and only wrong in this one.
context.ReportAt(MyDiagnostics.UnknownReference, file?.FindLocation(thing.Name, name), name);

Testing a Generator

using ktsu.SourceGeneratorToolkit.Testing;

GeneratorHarness harness = new(Path.Combine(AppContext.BaseDirectory, "Metadata"));

// Runs against every metadata file in the directory, the way MSBuild supplies them.
GeneratorRunResult result = harness.Run(new ThingsGenerator());
Assert.AreEqual(0, result.Diagnostics.Length);

// Substitute one file's contents to exercise a failure path.
GeneratorRunResult malformed = harness.Run(
	new ThingsGenerator(),
	new Dictionary<string, string> { ["things.json"] = "{ not json" });

// Withhold a file to assert what the generator says when it is missing.
GeneratorRunResult partial = harness.RunWithOnly(new PairGenerator(), "things.json");

// Assert it behaves like an incremental generator, not just that its output is right.
Assert.IsTrue(harness.ReusesCachedOutputOnRerun(new ThingsGenerator()));

<ProjectReference Include="..\MyProject.Generators\MyProject.Generators.csproj"
                  AdditionalProperties="BundleAnalyzerDependencies=false" />

API Reference

GeneratorBase

Properties

Methods

GeneratorBase<T>

Properties

Methods

MetadataFile

Properties

Methods

MetadataSet

Properties

DiagnosticCatalog

Properties

Methods

DiagnosticReporting

Methods

CSharpKeywords

Fields

GeneratorHarness

Properties

Methods

Contributing

License