Shared Source CLI 2.0 (SSCLI) Debugging Overview

Contents

• Introduction
• Symbolic Information Files
• Debugging and the CLI Logging Infrastructure
• JIT-attach Debugging
• Debugging Managed Code Running in the SSCLI
• Debugging Unmanaged SSCLI Code on Windows
  • Other Debuggers On Windows
  • Attaching to a Running Process on Windows
• Debugging Managed Code From Unmanaged SSCLI Code

Introduction

The debugging tool you should use with the Shared Source CLI (SSCLI) 2.0 depends on your debugging scenario. Debugging scenarios can be placed into three main categories:

• Debugging unmanaged code.
• Debugging managed code running under the SSCLI.
• Debugging managed code from unmanaged SSCLI code.

The following table shows the debugging combinations and options.

Debugging managed code in the .NET Framework and the SSCLI is supported by the debugging services APIs. 

Please note, there have been changes to the way the SOS debugger extensions are installed and run in SSCLI 2.0. Please read sos.html for further instructions. 

Symbolic Information Files

When the SSCLI is built on Windows two kinds of symbolic debugging information files are generated. Unmanaged code that is built will generate .pdb files and managed code that is built will generate .ildb files. The Windows debugger tools utilize the .pdb file format. The Runtime Debugger (cordbg.exe on Windows) utilizes the SSCLI .ildb symbolic file format.  The SOS debugger extension does not use either format of debug information.

You can convert between the .ildb format and .pdb format using the ildbconv conversion tool.  You can take an assembly built using the SSCLI tools, convert the corresponding .ildb file to .pdb format, and then debug that assembly running under the .NET Framework using Visual Studio 2005.

Debugging and the CLI Logging Infrastructure

Several environment variables are used by the CLI logging infrastructure which can be very useful when debugging the SSCLI or managed code running in the SSCLI.

The following table describes some of the most useful environment variables for use with debugging.

All the options above result in assert dialogs from the SSCLI on Windows except COMPlusJitHalt.  The assert dialog will have content such as the following when set COMPlus_BreakOnEELoad=1 is set:

---------------------------
clix.exe Assert Failure (PID 2448, Thread 620/26c)        
---------------------------
!"Start Loading EE!"

c:\sscli20\clr\src\vm\ceemain.cpp, Line: 467

Abort - Kill program
Retry - Debug
Ignore - Keep running


Image:
c:\sscli20\build\binaries.x86chk.rotor\clix.exe

---------------------------
Abort   Retry   Ignore   
---------------------------

Select the "Retry" button to return back into the debugger at the point where the assert was thrown.  The Retry button will cause a rethrow of the assertion and debuggers will normally catch the second assert and halt.

The COMPlus_JitHalt setting will not cause an assert dialog and will simply halt the debugger immediately after JIT-compiling code for the specified method and just before running that code.

See logging.html for more details on the CLI logging infrastructure.

JIT-Attach Debugging

Just-in-time (JIT)-attach debugging is the term used to describe attaching a debugger to an executable image that has thrown an unhandled exception. JIT-attach debugging of unmanaged code is occurring on Windows when you see a message box that invites you to:

• Click OK to terminate the program.
• Click Cancel to debug the program.

If you click Cancel, a debugger starts and attaches to the process. The Windows setting for JIT-attach debugging of unmanaged code is set in the registry at: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\Current Version\AeDebug.

JIT-attach debugging has no direct relationship to JIT compilation other than sharing the "JIT" acronym.

In SSCLI builds, the default behavior for JIT-attach debugging of managed code that throws unhandled exceptions is as follows:

• On Windows, attachment to the Runtime Debugger is enabled by default.

To change the default settings set the COMPlus_DbgJITDebugLaunchSetting environment variable to:

• 0 to enable JIT-attach debugging.
• 1 to disable JIT-attach debugging.

The environment variable will be used it if is present; otherwise the defaults will remain in effect. 

On Windows the JIT-attach debugging behavior when it is enabled is as follows:

1. An unhandled exception occurs in managed code.
2. A message box appears.  For example:

---------------------------
clix.exe - Common Language Runtime Debugging Services
---------------------------
Application has generated an exception that could not be handled. 

Process id=0x108c (4236), Thread id=0x1100 (4352). 

Click OK to terminate the application. 
Click CANCEL to debug the application.
---------------------------
OK Cancel 
---------------------------

3. If you click Cancel, then the Runtime Debugger is started.
4. If you click OK, another message box appears.  For example:

---------------------------
clix.exe - Application Error
---------------------------
The exception Integer division by zero.

 (0xc0000094) occurred in the application at location 0x02ca2d94.


Click on OK to terminate the program
Click on CANCEL to debug the program
---------------------------
OK   Cancel   
---------------------------

This second message box is the unmanaged code JIT-attach debugging message.

5. If you click Cancel, the currently registered unmanaged code debugger in the registry starts.
6. If you click OK, no debugger starts. Unhandled exception output should be sent to the console.

With JIT-attach debugging disabled, the first message box does not appear and you have the option of debugging using the unmanaged code debugger only.

Now when an unhandled exception occurs in managed code the Runtime Debugger starts to debug the managed application.

Debugging Managed Code Running in the SSCLI

The SSCLI supports a subset of the debugging functionality supported by the .NET Framework. In particular, the SSCLI does not have sufficient debugging support to use Microsoft® Visual Studio 2005 development to debug managed code running in the SSCLI. The Microsoft CLR Debugger included with the .NET Framework SDK is a variant of the Visual Studio .NET debugger and cannot be used to debug managed code running under the SSCLI.

The only option available for debugging managed code running under the SSCLI is to use the Runtime Debugger (cordbg.exe on Windows, cordbg on UNIX system-based platforms).

For more information see the Runtime Debugger documentation.

You must be in an SSCLI console window in which an SSCLI environment has been successfully built to ensure that you have a working copy of the SSCLI version of cordbg.exe in your path. If you are not in a SSCLI console window, you might inadvertently be running the .NET Framework SDK implementation of cordbg.exe which will not launch the application being debugged under the SSCLI. You do not have to explicitly use the clix SSCLI application launching utility when you debug with the Runtime Debugger because the SSCLI implementation of the debugger always starts all applications using the clix launcher. 

If the code that you develop under the SSCLI will also run under the .NET Framework, then you might choose to use the Visual Studio 2005 debugger on Windows and debug the code running under the .NET Framework. You can then run the debugged application under the SSCLI by using the clix launcher.

Debugging Unmanaged SSCLI Code on Windows

On Windows the preferred debugger for debugging unmanaged code is the Visual Studio 2005 debugger. To debug the SSCLI execution environment use the following steps:

1. Set up an SSCLI console window using the env.bat batch file with either the checked or the fastchecked option. Because the fastchecked build option will introduce optimizations into the built code that might cause binary code to be moved relative to its source position in the source file, it is preferable to use the checked option.
2. Build the SSCLI.
3. From the SSCLI console window, execute the following command:

devenv /debugexe %_NTTREE%\clix.exe <path_to_managed_application>

The debugger will start up and create a default project for the clix launcher which is the application being debugged. 

4. To start the debugger, choose Step Into from the Debug menu, (usually mapped to the F11 key). This will start debugging the clix application launcher.
5. After the debugger starts, you might be asked to save the solution file. Save the file in the default location.

   You should now see the breakpoint waiting on the second line below (the opening brace) in palstartup.h:

int __cdecl main(int argc, char **argv) 
{ 
    struct _mainargs mainargs;
 

    #ifdef _MSC_VER 
    if (PAL_Initialize(0, NULL)) { 
	return 1; 
    } 
    #else if (PAL_Initialize(argc, argv)) { 
	return 1; 
    } 
    #endif

6. You can now open other source files and set breakpoints or simply step through the SSCLI initialization process using the Step Into and Step Over commands.

Other Debuggers On Windows

There are times when Windows platform debuggers can be a useful substitute for the Visual Studio 2005 debugger. You should install the latest debugging tools for Windows from the Microsoft Debugging Tools Web page to make sure that you have the most up-to-date version of the debuggers on your computer. You can then use the NTSD, CDB, or WinDbg Windows debuggers to debug the unmanaged code portions of the SSCLI. The process of debugging is very similar to using the Visual Studio 2005 debugger.

1. Set up an SSCLI console window using the env.bat batch file with either the checked or the fastchecked option. Because the fastchecked build option will introduce optimizations into the built code that might cause binary code to be moved relative to its source position in the source file, it is preferable to use the checked option.
2. Build the SSCLI.
3. From the SSCLI console window, execute the following command:

   windbg clix.exe <path_to_managed_application>

4. You will initially stop at a breakpoint in the ntdll.dll module.  At this point you can bring in source-level debugging information by using the .lines command.  You should then set a breakpoint.  For example, to get the same location as you would by default with the Visual Studio 2005 debugger and to step at the source level, use the commands shown in boldin the following example. Some intermediate output has been removed for clarity.

ntdll!DbgBreakPoint: 
7c901230 cc int 3 
0:000> .lines Line number information will be loaded
0:000> bp clix!main
0:000> g

You can also use any other debugger that can debug Windows to debug the unmanaged code in the SSCLI. You will need to ensure that these alternate debuggers can utilize the .PDB symbolic information format if you want to debug at the source line level.

Attaching to a Running Process on Windows

In some cases an error will cause an assertion in the SSCLI or the SSCLI to stop responding. It is useful to be able to attach to the running process to diagnose the source of the problem.

To attach to a running process using Visual Studio 2005, start the development environment and select the Attach To Process from the Debug menu to display a list of running processes and attach to clix.exe. In this mode of using the development environment it is useful to be able to view the list of Miscellaneous files that are source files opened in the course of debugging.  To view these files, on the Tools menu choose Options and select the Documents node under Environment.  Select the item named Show Miscellaneous files in Solution Explorer.

To attach to a running process using the Windows debugging tools, start NTSD or CDB with the -pn option and specify clix.exe as the process name.

Debugging Managed Code From Unmanaged SSCLI Code

Although you cannot use the Visual Studio 2005 debugger to debug both the unmanaged SSCLI implementation code and managed code running under the SSCLI, you can use the SOS debugger extension to obtain additional functionality to support navigating through the managed code that is currently being executed.

For more information on the SOS debugging extension usage under Windows see the sos.html document .

Copyright (c) 2006 Microsoft Corporation. All rights reserved.