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.
- Find the Symsrv.dll file in the c:\Program Files\Debugging Tools for Windows folder
- Close any copies of Visual Studio .NET or Visual Studio 2005 that you have running
- 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
