Starting from version 1.2, dotPeek can function as a symbol server, that is, it can supply a debugger with the information required to debug compiled assemblies.
In contrast to traditional symbol servers, e.g. Microsoft Symbol Server, dotPeek does not store any symbol files, it generates PDB and source files for the requested assemblies and returns them back to the debugger.
If you are debugging a .NET application, chances are that you are using Microsoft Visual Studio. Therefore, we'll be using it as the debugger in this article.
Below are simple configuration steps that allow you to debug compiled assemblies in Visual Studio with the help of dotPeek symbol server:
- To start dotPeek symbol server, simply click Symbol Server on the dotPeek's action bar. When doing this for the first time, dotPeek asks you to choose the assemblies you want to generate symbol files for. Select All Assemblies (we'll see later why you may need other options and how to change your choice). That's it concerning dotPeek.
- Next, open Visual Studio options and go to Debugging | Symbols. Click Add new location and specify the following address for it: http://localhost:33417/
- In Visual Studio options, go to Debugging | General and clear the Enable Just My Code check box. If you want to step inside the .NET Framework symbols, tick the Enable .NET Framework source stepping check box.
That's all! Now you can get to the source code of any assemblies as you are stepping through them.
If dotPeek symbol server is configured to generate symbol files for all assemblies (which is the case in the example configuration above), you may be annoyed with stepping too much into system assemblies - normally, you don't need to step into that code. Well, dotPeek allows you to be flexible. The provided options allow you to choose the exact assemblies for which symbol files should be generated. To select the assemblies, choose Tools | Options in dotPeek's main menu, and then open the Symbol Server page:
Using the radio buttons, choose one of the alternative to all assemblies. The meanings of the first three options are obvious. The last one allows for the most flexibility - after selecting this option, choose only those assemblies which you need for debugging, and open them in the Assembly Explorer.
If you need symbol files elsewhere than in the debugger, dotPeek provides a command to simply generate a PDB file (together with the source files) for any .NET assembly. Usage examples of PDB files are beyond the scope of this article, however this John Robbins' post might be a good starting point on this topic.
Generating PDB with dotPeek is easy. Open the desired assemblies in the Assembly Explorer, select and right-click on them, and then choose Generate PDB in the context menu. In the dialog box that opens, specify the destination folder. Optionally, you can select some more assemblies in the reference hierarchy. After clicking Generate, PDB and source files for the selected assemblies are created in the specified destination folder.
When generating symbol files, dotPeek creates the directory structure identical to the Visual Studio symbol cache. Therefore, if you set the Visual Studio symbol cache directory as the output folder, all generated symbols will be automatically available to the Visual Studio debugger. You can get or set the cache directory in Visual Studio Options: Debugging | Symbols | Cache symbols in this directory.
If something goes wrong with dotPeek symbol server, the first thing you can do is to open the Project/PDB Generation window (Windows | Project/PDB Generation in dotPeek's menu). Here you can see all symbol server tasks as well as the results of the Generate PDB and the Generate Project commands.
If some PDB was requested from dotPeek symbol server but was not generated, you will see the corresponding entry with the error message in this window:
- Most often, problems occur when the target assembly is not found. To fix that, you can add the assembly to the Assembly Explorer. If you don't know the location of the assembly, you can learn it when Visual Studio is in the debug mode - open the Modules window (Debug | Windows | Modules) and check the Path column.
- If you are running dotPeek on 64-bit Windows, check that you are running the 64-bit version of dotPeek.
If the requested assembly doesn't appear in the Project/PDB Generation window, it means that the debugger has already found the corresponding symbol file and did not requested it from dotPeek. If the symbol file is correct and the source code is available, then everything is fine, the assembly can be debugged without dotPeek. If not, try the following:
- Delete or rename the PDB file that makes problems. You can always find the actual PDB file location, if any, for each assembly when Visual Studio is in the debug mode - open the Modules window (Debug | Windows | Modules) and check the Symbol File column.
- If the PDB file is received from another symbol server, you can either disable this server or move the dotPeek symbol server up in the list of symbol servers (Debugging | Symbols | Symbol file locations in Visual Studio options).
Another problem with debugging compiled assemblies is optimized assemblies. For optimized assemblies, some debugger functions are just not available, e.g. you would not see values of local variables, even if symbol files are correct. You can check if the assembly is optimized when Visual Studio is in the debug mode - open the Modules window (Debug | Windows | Modules) and check the Optimized column.