Debugging aspects

Adding breakpoints to templates and compile-time code

Debugging the compile-time logic of an aspect can be challenging due to the compiler not executing your source code, but a heavily transformed version of your code where T# templates have been compiled into plain C# code. This transformed code is stored under an unpredictable path.

Therefore, regular debugger breakpoints will not work. You must add break statements directly in your source code and remember to remove them after the debugging session is over.

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 Testing the aspect's code generation and error reporting. This allows you to perfectly isolate the scenario that 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, follow the steps below:

Insert breakpoints directly into your source code as described above.
Execute the compiler with the following 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:

```powershell
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:
```
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.
```
{

    // ...

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

    // ...

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