Debug Source Generators in JetBrains Rider

Khalid Abuhakmeh

Read this post in other languages:

• 简体中文

Source generators help developers rethink approaches that use reflection and instead use compile-time techniques to avoid the runtime expense of costly operations. The .NET team introduced the community to Source Generators on April 29th, 2020, as a new approach to inspect a project’s code using Roslyn and generate new C# source files that add new functionality to a project.

While many see the upside to source generators, using them or building your own can be complex. Luckily, with JetBrains Rider, you view any source generator output, debug the resulting artifacts, and debug the source generators themselves. 

All these techniques help reduce the confusion about the source generation process and help you build your confidence as a developer. So let’s look at these features.

To follow along, you can clone my sample source generator project.

Source Generator Files

When referencing a source generator, it’s essential to understand that the source generation occurs during the compilation process of the referencing project. You can see this in JetBrains Rider’s UI by navigating to your project’s Dependencies node.

You’ll notice a group for each source generator referenced in your project and all C# source-generated artifacts.

Debugging Source-Generated Files

While seeing the source-generated output can be helpful in debugging issues, you may also want to step into the code itself. Using Rider’s debugger, you can investigate any source-generated code anytime. You can start by adding a breakpoint to your code that uses the generated artifact and then use the shortcut Step Into to step through the code.

If you’re familiar with the JetBrains Rider debugger, you can now perform all the debugging tasks you’d typically do.

Debugging a Source Generator

We recently added support for debugging source generators themselves. Source generators need a context to run against, and that context is a project. You’ll need a launchSettings.json file in your source generator project to start debugging your source generator. Typically this file is found under the Properties folder. The file will look something like the following:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "Generators": {
      "commandName": "DebugRoslynComponent",
      "targetProject": "../ConsoleTest/ConsoleTest.csproj"
    }
  }
}

The critical part of this launch setting is the commandName value of DebugRoslynComponent. You’ll also need to specify a project to use as the context for the source generation process. Once you’ve completed this file, you can use the Play button in the gutter to start the debugging process.

From here, you can set breakpoints in your source generator code and see the context used during source generation.

As an important note, JetBrains Rider 2023.1 currently supports version 4.3.1 of Microsoft.CodeAnalysis.Csharp and Microsoft.Net.Compilers.Toolset packages for debugging. Therefore, if you are experiencing an inability to debug your source generators, you may have a newer version of these packages.

Snapshot Testing

If you’re looking for a different approach to testing source generators, check out Andrew Lock’s post on using Verify for snapshot testing. 

Snapshot testing is running a test and comparing the output to a known output. Of course, there’s more to it than that, but comparing test output with a known and verified previous output is an excellent way to ensure a source generator emits the code you expect it to emit.

Also, check out Matthias Koch’s plugin for Verify, which brings Verify into JetBrains Rider as a first-class experience.

JetBrains Rider 2023.2 Roslyn Templates

While many folks might already have a collection of custom source generators, we also know a large portion of the .NET community is still dipping their toes into the topic of source generators. Therefore, in JetBrains Rider 2023.2, we will ship two new JetBrains templates: Roslyn Analyzers and Source Generators.

Using these templates, you can start with a preconfigured solution that provides a core project, a sample target project for running your source generators against, and a unit testing project for quickly asserting your work. We aim to ease the onboarding process of writing source generators and get you to get you more value upfront.

If you already have a collection of source generator projects, these templates are a good reference for tweaking your solutions to work with JetBrains Rider’s debugging experience.

Conclusion

Working with source generators is already complex enough for many folks, so having tooling support to understand better what a generator is doing is priceless. If you’ve found jumping into source generators intimidating, I hope this quick overview of tooling support gives you the courage to try it.

As always, we hope you enjoyed this post, and please leave your comments below.

_{image credit: Denny Müller}

Subscribe to a monthly digest curated from the .NET Tools blog:

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!