Debugging .NET Compact Framework applications using the .NET SDK command line debugger (cordbg.exe) - Part I

I've gotten a number of requests for instructions on how to use the .NET SDK's command line debugger (cordbg.exe) to debug NetCF applications. While you would think this should be pretty straight forward, there are a number of hoops to jump through.

I intend this posting to be the first in a series on using cordbg with the .NET Compact Framework. If there are any specific questions folks would like answered, please leave me comment(s) either here or on the followup posts.

The first thing you must do to enable cordbg debugging is to do at least one F5 deploy, to the target device, with Visual Studio .NET 2003. This will provision the device (deploy transport files, install NetCF, etc) and enable debugging. Go ahead and stop the debugging session once the application launches. Your device is now provisioned.

NOTE: You will need to do the above once for each device you wish to debug.

Now that your device is ready, you can debug any NetCF application using cordbg. The steps below will get you started.

1. Locate your executable on the device
If you used Visual Studio to deploy your application, the default location will be "\Program Files\<appname>\<appname>.exe"

2. Launch your application for debugging.
There are a number of ways you can do this. I've listed my favorites below:
a. Use Visual Studio.
i. Click the Project|Properties menu item
ii. Under Configuration Properties|Debugging, add //i to the "Command Line Arguments" field
You can optionally add a port number between 3000 and 3031 like so "//i3003"
iii. Use Ctrl+F5 to launch your application without debugging
b. Use the "hidden" prompt on the PocketPC
i. From the Start screen, hold the action button (the large one) while clicking on the clock
ii. Release the action button and lift the stylus
If you get this right, you will see a menu containing "Run"
iii. Click the Run option in the popup menu
iv. Enter the path to your executable and include the //i[port] command line option
If your application lives in a folder with a space in the name, be sure to enclose the full path to the application in quotes as shown in the example below:
"\program files\quicktestcf\quicktestcf.exe" //i
On your device, you will see the spinning "busy" cursor, indicating that your application is waiting for you to connect.

3. Launch the "Visual Studio .NET 2003 Command Prompt"
Typically this is located in Microsoft Visual Studio .NET 2003|Visual Studio .NET Tools" on your start menu

4. Change your folder to the location containing your application's executable and symbol (pdb) files
This is required if you would like to perform source level debugging. If you omit this step, you will see IL code initially.

5. Launch cordbg.exe
You should get something that looks like this:
Microsoft (R) Common Language Runtime Test Debugger Shell Version 1.1.4322.573
Copyright (C) Microsoft Corporation 1998-2002. All rights reserved.

(cordbg)

6. Enable embeddedclr (NetCF) debugging
mode embeddedclr 1

7. Connect to the debuggee
connect <ipaddress> <port> -a
If you connected your device via ActiveSync, <ipaddress> should be "localhost".
If you did not specify a port number on your application command line (in the //i argument), <port> should be 3000

At this point, you should be connected and ready to debug. My quicktestcf example shows me the following:
Microsoft (R) Common Language Runtime Test Debugger Shell Version 1.1.4322.573
Copyright (C) Microsoft Corporation 1998-2002. All rights reserved.

(cordbg) conn localhost 3000 -a
Process -1920910570/0x8d813b16 created.
Warning: couldn't load symbols for <path>\mscorlib.dll
Warning: couldn't load symbols for <path>\System.Drawing.dll
Warning: couldn't load symbols for <path>\System.dll
Warning: couldn't load symbols for <path>\System.Windows.Forms.dll
[thread 0x41ea4] Thread created.

067: Application.Run(new Form1());
(cordbg)

Please note that not all of cordbg's commands are available when debugging NetCF applications. The most common commands which are not on the supported list are: attach (attach to a running process), run (launch process and attach), setip (set instruction pointer).

Enjoy!
-- DK

Disclaimer:
This posting is provided "AS IS" with no warranties, and confers no rights.