Symbols are a fundamental requirement for debugging and other diagnostic tools. Fortunately in most cases when you are building and launching your application in Visual Studio you don’t have to think about symbols for your code. However the odds are that at some point in time you’ll need to change how symbols load, where the debugger looks for them, or will need to load symbols for a 3rd party component (e.g. Windows or .NET libraries). Additionally because symbols are so fundamental to debugging, we continue to make tweaks to the experience so understanding the ins and outs of how Visual Studio behaves can save you hours of frustration.
In this blog post I’ll walk you through what symbols are and how to configure Visual Studio’s symbol settings (which are used by other diagnostic tools beyond the debugger such as the performance tools and IntelliTrace), the various knobs available when debugging, and how to trouble shoot issues when Visual Studio isn’t able to find the symbol files that you need.
Symbol basics
Before we delve into the details of symbol files it’s important to briefly review what symbols are and why they are important:
- What is a symbol file? For the Microsoft compilers, these are the .pdb files that are produced as part of your build.
- What is in a symbol (.pdb) file? The exact contents of symbol files will vary from language to language and based on your compiler settings, but at a very high level they are the record of how the compiler turned your source code into machine code that the processor executes.
- Why do I need symbols? Without symbols, tools are unable to correlate the instructions executing in the application to the original source code.
- When debugging, without a symbol file you are unable to set breakpoints on a specific line of code. If symbols are not loaded you will see a hollow circle with a warning symbol while in debug mode, and if you hover the mouse over it a tooltip will tell you that the breakpoint will not be hit because no symbols have been loaded.
- Depending on what you are debugging, symbols may be required to show you a complete call stack and to inspect objects using the Watch windows, or DataTips (e.g. this is true for C++).
- Note: If you are debugging a dump file that does not contain the heap, the debugger will need access to the original binary file so it can determine the correct symbol file to load. Said another way, if you are debugging a dump with no heap information, you need both the corresponding binary and symbol file on the symbol path.
Visual Studio’s default behavior
Before we look at any of Visual Studio’s advanced settings it’s important that I stop and review the default behavior (meaning if you never touch a setting how will it behave):
- Visual Studio will try to load symbols for all binaries (referred to as “modules”) in the process when the module is loaded (and for all modules already loaded when attaching to a process).
- The exception to this is when you are debugging managed (.NET) applications, the debugger will not load symbols for any binaries considered “not your code” when “Just My Code” is enabled.
- No symbol locations are set, so it will not find symbols for any Microsoft runtime binaries
- If you right click on a module in the Call Stack or Modules windows and choose to load symbols it will automatically try to get them from the Microsoft public symbol servers assuming it can’t be found on your local machine.
- Visual Studio will always find symbols when:
- The symbol file is located in the same folder as its corresponding module. The default build output settings for Visual Studio projects will output the symbols next to the binaries. This means that Visual Studio will always be able to find the symbols for your projects.
- The symbol file is located in the same directory is was placed during compilation. The full path of the .pdb is placed into the binary at build time.
How can I tell if a symbol is loaded and if not why?
The screenshot above (with the hollow breakpoint) shows a situation where symbols didn’t load for a source file you are trying to set a breakpoint in. The other ways to determine if symbols are loaded:
- A message will appear in the call stack window saying that symbols are not loaded
- The Modules window will tell you (Debug -> Windows -> Modules):
- The status of the symbol file (loaded, skipped, or couldn’t be opened or found)
- Path the binary is loaded from
- [if loaded] where the symbol file was loaded from
- The module version
- The module’s time stamp
Additionally the debugger can tell you why it didn't load symbols and where it searched for them. To see this information, open the Modules window, right click on a module and choose “Symbol Load Information…”
This will display a box that shows you all the paths the debugger searched for the symbol file.
Some common reasons symbols aren't loaded include:
- Symbol paths don’t point to the correct location
- The symbol file is from a different version of the module than the one loaded in the process
- Visual Studio requires that the symbol file come from the exact same build as the module. It cannot load symbols that come from a different build even if the source code was identical
- [Managed only] Just My Code settings prevent the debugger from loading the symbol file
Configuring Visual Studio’s settings
Now that you understand what symbols are, how to determine if they are loaded let’s look at how you configure Visual Studio’s symbol settings. To access symbols settings, go to the “Debug” menu and choose “Options…” (“Options and Settings…” in previous versions of Visual Studio), and then select the “Symbols” sub page
You’ll notice the following settings on the page:
- Symbol file (.pdb) locations
- Symbol cache settings
- “Load all symbols” button
- Automatic symbol loading settings
Symbol file locations
If you are building and debugging your application from Visual Studio this option likely won’t apply to the symbols for your modules, but remote symbol locations (or symbol servers) are used to load symbols in situations where you need a 3rd party symbol file (e.g. one from Microsoft), or you are working in an environment where you may not have the symbols on your local machine (e.g. your application is built using a build server).
The symbol file location box tells the debugger where to look for symbol files, these can be http symbol servers (e.g. the prepopulated “Microsoft Symbol Severs” entry), network shares, or folders on your local machine
- You can add as many paths as you need.
- There is a pre-populated entry for Microsoft’s public symbol servers. If you want to load symbols for modules from Microsoft (e.g. for the runtime or operating system) check this box.
- Visual Studio will search local paths before querying network paths regardless of the order provided.
- For performance reasons, beginning in Visual Studio 2012 Update 1, Visual Studio will only search each symbol server once for a symbol file in a given Visual Studio session (until you restart Visual Studio) when automatic symbol loading is enabled. This means you don’t pay the cost of a network call every time you start debugging when the server doesn’t contain the file.
- Environment Variable: _NT_SYMBOL_PATH: If you see this in your symbol file locations it means that the environment variable _NT_SYMBOL_PATH is set. Visual Studio uses a library from Windows to load symbols, and the library will always search any locations in this environment variable for symbols; which is why you cannot uncheck the option in Visual Studio. You will need to unset the environment variable if you want Visual Studio to ignore the variable.
If you need the environment variable for other purposes, the easy way to unset the variable locally is to open a command prompt, enter “set _NT_SYMBOL_PATH=” and then launch Visual Studio from the command prompt. You system’s environment settings will remain unaffected.
Symbol cache
The symbol cache is the location on your local machine that Visual Studio places a copy of the symbols it finds on remote locations for future use. Assuming you provide a path for the symbol cache, Visual Studio will search the cache before trying to find symbols in any symbol file locations you specified above. For performance reasons we recommend specifying a symbol cache if you need symbols stored in a remote location.
Load All Symbols
This button is only enabled while Visual Studio is in debug mode, and clicking it will tell the debugger to try to load symbols for all modules in the process.
Automatic Symbol Loading
Visual Studio offers two modes of automatic symbol loading:
- Automatically load symbols for all modules unless excluded: As the title indicates, unless you add a module to the exclude list by clicking “Specify excluded modules”, Visual Studio will try to load symbols for all modules in the process. You will typically want this setting if you want symbols loaded for almost everything in the process, or if there are only a handful of very large ones you don’t want loaded for memory or debug startup performance reasons.
- Only specified modules: This setting by default will load symbols that are next to the binary on the disk, but will not try to load symbols for any other modules unless you add them to the include list by clicking “Specify modules”.
- beginning with Visual Studio 2013 Update 2, the “Specify modules” dialogs accept * for module names. So if for example you wanted to use manual loading but always load symbols for anything with “Microsoft” in the name, you could enter “*Microsoft*”
- Symbols can be manually loaded from the Call Stack window as needed. To do this, you can select an individual frame (or select all with ctrl+a), right click and choose “Load symbols”. This will load symbols for all of the modules that were in the call stack window at that time. If loading symbols improves the call stack and additional modules are found you will need to repeat this as it won’t automatically try to load symbols for modules that appear due to the previous load.
- The other option to load symbols manually when you are debugging is to locate the module in the Modules window (Debug -> Windows -> Modules), right click and choose “Load Symbols”.
Deep dive on manual symbol loading
It is worth calling out that “Only specified modules” is my and many of the Visual Studio team’s preferred setting when debugging. The reason for this is:
- When debugging very large applications you can load symbols on demand as you need them. This helps with:
- The performance of your debug session—you don’t have to wait for symbols to load for everything in the process you are debugging.
- Visual Studio’s memory—if you are debugging a very large application you may need to selectively load symbols for only the modules you are interested in. Since Visual Studio is a 32bit process, it can at most grow to 4 GB in Virtual Memory. For very large applications you can have more in symbol files than this.
- You can leave your symbol servers enabled without encountering unexpected performance hits when debugging new applications or during your first debug session in a new Visual Studio instance.
If you have a very large solution that you build entirely on your machine you will need to uncheck the “Always load symbols located next to modules” checkbox to see the benefits I mentioned above. Then you will either need load the symbols on demand while debugging, or set the ones you need to automatically load.
- If you need to hit breakpoints in those modules you will want to set them to load automatically.
- If you aren’t sure you will need the symbols ahead of time you will want to wait and load them only if you need them to inspect an object or complete the call stack.
Conclusion
Keeping track of symbols and configuring your settings correctly and for optimal performance can be quite complicated. Hopefully the above content helps you understand the settings available to you. However if you run into issues I did not cover, or have any other feedback you’d like to share, please let me know below, through Visual Studio’s Send a Smile feature, or in our MSDN forum.