Understanding symbol files and Visual Studio’s symbol settings
January 5, 2015
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, and 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
Autom
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. If you are using TFS read about how to add symbol and source archiving support).
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.
It'd be good if explanatory posts like this were tied to error messages in the VS UI.
Brilliant insight into debugging symbol. Very informative indeed.
Really useful tips, I'm going to try the "Only specified modules" style of working… but why isn't there an option in Visual Studio to "Automatically load symbols for modules in which I set a breakpoint"?
Thank you. very useful.
Thanks for the useful post. I agree you should link to this in Visual Studio.
"This means that Visual Studio will always be able to find the symbols for your projects." – except when it can't. I've had instances where a clean build of a project in Visual Studio still results in a debug session with no symbols loaded.
"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." – it's nice to hear someone from MS actually acknowledge that the fact that its a problem that the application is still 32-bit. For years we've been told how it's not really a problem, we're just misunderstanding, despite the fact that scores of customers complain about VS crashing or slowing to a crawl as it chews up all of its memory. After VS 2015 is released it's time to make 64-bit a priority already.
That was helpfull thank you 🙂
@Tim: re: "why isn't there an option in Visual Studio to 'Automatically load symbols for modules in which I set a breakpoint'?" In order to know what module the breakpoint is set in symbols have to be loaded. So the debugger does not know what module that source file compiled into until it has loaded symbols for that module. So it has to load symbols for modules until it finds a match. For example, you have File1.cs that compiles into Library1.dll that is loaded by Program1.exe. If you set a breakpoint in File1.cs the debugger does not know if File1.cs compiles into Program1.cs, or Library1.dll, etc. until it has loaded symbols for Library1.dll. So it has to load symbols for modules that are loaded into the process until it finds a match for your breakpoint. That said, we have been doing some thinking about future ways to optimize symbol loading to try to be a bit smarter about this.
@MgSm88: re "I've had instances where a clean build of a project in Visual Studio still results in a debug session with no symbols loaded". Next time you hit this, please reach out to us by contacting vsdbgfb@microsoft.com, we'd like to understand what the problem is so we can address it.
@Andrew B Hall – MSFT Ron is right imho. These kinds of posts are awesome to learn about this stuff. It has always bothered me that these valuable and good written information are pretty much lost with time. They should make their way into MSDN or something, but definitely on a blog like this. I wonder how many treasures are hidden in all MSDN (dead) blogs.
Thanks for this very detailed, useful explaination. 🙂
Great explanation, Andrew!
But, unfortunatelly, didn't achieve my problem.
I got a "Binary was not built with debug information." in a module from my Project.
Can you help me with that?
@Roberto, reach out to me on our debugger feedback email vsdbgfb@microsoft.com, it'll be faster to iterate through mail than a blog post. For starters what type of project is it (e.g. C# .exe, C++ .dll, etc.). And can you include a screenshot of what you are seeing?
I am getting this error in VS2015. I tried your method but still i am facing issue.
Now i am getting exception message in output:
Exception thrown: 'System.CannotUnloadAppDomainException' in Unknown Module.
@suman george What issue specifically are you facing? Is it that when the exception is being thrown the location says it is in an "Unknown Module", so you would like to load symbols for that "Unknown Module" so you can diagnose your exception? Or are you getting an error message for something else? Re: "I tried your method but still I am facing issue" – Which method do you mean?
This MSDN article has some information about CannotUnloadAppDomainException in it's remarks if that is helpful to you in the meantime (msdn.microsoft.com/…/system.appdomain.unload(v=vs.110).aspx)
if .exe binary info(checksum, size) related pdb file is changed by winlisence themida, how should i load .pdb for debugging.
i tried to load pdb symblols of original exe binary file!! but I failed!
plz… give me an answer!
additionally,
when I analyze .dmp files. it happens…..
—————————————————————————————————————————
if .exe binary info(checksum, size) related pdb file into dmp files is changed by winlisence themida,
how should i load .pdb for debugging.
i tried to load pdb symblols of original exe binary file!! but I failed!
plz… give me an answer!
@YoungSeok_Neowiz: If you look in the modules window, right click on the .exe, and choose "Symbol Load Information…" what reason does it say that it isn't loading the .pdb file?
To. Andrew B Hall – MSFT
i describe my situation!
1. I build hello.exe with hello.pdb using VS2013
2. I obfuscated hello.exe with themida packer
3. I made a hello.dmp file of obfuscated hello.exe
4. Now, I have only hello.dmp and hello.pdb files
5. so i tried to debugge hello.dmp with hello.pdb…
6. i failured to load hello.pdb because hello.pdb is not matched with hello.dmp
7. code obfuscation made hello.exe difference code!
8. but i want to debugge hello.dmp
9. first, i have to load hello.pdb forced.
is there any option or good way like windbg -i option ?
@Neo_SEOK: Visual Studio does not offer the ability to use mismatched symbols. You will need to use WinDbg in the case where you don't have matching symbols for the binary that was loaded in memory when the dump was taken
Same problem…
Great explanation, Andrew!
But, unfortunatelly, didn't achieve my problem.
I got a "Binary was not built with debug information." in a module from my Project.
Can you help me with that?
@Rose, can you follow up with me at vsdbgfb@microsoft.com. Can you start by including information about what type of project you are debugging, and if you look in the modules window where the module you are getting the message for is being loaded from?
This is very misleading: I clicked on it 'cause it had label 'Code'. However, there's no code here. It's a step by step tutorial. Why not letting people download the final solution???
@Dmitry, could you please clarify what you mean by "why not let people download the final code?" This blog post is about how to configure and trouble shoot symbol settings it is not a walkthrough for creating or editing any particular code sample
By the way, when you have a lot of PDBs loaded, and you have a lot of threads, and you have the Threads window open, single stepping in the debugger is INCREDIBLY slow. Closing the Threads windows solves the issue. This is still an issue in the very latest VS 2017 with all patches. This needs to either be fixed or clearly documented. I will be Reporting this as a bug in feedback.