Symbol / PDB files in the Visual Studio debugger (original) (raw)

Specify symbol (.pdb) and source files in the Visual Studio debugger (C#, C++, Visual Basic, F#)

Program database (.pdb) files, also called symbol files, map identifiers and statements in your project's source code to corresponding identifiers and instructions in compiled apps. These mapping files link the debugger to your source code, which enables debugging.

When you build a project from the Visual Studio IDE with the standard Debug build configuration, the compiler creates the appropriate symbol files. This article describes how to manage symbol files in the IDE, for example:

For a detailed explanation of symbol files, see the following:

How symbol files work

The .pdb file holds debugging and project state information that allows incremental linking of a Debug configuration of your app. The Visual Studio debugger uses .pdb files to determine two key pieces of information while debugging:

Symbol files also show the location of the source files, and optionally, the server to retrieve them from.

The debugger only loads .pdb files that exactly match the .pdb files created when an app was built (that is, the original .pdb files or copies). This exact duplication is necessary because the layout of apps can change even if the code itself has not changed. For more information, see Why does Visual Studio require debugger symbol files to exactly match the binary files that they were built with?

Tip

To debug code outside your project source code, such as Windows code or third-party code your project calls, you must specify the location of the external code's .pdb files (and optionally, the source files), which must exactly match the builds in your app.

Where the debugger looks for symbols

When you debug a project in the Visual Studio IDE, the debugger automatically loads symbol files that it can find by default.

Note

When debugging managed code on a remote device, all symbol files must be located either on the local machine, or in a location specified in the debugger options.

The debugger searches for symbol files in the following locations:

  1. The project folder.
  2. The location that is specified inside the DLL or the executable (.exe) file.
    By default, if you have built a DLL or an .exe file on your computer, the linker places the full path and filename of the associated .pdb file in the DLL or .exe file. The debugger checks to see if the symbol file exists in that location.
  3. The same folder as the DLL or .exe file.
  4. Any locations specified in the debugger options for symbol files. To add and enable symbol locations, see Configure symbol locations and loading options.
    • Any local symbol cache folder.
    • Specified network, internet, or local symbol servers and locations, such as the Microsoft Symbol Servers if selected. Visual Studio can download debugging symbol files from symbol servers that implement the symsrv protocol. Visual Studio Team Foundation Server and the Debugging Tools for Windows are two tools that can use symbol servers.
      Symbol servers you might use include:
      Public Microsoft Symbol Servers: To debug a crash that occurs during a call to a system DLL or to a third-party library, you often need system .pdb files. System .pdb files contain symbols for Windows DLLs, .exe files, and device drivers. You can get symbols for Windows operating systems, MDAC, IIS, ISA, and .NET from the public Microsoft Symbol Servers.
      Symbol servers on an internal network or on your local machine: Your team or company can create symbol servers for your own products, and as a cache for symbols from external sources. You might have a symbol server on your own machine.
      Third-party symbol servers: Third-party providers of Windows applications and libraries can provide access to symbol server on the internet.

Warning

If you use a symbol server other than the public Microsoft Symbol Servers, make sure that the symbol server and its path are trustworthy. Because symbol files can contain arbitrary executable code, you can be exposed to security threats.

Configure location of symbol files and loading options

The debugger checks various locations for symbols by default. See Where the debugger looks for symbols.

On the Tools > Options > Debugging > Symbols page, you can:

To specify symbol locations and loading options:

Note

These options were updated in Visual Studio 2022 Version 17.12 Preview 1.

  1. In Visual Studio, open Tools > Options > Debugging > Symbols (or Debug > Options > Symbols).
  2. Under Symbol file (.pdb) locations,
    • To use the Microsoft Symbol Servers or NuGet.org Symbol Server, select the checkbox.
    • To add a new symbol server location,
      1. Select the + symbol in the toolbar.
      2. Type the URL (http), network share, or local path of the symbol server or symbol location in the text field. Statement completion helps you find the correct format.

Tools - Options - Debugging - Symbols page
Tools - Options - Debugging - Symbols page
Note
Only the specified folder is searched. You must add entries for any subfolders that you want to search.

  1. (Optional) To improve symbol loading performance, under Cache symbols in this directory, type a local folder path that symbol servers can copy symbols to.

Note

Do not place the local symbol cache in a protected folder, like C:\Windows or a subfolder. Use a read-write folder instead.

Note

If you have the _NT_SYMBOL_PATH environment variable set, it overrides the value set under Cache symbols in this directory.

  1. Specify the modules that you want the debugger to load from the Symbol file (.pdb) locations when it starts.
    • Select Automatically choose what module symbols to search for (recommended) to allow Visual Studio to decide what symbols to search for and load. By default, Visual Studio automatically loads symbols that were built by your opened solution, and loads any additional symbols that are needed to perform common debugging operations. This reduces the number of files that must be searched for and loaded by Visual Studio, which improves debugger performance. You can force additional symbols to load by clicking theSpecify module filters link.
    • Select Search for all module symbols unless excluded to force Visual Studio to load all symbols in your debugged process. This is not recommended because it may slow down your debugging experience. If you select this option, you can force Visual Studio to ignore certain symbols by clicking the Specify module filterslink.
    • Select Load all modules, unless excluded (the default) to load all the symbols for all modules in the symbol file location, except modules you specifically exclude. To exclude certain modules, select Specify excluded modules, select the + icon, type the names of the modules to exclude, and select OK.
    • To load only modules you specify from the symbol file locations, select Load only specified modules. Select Specify included modules, select the + icon, type the names of the modules to include, and then select OK. The symbol files for other modules are not loaded.
  2. Select OK.

Specify module filters

Both the Automatically choose what module symbols to search for and Search for all module symbols unless excluded options allow you to have more fine control over what symbols are searched for while debugging. Choose Specify module filters to fine-tune your experience.

By default, you see the following dialog when Automatically choose what module symbols to search for is selected:

Screenshot of specifying module filters.

You can add a module to the filter by using the '+' icon. Module filters support simple wild-card matching. A '*' matches any group of characters. For example '*myproduct*' will match files such as 'myproduct.utilities.dll' and 'entrypoint.myproduct.exe', among others.

There are several additional options to further customize your experience:

If you have selected Search for all module symbols unless excluded, then the module filter dialog looks like this:

Screenshot of specifying excluded modules.

In this dialog, you can choose what modules you do not want Visual Studio to load symbols for. In this scenario, Visual Studio attempts to load symbols for every module in your debugged proces (including modules by third parties), unless you add a matching filter to exclude them. The only other way that this behavior will be modified is by your Just My Codesettings.

Other symbol options for debugging

You can select additional symbol options in Tools > Options > Debugging > General (or Debug > Options > General):

Compiler symbol options

When you build a project from the Visual Studio IDE with the standard Debug build configuration, the C++ and managed compilers create the appropriate symbol files for your code. You can also set compiler options in code.

To set the compiler options for your build configurations in Visual Studio, see Set debug and release configurations.

.NET options

Build with /debug to create a .pdb file. You can build applications with /debug:full or /debug:pdbonly. Building with /debug:full generates debuggable code. Building with /debug:pdbonly generates .pdb files, but does not generate the DebuggableAttribute that tells the JIT compiler that debug information is available. Use /debug:pdbonly if you want to generate .pdb files for a release build that you do not want to be debuggable. For more information, see /debug (C# compiler options) or /debug (Visual Basic).

C/C++ options

Web applications

Set the web.config file of your ASP.NET application to debug mode. Debug mode causes ASP.NET to generate symbols for dynamically generated files and enables the debugger to attach to the ASP.NET application. Visual Studio sets this automatically when you start to debug, if you created your project from the web projects template.

Load symbols while debugging

You can use the Modules, Call Stack, Locals, Autos, or any Watch window to load symbols or change symbol options while debugging. For more information, see Get more familiar with how the debugger attaches to your app.

Work with symbols in the Modules window

During debugging, the Modules window shows the code modules the debugger is treating as user code, or My Code, and their symbol loading status. You can also monitor symbol loading status, load symbols, and change symbol options in the Modules window.

To monitor or change symbol locations or options while debugging:

  1. To open the Modules window, while debugging, select Debug > Windows > Modules (or press Ctrl + Alt + U).
  2. In the Modules window, right-click the Symbol Status or Symbol File headers, or any module.
  3. In the context menu, select one of the following options:
Option Description
Load Symbols Appears for modules with skipped, not found, or not loaded symbols. Attempts to load symbols from locations specified on the Options > Debugging > Symbols page. If the symbol file is not found or not loaded, launches File Explorer so you can specify a new location to search.
Symbol Load Information Shows the location of a loaded symbol file, or the locations that were searched if the debugger cannot find the file.
Symbol Settings Opens the Options > Debugging > Symbols page, where you can edit and add symbol locations.
Always Load Automatically Adds the selected symbol file to the list of files that are automatically loaded by the debugger.
Decompile Source to Symbol File For .NET code, you can choose this option and then follow instructions in Generate and embed sources for an assembly.

Use the No Symbols Loaded/No Source Loaded pages

There are several ways for the debugger to break into code that does not have symbol or source files available:

When this happens, the debugger displays the No Symbols Loaded or No Source Loaded pages to help you find and load the necessary symbols or source.

No Symbols Loaded page

To use the No Symbols Loaded document page to help find and load missing symbols:

If the debugger finds the .pdb file after you execute one of the options, and can retrieve the source file using the information in the .pdb file, it displays the source. Otherwise, it displays a No Source Loaded page that describes the issue, with links to actions that might resolve the issue.

To add source file search paths to a solution:

You can specify the locations the debugger searches for source files, and exclude specific files from the search.

  1. Select the solution in Solution Explorer, and then select the Properties icon, press Alt+Enter, or right-click and select Properties.
  2. Select Debug Source Files.
    Debug source files page
  3. Under Directories containing source code, type or select source code locations to search. Use the New Line icon to add more locations, the Up and Down arrow icons to reorder them, or the X icon to delete them.
    Note
    The debugger searches only the specified directory. You must add entries for any subdirectories that you want to search.
  4. Under Do not look for these source files, type the names of source files to exclude from search.
  5. Select OK or Apply.