Debugging aspects

Adding breakpoints to templates and compile-time code

Debugging the compile-time logic of an aspect or fabric can be challenging because the compiler doesn't execute your source code, but a heavily transformed version where T# templates have been compiled into plain C#. This transformed code is stored under the obj/<Configuration>/<TargetFramework>/metalama directory.

Warning

You cannot set compile-time breakpoints in your source code files if the project references the Metalama.Framework package and the MetalamaEnabled MSBuild property is not set to False. Visual Studio breakpoints placed in source files will not be hit because the debugger sees only the transformed code, not the original source.

You must add break statements directly in your source code and remember to remove them after the debugging session. Once the debugger stops at a break statement and you step through the code, you'll be viewing the transformed code. At that point, you can set breakpoints in that transformed code file for the remainder of your debugging session.

To add break statements:

In a non-template compile-time method such as BuildAspect, invoke Debugger.Break().
In a template compile-time method, invoke meta.DebugBreak().

Debugging aspect tests

The most convenient way to debug an aspect is to create an aspect test as described in Snapshot testing of aspects. This allows you to isolate the scenario you want to debug.

To debug an aspect test:

Insert breakpoints directly into your source code as described above.
Use the Debug command of the unit test runner.

Debugging the compiler process

To debug compile-time logic:

Insert breakpoints directly into your source code as described above.
Execute the compiler with these options:
- -p:MetalamaDebugCompiler=True to cause the compiler to display the JIT debugger dialog, allowing you to attach a debugger to the compiler process.
- -p:MetalamaConcurrentBuildEnabled=False to force Metalama to run in a single thread, saving you from the chaos of multi-threaded debugging.
- Optionally, --disable-build-servers to disable the use of reusable server MSBuild and Metalama.Compiler processes.
- Optionally, --no-dependencies to avoid rebuilding referenced projects.

Example:

Full screen

dotnet build MyProject.csproj -p:MetalamaDebugCompiler=True -p:MetalamaConcurrentBuildEnabled=False

Debugging the IDE process

To attach a debugger to the design-time compiler process, follow these steps:

Install the Metalama Command Line Tool as instructed in Installing the Metalama command line tool.
Execute the command below:
Full screen
```
metalama config edit diagnostics
```
In the diagnostics.json file, modify the debugging/processes section and enable debugging for the appropriate process. If you're using Visual Studio, this process is named RoslynCodeAnalysisService.
Full screen
```
{

    // ...

    "debugger": {
        "processes": {
             "Rider": false,
              "RoslynCodeAnalysisService": true
        }
    }

    // ...

}
```
Insert breakpoints directly into your source code as described above.
Restart your IDE.