Boilerplate Guide to Creating a Source Generator - Part 1

• Download source code - 69.2 KB

Introduction

Looking to create a Source Generator and don't know where to begin? This 6-part article will provide you with a boilerplate guide that will guide you through the process.

Table of Contents

• Part 1 - Introduction / Preparing to Create a Source Generator
• Part 2 - Create the Basic Infrastructure of the Source Generator
• Part 3 - Implementing the Source Generator
• Part 4 - Debugging the Source Generator
• Part 5 - Packaging the Source Generator into a NuGet Package
• Part 6 - How to use the NuGet Source Generator

Background on Source Generators

A Source Generator is code that runs during the compilation of your code and produces code to add additional or changes functionality. This is done by examining your code 

• namespaces
• classes
• properties / fields
• attributes
• interfaces
• etc.

The output of the Source Generator that I will be discussing is to build Object Mothers.  Martin Fowler describes them as "An object mother is a kind of class used in testing to help create example objects that you use for testing.".  Another article will discuss why you would want them and how to use them.

Tutorial Overview

This tutorial is laid out with folders which are labeled in order of importance and what will be discussed. Each step is then built upon by the next, so it would be wise to step through each one the first time through this tutorial.

Each folder has an additional Readme.md file that discusses in greater detail the purpose of the step. Additionally, you can use a tool like WinMerge to diff the folders in order to see the important changes.

The source code in each step should be examined to fully understand what is being done.

Requirements

The majority of this tutorial will apply to either Visual Studio or VS Code. However, I'm not a VS Code guy so you may have to do some research on your own as to how to proceed.

The two areas that may be a problem are:

• Tooling in general - In a minute, you will see an option you will need for Visual Studio. VS Code may have a similar requirement.
• Step 4 - Debugging - This may only be available in Visual Studio.

These are the minimum requirements given the implementation, using method ForAttributeWithMetadataName, that I will be showing.

After upgrading Visual Studio to at least 17.3, you will have to add an additional feature through the installer. Individual Components -> Compilers, build tools, and runtimes -> .NET Compiler Platform SDK.

Preparing to Create a Source Generator

Produce a Working Version of the Final Product

Working backwards is the easiest way to create a generated object.
Doing so will help you to:

• Identify sections that need to be repeated
• Parts that need to be replaced dynamically
• Verify the final product is valid for what you need

Create a Throw-a-way Application

Create a simple console application that lays things out in the general format that you would like.
This will include:

• A "Run" method which will be useful for testing (Program.cs)
• Classes to hold the information that you need to produce the final product (Models folder)
• A class to house all the methods and string interpolations to create the final product (FileGenerator.cs)

At this point in time, FileGenerator contains stub methods that return placeholder data.

When creating your own generator, add as much or as little as you would like. I prefer to make meaningful changes by the method in Step 3 - Implementation.

This code will be used during Step 3 - Implementation, so make sure it compiles and is capable of returning output in a string format.

Run the Application

Make sure that the application runs and returns something in the general form that you need.

History

• 18^th January, 2024: Initial version
• 20^th January, 2024: Added background section on Source Generators