Articles Advanced topics Debugging plugins and game assemblies Debugging plugins with Visual Studio

Debugging plugins with Visual Studio Tools for Unity

Note

This method is suitable for debugging only BepInEx plugins! To debug preloader plugins, refer to dnSpy debug guide.

While debugging with dnSpy is rather simple, you might want to debug directly in Visual Studio while developing. It is possible to debug your plugins with the help of Visual Studio Tools for Unity (VSTU).

Installing required tools

First, you have to convert the game to debug build. To do that, refer to dnSpy guide on converting the game to pure debug build.

Next, install VSTU. You can do so in Visual Studio 2019 via Visual Studio Installer. You can find the component behind Individual components tab: Select "Visual Studio Tools for Unity" component in Visual Studio installer

Note

Rider provides a similar Unity extension which allows for the same debugging functionality.

Compiling your project

Next, compile your BepInEx plugin with a Debug build. Make sure that you generate a .pdb file!

Place your BepInEx plugin into BepInEx\plugins like you normally would but with the .pdb file accompanying it:

Install your plugin with the .pdb file normally into BepInEx/plugins folder.

Converting .pdb to .mdb

Since Unity uses Mono as its .NET runtime, it cannot directly read .pdb files which contains the required debug symbols. Instead, it uses .mdb files for the similar task. Because of this, .pdb file needs to be converted.

Grab pdb2mdb converter (for example, from NuGet or from GitHub). Put the executable in some folder except not into BepInEx plugin folder.

Finally, simply drag-and-drop your plugin DLL file, which will generate the required debug symbols:

Convert pdb to mdb by dragging and dropping the plugin DLL onto the pdb2mdb.exe

After this, you can optionally delete the .pdb file as it is not needed.

Starting debugging

Finally, put breakpoints in Visual Studio however you want and start the game. When the game has started, you're ready to start debugging.

In Visual Studio, select Debug > Attach Unity Debugger:

Select Debug > Attach Unity Debugger in Visual Studio

In the opened dialog, select the game executable and press OK:

Select the game process from the opened dialog

Note

If there is no processes in the list, try pressing Refresh -- it might be that the game hasn't loaded in yet.
It is also may be because you didn't follow the dnSpy debug build conversion guide properly. In that case, please repeat the steps in that setup guide making sure you use correct Unity version and bitness.

If you've done everything correctly, the debugging session starts and your breakpoints can be hit:

An example of a breakpoint being hit