Product version: 1.0
SymGetEx is an addition to Visual Studio 6.0, which allows Visual C++ debugger to automatically download symbols from symbol servers. With automatic symbol server support, it is easy to keep system symbols up-to-date, regardless of the number of system updates and hotfixes installed on the computer. In turn, good symbols for system DLLs help you get complete and informative call stacks when debugging your applications.
In the process of downloading symbols, SymGetEx provides detailed progress reports, which help to troubleshoot network failures and various symbol server issues. SymGetEx also allows to reduce unnecessary network traffic by maintaining the list of modules whose symbols should not be downloaded from the symbol server (exclusion list).
SymGetEx allows to enable or disable symbol server access on the fly, ensuring that the debugger uses symbol server only when it is really needed, and does not consume computing resources at other times.
Operating system: Windows NT 4.0 SP4, Windows 2000, Windows XP, Windows Server 2003.
Development tools: Visual C++ 6.0 with service pack 5 or 6.
Note: Visual C++ 6.0 debugger does not support the symbol format used by system symbols of Windows XP Service Pack 2 and Windows Server 2003 Service Pack 1. Even though SymGetEx can work on those platforms and download symbols successfully, the debugger will not be able to use the downloaded symbols. We are planning to address this issue in the next version of SymGetEx.
Note: Remote debugging scenario is not supported in this version of SymGetEx.
Note: If you will use Visual C++ debugger with SymGetEx under other user account than the one used to run SymGetEx setup, please pay attention to Step 2 below.
1. Run symgetex10.exe.
The installation wizard will collect the necessary information and install SymGetEx on your computer.
2. Run RegUser.exe.
If you are going to use SymGetEx under other user account than the one used to run SymGetEx setup, it is necessary to register SymGetEx addin manually. Login under the user account you will use to debug applications, navigate to SymGetEx installation directory and run RegUser.exe.
Also make sure that the user account has write access to the local symbol cache directory and to Visual C++ symbol directory (%windir%\symbols) (write access is necessary to store downloaded symbols for use by Visual C++ debugger).
3. Check SymGetEx configuration.
Start Visual C++ 6.0. SymGetEx toolbar will appear. Move the toolbar to another position (or dock it) if necessary. Then use Symbol Server Settings button on the toolbar to open SymGetEx Configuration dialog. Review the settings and make sure that they are correct for your system (default settings should be enough in most cases).
More information about SymGetEx Configuration dialog can be found in Configuration section of this help file.
The simplest way to configure SymGetEx is to use SymGetEx Configuration dialog. You can open this dialog using Symbol Server Settings button on the SymGetEx toolbar.
SymGetEx Configuration dialog allows to enable and disable symbol server access, specify symbol server path, and modify symbol server exclusion list. The dialog also allows to specify the locations of Visual C++ symbol directories.
When you modify configuration settings in SymGetEx Configuration dialog, the new settings are taken into use after you close the dialog with OK button.
You can use “Enable” checkbox in SymGetEx Configuration dialog to enable or disable symbol server. When symbol server is enabled, SymGetEx will try to download symbols for every module loaded by the debuggee, if symbols are not available in Visual C++ symbol directory yet. When symbol server is disabled, SymGetEx does not attempt to download symbols.
Since checking for presence of symbols in Visual C++ symbol directory and downloading symbols over the network can take some time, you can disable symbol server access to improve the startup time of your debugging sessions when you know that symbols are already up-to-date.
It is possible to enable or disable symbol server at any time, even in the middle of the debugging session.
For troubleshooting purposes, SymGetEx can display detailed progress report about the process of downloading symbols. The messages can be viewed on the Macro tab of Visual Studio’s Output window.
Progress report can be enabled or disabled using “Report progress” checkbox in SymGetEx Configuration dialog.
SymGetEx needs to know the symbol server path to be able to download symbols. You can explicitly specify the path to the proper symbol server, or you can ask SymGetEx to use the path specified in _NT_SYMBOL_PATH environment variable. Both options are available in SymGetEx configuration dialog.
If you want to configure SymGetEx to use _NT_SYMBOL_PATH environment variable, select “Use _NT_SYMBOL_PATH” option. If you want to specify the symbol server path explicitly, select “Use this path” option and enter the path in the field below.
Symbol server path format consists of the following parts:
srv*LocalCache*ServerPath
LocalCache specifies a directory on the local system (or shared directory on a network server in the LAN) that will be used as the cache for downloaded symbols. If symbols are already available in the cache, SymGetEx will not have to download symbols from the potentially slow symbol server.
ServerPath specifies the path to the actual symbol server. It can be a UNC path, or a path to HTTP server.
Here is a sample symbol server path, which will configure SymGetEx for downloading symbols from the public symbol server in Microsoft:
srv*c:\symbolcache*http://msdl.microsoft.com/download/symbols
Note: You can find detailed information about symbol server and related technologies in the documentation of Debugging Tools for Windows.
If you use WinDbg or Visual Studio.NET on the same computer with Visual C++ 6.0 and SymGetEx, you can configure them to share the same symbol cache directory.
Warning: Do not use Visual C++ symbol directory as the symbol cache. Differences between Visual C++ 6.0 and symbol server directory structures will prevent Visual C++ debugger from loading symbols correctly.
Visual C++ can search for symbols in several predefined locations. By default, it uses only %windir%\symbols directory, but additional symbol directories can be specified in Registry.
After SymGetEx downloaded symbols for a module, it copies the symbol files into a directory on Visual C++ symbol path, so that Visual C++ debugger can find and load them.
"Main symbol directory" setting in SymGetEx Configuration dialog tells SymGetEx where the main symbol directory of Visual C++ is located.
Note: This setting is used only to inform SymGetEx about location of this directory. It cannot change the location where Visual C++ debugger will look for symbols.
"Additional PDB directories" setting allows to specify additional directories where Visual C++ debugger will look for symbols (multiple directories can be specified, separated by semicolons). Unlike the previous setting, this setting does affect the path where Visual C++ debugger will search for symbols. It is recommended that this setting always contain at least two directories:
%windir%\symbols\exe;%windir%\symbols\dll
(%windir% should be replaced with the real Windows directory path)
If the setting does not contain these directories, Visual C++ debugger will not be able to find symbols when running on Windows XP.
You can use Defaults button to configure Visual C++ symbol path settings to reasonable default values.
Some executables and DLLs do not have their symbols on the public symbol server (for example, 3rd party components). By default, SymGetEx does not know about it, and will still try to connect to the symbol server and download symbols for these modules. To prevent SymGetEx from spending unnecessary time looking for nonexistent symbols, you can add these modules to the symbol server exclusion list. The list can be configured with the help of Exclusions dialog, which can be opened using Exclusions… button in SymGetEx Configuration dialog.
If you want to add a module to the symbol server exclusion list, enter the module name into the dialog, on a separate line. Note that it is recommended to use * wildcard instead of the module’s file extension, to account for all possible kinds of symbol files.
Example:
shlwapi.* someotherfile.*
If Visual C++ debugger cannot load symbols for a module, enable progress reporting in SymGetEx Configuration dialog and check the report in Macro tab of Visual Studio’s Output window. For every module, the window will contain detailed progress report, which is often enough to find the reason of the problem.
Note that temporary network problems may prevent SymGetEx from downloading symbols correctly. If SymGetEx reported that it could not download symbols for a module, it makes sense to try again after some period of time.
If you do not see SymGetEx toolbar (or Symbol Server Settings button), make sure that SymGetEx addin is registered with Visual Studio. Open Visual Studio’s Customize dialog (Tools | Customize… | Add-ins and Macro Files) and make sure that SymGetEx IDE AddIn is loaded and enabled. If SymGetEx IDE AddIn is not in the list of addins, refer to Step 2 in Installation section of this help file.
Open Configuration dialog and make sure that "Additional PDB directories" setting is not empty and contains at least the following entries:
%windir%\symbols\exe;%windir%\symbols\dll
%windir% should be replaced with the real Windows directory path. You should add other entries (for other file extensions, e.g. "ocx") to be able to download symbols for files with those file extensions. You can press "Defaults" button to set the reasonable default values.
Visual C++ 6.0 debugger does not support the symbol format used by system symbols of Windows XP Service Pack 2 and Windows Server 2003 Service Pack 1. Even though SymGetEx can work on those platforms and download symbols successfully, the debugger will not be able to use the downloaded symbols. We are planning to address this issue in the next version of SymGetEx.
If you have noticed misbehaviour of Visual Studio IDE and suspect that SymGetEx could cause it, disable SymGetEx (uncheck “SymGetEx IDE AddIn” in Tools | Customize… | Add-ins and Macro Files), restart Visual Studio and try to reproduce the problem. If the problem cannot be reproduced when SymGetEx is disabled, a bug in SymGetEx should be suspected.
If you have found a problem in SymGetEx, please report it to developers. You can send the bug report to writesupport@debuginfo.com (the real email address does not contain the word "write" - spam prevention).
Please provide the following information in the bug report:
If you want to register SymGetEx, please see registration information at http://www.debuginfo.com/tools/symgetex.html#register
More information about SymGetEx:
http://www.debuginfo.com/tools/symgetex.html
SymGetEx support:
writesupport@debuginfo.com
(the real email address does not contain the word "write" - spam prevention)
DebugInfo.com:
http://www.debuginfo.com/
Debugging tools:
http://www.debuginfo.com/tools.html
Articles about debugging:
http://www.debuginfo.com/articles.html
Debugging services:
http://www.debuginfo.com/contact.html
© Oleg Starodumov, 2005