Debugging C# code in Unity

Using a debugger allows you to inspect your source code while your application or game is running. Unity supports debugging of C# code using the following code editors:

• Visual Studio (with the Visual Studio Tools for Unity plug-in)

• Visual Studio for Mac

• Jetbrains Rider

• Visual Studio Code

Although these code editors vary slightly in the debugger features they support, all provide basic functionality like break points, single stepping, and variable inspection.

Managed code debugging in Unity works on all platforms except WebGL. It works with both the Mono and IL2CPP scripting backends.

Configuring the code editor

Visual Studio (Windows)

The Unity Editor installer includes an option to install Visual Studio with the Visual Studio Tools for Unity plug-in. This is the recommended way to set up Visual Studio for debugging with Unity.

If Visual Studio is already installed on your computer, use its Tools > Get Tools and Features… menu to locate and install the Visual Studio Tools for Unity plug-in.

Visual Studio for Mac

The Unity Editor installer includes an option to install Visual Studio for Mac. This is the recommended way to set up Visual Studio for Mac for debugging with Unity.

If Visual Studio for Mac is already installed on your computer, use its Extension Manager to locate and install the Visual Studio Tools for Unity plug-in.

JetBrains Rider

The default installation of JetBrains Rider can debug code in Unity on Windows or Mac. Please visit the JetBrains website to install it.

VS Code

VS Code requires you to install an extension to debug code in Unity. Please follow the instructions specific to this extension to install it.

Specifying the External Script Editor in Unity

Once you’ve installed a code editor, go to Preferences > External Tools and set the External Script Editor to your chosen code editor.

Debugging in the Editor

You can debug C# code that is running in the Unity Editor while the Unity Editor is in Play Mode.

To debug in the Editor, you need to set the Editor’s Code Optimization mode to Debug Mode, then you can attach a code editor with a debugging feature.

To change the Code Optimization mode, select the Debug Button in the bottom right of the Unity Editor Status Bar.

Unity’s Code Optimization setting has two modes.

• Debug Mode, which you can use to attach external debugger software, but gives slower C# performance when you run your Project in Play Mode in the Editor.
• Release Mode, which gives faster C# performance when you run your Project in Play Mode in the Editor, but you cannot attach any external debuggers.

When you click the Debug button in the status bar, a small pop-up window opens which contains a button you can use to switch modes. It also displays information about the current mode, and describes what happens if you switch modes.

To change which mode the Unity Editor starts up in, go to Edit > Preferences > General > Code Optimization On Startup.

To control these settings via a script, use the following API: ManagedDebugger, Compilation.CompilationPipeline-codeOptimization, and Compilation.CodeOptimization.

You can also override the mode that the Editor starts up in, or turn off the debugger listen socket. To do this, use the following command line arguments when you launch the Editor:

• -releaseCodeOptimization Starts the Editor in release code optimization mode.
• -debugCodeOptimization Starts the Editor in debug code optimization mode.
• -disableManagedDebugger Starts the Editor with the debugger listen socket disabled.

Setting breakpoints and attaching to the Editor

In your external code editor, set a breakpoint in the code editor on a line of script code where the debugger should stop. For example, in Visual Studio, click on the column to the left of your code, on the line you want to stop the debugger (as shown below). A red circle appears next to the line number and the line is highlighted.

Next, attach the code editor to the Unity Editor. This option varies depending on the code editor, and is often a different option from the code editor’s normal debugging process. In Visual Studio, the option looks like this:

Some code editors may allow you to select an instance of Unity to debug. For example, in Visual Studio, the Debug > Attach Unity Debugger option exposes this capability.

When you have attached the code editor to the Unity Editor, return to the Unity Editor and enter Play Mode. When the code at the breakpoint is executed, the debugger will stop, for example:

While the code editor is at a breakpoint, you can view the contents of variables step by step. The Unity Editor will be unresponsive until you choose the continue option in the debugger, or stop debugging mode.

Debugging in the Player

To debug script code running in a Unity Player, ensure that you enable the “Development Build” and “Script Debugging” options before you build the Player (these options are located in File > Build Settings). Enable the “Wait For Managed Debugger” option to make the Player wait for a debugger to be attached before it executes any script code.

To attach the code editor to the Unity Player, select the IP address (or machine name) and port of your Player. In Visual Studio, the drop-down menu on the “Attach To Unity” option looks like this:

The Debug > Attach Unity Debugger option looks like this:

Make sure you attach the debugger to the Player, and not to the Unity Editor (if both are running). When you have attached the debugger, you can proceed with debugging normally.

Debugging on Android and iOS devices

Android

When debugging a Player running on an Android device, connect to the device via USB or TCP. For example, to connect to an Android device in Visual Studio (Windows), select Debug > Attach Unity Debugger option. A list of devices running a Player instance will appear:

In this case, the phone is connected via USB and Wi-Fi on the same network as the workstation running the Unity Editor and Visual Studio.

iOS

When debugging a Player running on an iOS device, connect to the device via TCP. For example, to connect to an iOS device in Visual Studio (Mac), select Debug > Attach Unity Debugger option. A list of devices running a Player instance will appear:

Ensure that the device only has one active network interface (Wi-Fi recommended, turn off cellular data) and that there is no firewall between the IDE and the device blocking the TCP port (port number 56000 in the above screenshot). Debugging over USB is not supported with iOS.

Troubleshooting the debugger

Most problems with the debugger occur because the code editor is unable to locate the Unity Editor or the Player. This means that it can’t attach the debugger properly. Because the debugger uses a TCP connection to the Editor or Player, connection issues are often caused by the network. Here are a few steps you can take to troubleshoot basic connection issues.

Ensure you attach the debugger to the correct Unity instance

You can attach code editor to any Unity Editor or Unity Player on the local network that has debugging enabled. When attaching the debugger to ensure that you are attaching to the correct instance. If you know the IP address or machine name of the device on which you are running the Unity Player, this helps to locate the correct instance.

Verify the network connection to the Unity instance

The code editor uses the same mechanism to locate a Unity instance to debug as the Unity Profiler uses. If the code editor cannot find the Unity instance you expect it to find, try to attach the Unity Profiler to that instance. If the Unity Profiler cannot find it either, a firewall might exist on the machine which you are running the code editor on or the machine which you are running the Unity instance on (or possibly both). If a firewall is in place, see the information about firewall settings below.

Ensure the device has only one active network interface

Many devices have multiple network interfaces. For example, a mobile phone may have both an active cellular connection and an active Wi-Fi connection. To properly connect the debugger for TCP, the IDE needs to make a network connection to the correct interface on the device. If you plan to debug via Wi-Fi, for example, make sure you put the device in airplane mode to disable all other interfaces, then enable Wi-Fi.

You can determine which IP address the Unity Player is telling the IDE to use by looking in the Player Log. Look for a part of the log like this:

Multi-casting "[IP] 10.0.1.152 [Port] 55000 [Flags] 3 [Guid] 2575380029 [EditorId] 4264788666 [Version] 1048832 [Id] iPhonePlayer(Joshs-iPhone):56000 [Debug] 1 [PackageName] iPhonePlayer" to [225.0.0.222:54997]...

This message indicates the IDE will try to use the IP address 10.0.1.152 and port 56000 to connect to the device. This IP address and port must be reachable from the computer running the IDE.

Check the firewall settings

The Unity instance communicates with the code editor via a TCP connection. On most Unity platforms, this TCP connection occurs on an arbitrarily chosen port. Normally, you should not need to know this port, as the code editor should detect it automatically. If that does not work, try to use a network analysis tool to determine which ports might be blocked either on the machine where you are running the code editor, or the machine or device where you are running the Unity instance. When you find the ports, make sure that your firewall allows access to both the port on the machine running the code editor, and the machine running the Unity instance.

Verify the managed debugging information is available

If the debugger does attach, but breakpoints don’t load, the debugger may not be able to locate the managed debugging information for the code. Managed code debugging information is stored in files named .pdb, next to the managed assembly (.dll file) on disk.

When the correct preferences and build options are enabled (see above, Unity will generate this debugging information automatically. However, Unity cannot generate this debugging information for managed plugins in the Project. It is possible to debug code from managed plugins if the associated .pdb files are next to the managed plugins in the Unity project on disk.

Prevent the device from locking

If the device you are using to debug the application has a screen lock, make sure this is disabled. Screen locks cause the debugger to disconnect, and prevent it from re-connecting. It is best to avoid locking the screen during managed code debugging. If the screen does lock, you should restart the application on the device before the debugger can connect again.

• 2018–09–06 Page published

• Managed Code Debugging added in 2018.2