Command Line Debugging Revisited - Part 1: Getting started with MDbg and .NET Compact Framework Version 2 Service Pack 1

It's been a while since I last wrote about using the command line debugger (cordbg) with the .NET Compact Framework.  Quite a bit has changed in the world of .NET Compact Framework command line debugging since that time.

With the release, last year, of version 2 of the .NET Framework SDK, a new command line debugger (MDbg) became available.  MDbg is written in managed code and supports adding functionality via extension assemblies (DLLs).  At the time we released version 2, the extension which adds .NET Compact Framework support was not ready.  With the release of .NET Compact Framework version 2 service pack 1, our extension assembly (mdbgnetcf.dll) is now available.

If you followed my original command line debugger series, you may recall that there were several steps to getting a command line debugging session established with a .NET Compact Framework application in version 1.  I'm happy to say that we have made the process of getting started quite a bit easier with our MDbg extension.  I'm going to spend today's post talking about the device and run commands that are added by the mdbgnetcf extension.

Preliminary steps
Before we can get started using MDbg to debug a .NET Compact Framework application, there are a few preliminary tasks we must perform.

  1. Download and install .NET Compact Framework version 2 service pack 1
  2. Update your device to the service pack 1 release
  3. Copy the following files to the \Windows folder on the device
    • from <drive>:\Program Files\Common Files\Microsoft Shared\CoreCon\1.0\Target\wce400\<cpu>
      • edbgtl.dll
      • tcpconnectiona.dll
    • from the service pack 1 installation folder (typically <drive>:\Program Files\Microsoft.NET\SDK\CompactFramework\v2.0\WindowsCE\<version>\<cpu>
      • netcfrtl.dll
      • netcflaunch.exe
  4. Deploy your application file(s) to the device.

Steps 2 & 3 typically need to be performed only once per device.  Step 1 once per development / debugging PC.  Step 4 needs to be performed whenever the application file(s) have changed.

Getting started
Once the preliminary tasks have been performed, we can get started debugging our application using MDbg. 

  1. Run mdbg.exe
    I recommend running MDbg from either a Visual Studio 2005 Command Prompt (Start Menu\All Programs\Microsoft Visual Studio 2005\Visual Studio Tools) or a SDK Command Prompt (Start Menu\All Programs\Microsoft .NET Framework SDK v2.0).  This will ensure that MDbg.exe is on the search path.

    I also recommend running MDbg from within the folder containing both your target executable and the symbol (.pdb) file.  This allows MDbg to match the symbols to the exe and display the correct source code without any additional steps.
     

  2. Load the mdbgnetcf extension

    mdbg>load <path>\mdbgnetcf

    It is important to note that the file extension (.dll) is left off when using the load command.

    When the extension is loaded, the following message will be displayed.

    .NET Compact Framework extension loaded successfully.
     

  3. On your device, run NetCFLaunch.exe

    When NetCFLaunch starts, it will display the transport parameters (ex: 169.254.2.1 6510) required to connect to the device.  We will use the transport parameters in the next step.
     

  4. Connect to the device using the device command

    device 169.254.2.1 6510

    When the device command successfully completes, we will have a connection to the NetCFLaunch application.  The NetCFLaunch window will display "Connection SUCCEEDED".
     

  5. Run your application using the run command

    I will use the WebCrawler sample from Visual Studio 2005.

    run "\program files\webcrawler.exe"

    When the run command completes, MDbg will display the current source location (the application entry point).

    STOP: Breakpoint Hit288: {[p#:0, t#:0] mdbg>

    Note: The breakpoint to which MDbg refers is the initial, temporary breakpoint managed by the debugger.  This breakpoint is inserted and cleared when MDbg connects to the application.

You can now debug your application using the other MDbg commands.  For a list of available commands, use the h[elp] or ? commands.

In the coming weeks, I plan on continuing this series and talking about the other commands added by the mdbgnetcf extension and show some examples of how they can be used.

Enjoy!
-- DK

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