Debugging EPiServer CMS 5 R2 with Symbols

When debugging an EPiServer Web site, not all stack information will be present without symbol files, such as line numbers. This article provides a description of how to debug an EPiServer CMS 5 R2 Web site utilizing the EPiServer symbol server.

Contents

›› Introduction
›› EPiServer symbol server
›› Environment variables
›› Debug in Visual Studio 2008

Introduction

When debugging an EPiServer Web site, not all stack information will be present without symbol files, such as line numbers. It can be important to get as much information as possible when an exception has been thrown from an EPiServer binary, therefore the symbols (pdb:s) should be used for debugging purposes.
The pdb:s are created together with the binary files, though not shipped with the EPiServer CMS 5 R2 installer. Instead, EPiServer has a symbol server, where the pdb:s can be downloaded and used by a debug tool.

EPiServer symbol server

From EPiServer CMS 5 R2 (5.2.375.7) symbols will be uploaded to the symbol server for every release. When debugging an EPiServer site with that version number or higher, it will be possible to automatically download the correct symbols from the EPiServer symbol server. The symbol server URL is: http://symbols.episerver.com.

Environment variables

To be able to automatically get the pdb:s from EPiServers symbol server, a couple of environment variables must be configured. To open windows environment variables, follow these steps:

1. Go to system properties (Start, right click on myComputer, properties).
2. “Advanced” tab
3. “Environment Variables” button

_NT_EXECUTABLE_IMAGE_PATH

To download the binary files, the system variable “_NT_EXECUTABLE_IMAGE_PATH” must be set to download binaries from the EPiServer server. If there is already a system variable with that name, it must be changed through the “Edit” button. If no system variable with that name is present in the list, add a new with the “New” button. Set the “variable name” to “_NT_EXECUTABLE_IMAGE_PATH”.
The “variable value” should be set as “SRV*local_cache_path*http://symbols.episerver.com”, for example “SRV*c:\epipdb*http://symbols.episerver.com”.

_NT_SYMBOL_PATH

To download the pdb files, the system variable “_NT_SYMBOL_PATH” must be set to download symbols from the EPiServer server. If there is already a system variable with that name, it must be changed through the “Edit” button. If no system variable with that name is present in the list, add a new with the “New” button. Set the “variable name” to “_NT_SYMBOL_PATH”.
The “variable value” should be set as “SRV*local_cache_path*http://symbols.episerver.com”, for example “SRV*c:\epipdb*http://symbols.episerver.com”.

Debug in Visual Studio

To debug a site through Visual Studio with the symbols from EPiServer, the symbol server and cache path must be set in the debugging options:

1. Open up options in Visual Studio (Tools, Options, Debugging, Symbols).
2. Add a new location by clicking on the map symbol. Enter the address to the EPiServer symbol server.
3. In the textbox for “Cache symbols from symbol servers to the directory”, enter the local cache path that was specified when setting up the environment variables.
   Now, the symbol files will be downloaded to the “cache map for symbols” that has been pointed out when the code is debugged. Every time the code is debugged, the debugger will check if the symbols are in the cache folder and if not, it will be downloaded to the cache folder. Then it will load the symbols.

Control if the symbols have been downloaded

When debugging, open the modules windows in Visual Studio (Debug, Windows, Modules) that is only available when debugging. When an assembly is loaded, it will appear in the modules list, and you can see if it´s symbols have been loaded (Symbol Status). The symbol file should point to somewhere in the directory that has been pointed out before (cache map for symbols).

Comments