Debugging OpenCatapult in Visual Studio by using "Attach to Process"

In many tutorials, we often show how to do various things in OpenCatapult directly via console and Visual Studio Code. For Visual Studio users, it sometimes makes them feel uncomfortable, especially when it comes to debugging the code. Some people think that OpenCatapult is not Visual Studio friendly.

Don’t get us wrong, we do love Visual Studio. In fact, most of the core developers of OpenCatapult are Visual Studio users. The reason why we often demo OpenCatapult with the command line and VS Code is just that we want to emphasize that OpenCatapult is a cross-platform application which can be run (and develop) easily in Windows, Linux, and Mac environment. If we get more feedback from you that we also need to show on how to do things via Visual Studio, of course, we’d be happy to do that.

As a starter, I want to show you a trick on how to attach the process of running OpenCatapult components so you can set breakpoints and debug them in Visual Studio.

If you are following the “Getting Started” steps from the docs, you will know that the easiest way to run all components in your local machine is by executing the “build-all.ps1” script. By default, it will publish all components by using the “Release” configuration. However, if you want to debug them in Visual Studio, you need to publish the components by using the “Debug” configuration. It can be done by adding “-configuration” argument when executing the build script:

.\builds\build-all.ps1 -configuration Debug

The argument can also be included in the individual component build scripts:

.\builds\build-api.ps1 -configuration Debug
.\builds\build-cli.ps1 -configuration Debug
.\builds\build-engine.ps1 -configuration Debug

After executing the script, the API instance has already started, and the CLI and Engine commands are ready to be executed. In order to use Visual Studio to debug them, you need to know the process ID (PID) of each component.

For API, it’s easy because the PID is automatically displayed in the console.

For CLI or Engine, you need to include --debug option to the command, e.g:

dotnet occli.dll config get --debug

The console will show the PID of the running instance, and pause the process until you press ENTER:

Take note of the PID, open Visual Studio, and build the project in Debug configuration. You can now use the “Attach to Process” feature as usual:


Set breakpoints in any line you want in the code, and press ENTER to continue the process in the console:


Congratulations! You are debugging OpenCatapult in Visual Studio now.


We can also modify the main project properties, and go to the Debug section. We can then specify the application argument there. For example, we can run the engine start command this way:

Save the csproj, and we can directly debug the application using the Start Debugging button (or F5 in keyboard).

The cons though, the console app will immediately closes once the process has ended.