Debug Symbols Management

When you start serious debugging of your VB .NET applications, and especially when you have to support multiple versions of your software, you'll find life much easier if you have a good debug symbols management process.

When you look in the Call Stack window, any methods for which debug symbols aren't available are shown in gray. The Modules window tells you the modules of your application for which the debugger was unable to locate debug symbols. If this happens and you know where a specific module's symbols can be found, try right-clicking the module and specifying the path by using the Reload Symbols menu item.

Symbols for Your Applications

You should always keep matching binaries, source, and symbol files under tight source control for every production and test version of your application. Of course, you normally won't distribute either the source or symbol files to your end user, but you need them available in case you have to reproduce a problem that occurs with just the version of the application that your pesky end user is running. It's then a relatively simple matter to use Visual Studio's remote debugging facilities to hop onto the end user 's machine while still keeping the source and symbol files on your own machine. See Chapter 15 for more details on exactly how to do this.

Symbols for Windows

Every version of Windows comes with its own set of debug symbols. You can find the debug symbols for the various Windows operating systems on the Microsoft Web site at http://www.microsoft.com/ddk/debugging/symbols.asp. You should place these files in a folder on a path where the Visual Studio debugger has access to them ”by convention, this folder is normally C:\Windows\Symbols\Dll. Be careful after patching or service-packing your Windows installation, or even updating a Microsoft application, as you may need to download a new set of symbol files. If this happens, you'll see an error message that says "No matching symbolic information found."

Unfortunately , these Windows symbols are of limited use when debugging VB .NET code, as most of the calls are done into managed code rather than native Windows code.

Symbols for the Framework SDK

There are also some limited .NET Framework debug symbols installed as part of the .NET Framework. For version 1.0 of the .NET Framework, you can find these symbols in a folder called

 C:\Program Files \Microsoft .NET\FrameworkSDK\symbols 

For version 1.1 of the .NET Framework, you can find the same symbols in a folder called

 C:\Program Files \Microsoft Visual Studio .NET 2003\SDK\v1.1\symbols 

To allow the Visual Studio debugger to locate these symbols, you should add the appropriate path to your solution's Common Properties ’ Debug Symbol Files page. An alternative is to copy each debug symbol file to the folder containing its corresponding framework binary.

Unfortunately, at the time of this writing, Microsoft doesn't release debug symbols for most of the interesting binaries, such as mscorlib.dll and system.dll. This situation may have changed by the time that you read this book, as Microsoft is known to be working on this project.

Because even the Framework binaries for which symbols are available are retail builds, you won't gain much information just by having the debug symbols available. If you recall from Chapter 3, a typical release build turns off the JIT tracking attribute, without which the symbols aren't nearly so useful. Fortunately, you can use the same trick described in the previous section on debugging production applications. You need to create an .ini file for each of the appropriate framework binaries (for instance, one called mscoree.dll.ini), and place it in the same folder as the binary. This.ini file would contain

 [.NET Framework Debugging Control] GenerateTrackingInfo=1 AllowOptimize=0 

This should allow the debugger to load the debug symbols and at least give you access to the assembly's complete call stack.

Symbol Server

Keeping track of all of the binaries and symbols needed to debug every version of your applications can turn into a full-time job. So Microsoft has come up with a solution that shows promise, even though unfortunately it doesn't yet work with the managed world.

A symbol server is designed to store all of the debug symbols for a public build in a single known location. Then all that's needed is a debugger smart enough to know where to find the symbol server and which versions of the stored files should be used.

To set up a symbol server, you need the symbol server binaries, a symbol server location, and a symbol server store. You can retrieve the binaries by downloading the Debugging Tools for Windows package (sometimes called WinDbg ) from http://www.microsoft.com/ddk/debugging. After installing the package, you need to place the symbol server binaries SYMSRV.DLL and SYMSTORE.DLL somewhere where they can be found and used by the Visual Studio debugger.

Then you need to specify the symbol server where the debug symbols are stored. For the Windows symbols, this is http://msdl.microsoft.com/download/symbols. For your own symbols, this would be any local or network folder that you care to specify.

Next , you need to designate a symbol store where you want to store the debug symbols once they've been downloaded from the symbol server. This symbol store might be simply a folder on your local machine if you're the only developer on the team. Alternatively, a bigger team should find a network folder that everybody on the team can access. The only caveat is that everybody on the team should have both read and write rights to this folder.

Finally, you need to tell the Visual Studio debugger where the symbol store and symbol server are located. With this information, it can download the correct version of the debug symbols from the symbol server to the symbol store and then use them during debugging sessions. To do this, use the Control Panel System applet to create an environment variable called _NT_SYMBOL_PATH and place the following value in it (where c:/localstore is replaced by the location of your symbol store):

 SRV*c:/localstore*http://msdl.microsoft.com/download/symbols 

Now when the Visual Studio IDE is next loaded and the debugger starts, it should locate the appropriate debug symbols on the symbol server and download them to the symbol store where it can use them. This is a once-only operation unless, of course, the binary versions change and the revised symbols therefore need to be downloaded.

Unfortunately, you should remember that this currently only works with Win32-native code, not with managed code. Also, at the time of this writing, this is an undocumented procedure and might well change with the next release of Visual Studio and the .NET Framework.