Click here to Skip to main content
Click here to Skip to main content
Go to top

[Debugging] - Symbols

, 21 Jun 2007
Rate this:
Please Sign up or sign in to vote.
Setting up a Microsoft Symbol Server

Introduction

This article describes how to set up and use the Microsoft Symbol Server to help you when debugging applications under Windows. Microsoft provides access to an Internet symbol server that contains symbol files for the Microsoft Windows Server 2003, Windows XP, and Windows 2000 operating systems, as well as for other Microsoft products.

When debugging applications with various Microsoft Tools, you must have symbol information available (usually stored in a PDB file).
Debug symbols provide you with a footprint of the functions that are contained in executable files and dynamic-link libraries (DLLs). In addition, when debugging an application, symbol files can help point to the function calls that led to a failure by helping you to view your application's full call stack.

Microsoft Symbol Server is built using the SymSrv technology (SymSrv.dll), which it uses to build a local symbol cache for fast, automatic symbol resolution. The Symbol Server contains symbols for all the latest service packs and security fixes.

Disk Space

To install a full set of symbols for your operating system and associated files, you will need to have at least 1GB of free space available. It should use less than this (around 550MB-750MB), but 1GB will allow the Symbol Server to automatically download new symbols as necessary.

Installation

In order to set up the Symbol Server you will need to download it from Microsoft, it is part of the Debugging Tools for Windows kit (Always download the latest version).
You can download the appropriate version from the following locations:

Configuring Symbol Server

Before you can use Symbol Server you need to configure it.
This is very easy and simply requires that you to set the _NT_SYMBOL_PATH environment variable. Once you have set this path you will find that most of the common Microsoft debugging tools will use it automatically.

This variable can be either a system or user environment variable, to set it from the desktop, right-click My Computer, and then click Properties. Select the Advanced tab and click the Environment Variables button.

You need to set this variable to the following value:

SRV*e:\localsymbols*http://msdl.microsoft.com/download/symbols 

In the example above, I have told the Symbol Server that I want my local cache to be in the e:\localsymbols folder. You will need to modify this to point to the location that you want to use.

You can see my symbol path in the following screenshot, in the list of System variables.

Using the SymChk.exe utility to download symbols

The SymChk.exe utility can be used to build your local symbol cache quickly, rather than waiting for individual symbols to be downloaded while you are debugging an application. This utility is included with the Debugging Tools for Windows package.

SymChk.exe is a command-line tool. You could add the Debugging Tools for Windows folder to your PATH environment variable for convenience so that you can access it from any command prompt.
Type the following at a command prompt, replacing the symbol path (e:\localsymbols) with the one you have chosen.

symchk /r c:\windows\system32 /s
    SRV*e:\localsymbols\*http://msdl.microsoft.com/download/symbols 

In the above example:

  • /r c:\windows\system32 - Finds all symbols for files in the System32 folder and any subfolders
  • /s SRV*e:\localsymbols\*http://msdl.microsoft.com/download/symbols - Specifies the symbol path to use for symbol resolution. In this case, e:\localsymbols is the local folder where the symbols will be copied from the symbol server

Using the Symbol Server with the Visual Studio .NET or Visual Studio 2005 debugger

This section describes how to use the Visual Studio .NET or Visual Studio 2005 debugger with a symbol server.
This allows them to automatically load symbols from the Symbol Server, assuming they are not already in your local cache.

Before you begin, ensure that you have downloaded the latest Debugging Tools for Windows and set the _NT_SYMBOL_PATH environment variable.

  1. Find the Symsrv.dll file in the c:\Program Files\Debugging Tools for Windows folder
  2. Close any copies of Visual Studio .NET or Visual Studio 2005 that you have running
  3. Copy the Symsrv.dll file to the C:\Program Files\Microsoft Visual Studio .NET\Common7\IDE or C:\Program Files\Microsoft Visual Studio 8\Common7\IDE folder

The next time that you start Visual Studio .NET or Visual Studio 2005, you can use the Symsrv.dll file to find symbol servers that you specify.

Adding your own symbols to the Symbol Server Cache

When developing and debugging your own applications, you can use the SymStore.exe utility to add your own symbols to your local symbol cache.
This will allow a debugger to retrieve the symbols it requires automatically, giving you an almost complete call stack every time you debug.

SymStore comes with the Debugging Tools for Windows, and you should refer to its documentation for full information on using SymStore.

The following sections show a simple method of adding your own symbols and then removing them from the symbol cache.

Typically your application's symbols will be stored within the executable image itself (MyApp.exe) or within a separate program database file (MyApp.pdb).

SymStore Transactions

Every call to SymStore is recorded as a transaction, of which there are two types: add and delete. You will need to understand how these transactions work before you can delete your symbols from the cache as you will need the transaction number that was assigned when you added the symbols in the first place.
This is obviously cumbersome, but as you will be mainly adding symbols to your cache it is not really a problem, you should only need to delete symbols occasionally.

When you create your symbol cache for the first time, a folder called 000admin will be created under the root folder of the cache. This folder contains one file per transaction, as well as two log files, server.txt and history.txt.

The server.txt file contains a list of all transactions that are currently on the server. The history.txt file contains a chronological history of all transactions.

Each time you add symbols, SymStore will generate a new transaction number and will create a file with this name in the 000admin folder.
This file contains a list of all the files that were added to the symbol cache during this transaction, when you delete symbols SymStore will use this file to determine which files it should delete from the cache. A new transaction number will be allocated for the delete operation too.

Adding Symbols

To add your own application's symbols to the cache you need to specify the location of the cache and the path of the folder containing the symbols.
The following example shows how to add symbols for an application called SymbolTest to our cache which is stored in d:\Symbols.
We tell SymStore to recursively search (/r) from the specified folder for the symbols.

symstore add /r /f d:\MyStuff\Code\SymbolTest\*.* /s d:\Symbols /v "Build 1"

In this example:

  • /f d:\MyStuff\Code\SymbolTest\*.* - Find all symbols for the SymbolTest application
  • /s d:\Symbols - Specifies the root folder of our local symbol cache
  • /v "Build 1" - Specifies the version of the product

The Transaction - 0000000001

When I added the symbols for SymbolTest, SymStore created a transaction file (Filename: 0000000001), containing the name of each of the symbol files that it added to the cache, the contents of which can be seen here:

"vc70.pdb\6BE4B8055F6846F5A2BB748B91DA5FD9",
            "D:\My Stuff\SymbolTest\release\vc70.pdb"
"SymbolTest.pdb\96CE1B9F227349DD948B38831D9161A11",
            "D:\My Stuff\SymbolTest\release\SymbolTest.pdb"

Note: SymStore does not support simultaneous transactions from multiple users. Microsoft recommend that a single user is assigned to be the administrator of the symbol store and they will be responsible for all add/delete transactions.

Removing Symbols

To remove the symbols from the cache you will need to know the ID of your initial Add transaction. See the previous section "Adding Symbols" to determine the transaction ID, in this example the value is 0000000001.

You need to specify the number of the transaction that you want to delete, and the path to your symbol cache on the command line to SymStore, as in the following example.

symstore del /i 0000000001 /s d:\Symbols

Conclusion

You should now have full symbolic information when debugging, including full symbols for whatever operating system you are working on. In an environment with multiple developers, they can all share the same symbol store by simply placing it on a network location accessible to all.

History

  • 1.02 (June 21, 2007) - Updated the screen shot and fixed a few spelling mistakes
  • 1.01 (May 24, 2006) - Added a section on how to add your own symbols to the Symbol Server Cache
  • 1.00 (May 17, 2006) - Initial Public Release

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Jonathan [Darka]

United Kingdom United Kingdom
No Biography provided

Comments and Discussions

 
QuestionTerms of use Pinmemberwj255214-Aug-11 21:03 
Generalvista symbols on XP Pinmemberumeca7418-Jul-07 22:23 
GeneralRe: vista symbols on XP PinmemberJonathan [Darka]18-Jul-07 23:33 
GeneralRe: vista symbols on XP Pinmemberumeca7419-Jul-07 3:06 
GeneralRe: vista symbols on XP PinmemberJonathan [Darka]19-Jul-07 3:25 
GeneralRe: vista symbols on XP [modified] PinmemberPaul Sanders (AlpineSoft)29-Oct-07 13:33 
AnswerRe: vista symbols on XP PinmemberBernd Giesen13-Dec-07 3:00 
GeneralRe: vista symbols on XP PinmemberPaul Sanders (AlpineSoft)13-Dec-07 3:06 
AnswerRe: vista symbols on XP PinmemberBernd Giesen13-Dec-07 3:39 
GeneralRe: vista symbols on XP PinmemberPaul Sanders (AlpineSoft)13-Dec-07 3:46 
Questionno matching symbolic information found PinmemberYakie28-Apr-07 12:48 
GeneralCannot load System.Drawing.pdb PinmemberArtiGujare28-Nov-06 0:29 
GeneralRe: Cannot load System.Drawing.pdb PinmemberJonathan [Darka]28-Nov-06 1:28 
QuestionQuery regading symbol server PinmemberRajakani21-Nov-06 17:43 
AnswerRe: Query regading symbol server PinmemberJonathan [Darka]27-Nov-06 0:16 
GeneralRe: Query regading symbol server PinmemberRajakani20-Dec-06 1:06 
QuestionCan I use symbols in vc6 Pinmembermatakk@126.com16-Aug-06 19:10 
AnswerRe: Can I use symbols in vc6 PinmemberDarka16-Aug-06 21:43 
QuestionRe: Can I use symbols in vc6 Pinmembermatakk@126.com21-Aug-06 20:09 
AnswerRe: Can I use symbols in vc6 PinmemberDarka31-Aug-06 0:45 
GeneralNot about this article... PinmemberJun Du26-May-06 8:01 
GeneralRe: Not about this article... PinmemberDarka26-May-06 8:29 
GeneralRe: Not about this article... [modified] PinmemberDarka26-May-06 8:30 
GeneralRe: Not about this article... [modified] PinmemberJun Du26-May-06 8:57 
GeneralRe: Not about this article... [modified] PinmemberDarka27-May-06 6:05 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web02 | 2.8.140916.1 | Last Updated 21 Jun 2007
Article Copyright 2006 by Jonathan [Darka]
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid