Microsoft .NET Compact Framework Debugging

.NET Compact Framework 1.0

Jim Wilson
JW Hedgehog, Inc.

March 2003


General Debugging Guidelines
Working with the Emulator
Device Debugging


The Microsoft .NET Compact Framework is fully integrated into Visual Studio .NET 2003 and supports all of the same debugging features available to other Visual Studio .NET application types. Debugging applications running on a separate device or within the emulator does, however, introduce some special considerations. The following are some suggestions for getting the most out of the .NET Compact Framework debugging experience.

Note   For a complete discussion of general Visual Studio .NET debugging see Visual Studio Debugging.

General Debugging Guidelines

The following are general guidelines for getting the best results when debugging .NET Compact Framework applications with Visual Studio .NET.

Take advantage of the Emulator

By running directly on the desktop, the emulator tends to provide a more convenient debugging experience than managing a separate device. Applications running in the emulator start more quickly and are more responsive to interaction with the debugger. For applications requiring data entry, the emulator provides full support for the desktop computer's keyboard, substantially reducing data entry time as compared to stylus-based input. As shown in Figure 1, the Device toolbar's Deployment Target drop-down can be used to control whether the application is run in the emulator or on the device.

Figure 1. Deployment target options on Device toolbar

Enable application shutdown during Pocket PC application debugging

Applications developed for smart devices are often designed to remain running indefinitely. In fact, the official Designed for Windows for Pocket PC Logo Guidelines mandate that applications not allow the user to exit, but instead implement a feature called "smart minimize," which moves the application into the background, ready to be reactivated when the user is not using it. .NET CF applications implement "smart minimize" by default.

Having the application remain running is great for end-users, but for developers, debugging requires that applications be frequently started and stopped. If the application does not provide an exit feature, the only way to stop it is to abruptly kill the process, using either the Pocket PC's "Running Programs" screen or the "Stop Debugging" menu item in Visual Studio .NET. Debugging is often more convenient if the application can be easily exited. Disabling "smart minimize" provides this ability.

"Smart minimize" is controlled in the Compact Framework by the MinimizeBox property of the application's main form, and can be disabled by setting the property to false. Doing this causes the application to display an "OK" button on the top of the form, which, when clicked, exits the application. Since this behavior is desired only when debugging, the MinimizeBox property can be set to false using conditional compilation and the DEBUG constant. The best place to do this is in the main form's constructor just after the call to InitializeComponent(), as shown in the following C# code.

public Form1()
   this.MinimizeBox = false;

The following is the same code for VB .NET

Public Sub New()
#If DEBUG Then
   Me.MinimizeBox = False
#End If
End Sub

With this code, the application will display an "OK" button, which exits the application when compiled for debug, but will continue to support "smart minimize" when compiled for release.

Use the Debug.Write methods cautiously

For desktop applications, calling Debug.Write displays the desired content in the Visual Studio .NET Output window. This is not the case for the .NET Compact Framework, as the Compact Framework debugging environment does not support the necessary connectivity.

Due to differences between the Windows CE and Pocket PC operating systems, the results of calling Debug.Write are different for each.

On Windows CE, any information passed to Debug.Write is displayed in a temporary console window on the device. The console window automatically opens on the fist call to Debug.Write and closes immediately after the application exits. The console window can be kept open by placing a breakpoint at the end of the application's Main() function, to prevent the application from completely exiting.

The Pocket PC operating system has no support for console windows. As a result, information passed to Debug.Write is not displayed anywhere. For this reason, calling Debug.Write from Pocket PC applications is not recommended.

Note   The described behavior applies to all Debug.Write related methods including Debug.WriteIf, Debug.WriteLine and Debug.WriteLineIf.

Working with the Emulator

For the most part, debugging applications, whether on the emulator or the device, is no different. There are, however, a few special considerations for getting the most out of the emulator debugging experience.

Insure that network connectivity is available

Visual Studio .NET uses TCP for portions of its communication with the emulator, and therefore requires that the desktop computer be plugged into a network or have a loopback adapter installed. Without a network connection or loopback adapter, Visual Studio .NET will raise an error when attempting to launch the application.

Note   See Installing the Microsoft Loopback Adapter for more information on using the loopback adapter.

Configure the Emulator to Match the Deployment Device

For the emulator to provide an accurate debugging experience, it must be configured as much like the deployment device as possible. Many features of the emulator can be configured, including the display, memory and device ports.

To modify the emulator configuration, open the "Options" dialog by choosing "Options" under the "Tools" menu in Visual Studio .NET. On the "Options" dialog, expand the "Device Tools" folder and select "Devices". The dialog should now appear similar to Figure 2.

Figure 2. "Devices" section of the Options dialog

From the "Options" dialog, verify that "Pocket PC 2002 Emulator" is highlighted in the "Devices:" list and click the "Configure" button on the bottom right. The "Configure Emulator Settings" dialog shown in Figure 3 should now be open.

Figure 3. Configure Emulator Settings dialog

Each of the three tabs in the "Configure Emulator Settings" dialog affects the emulator as follows.

Tab Description
Display Change the size and color resolution of the emulator screen.

The "Screen Width" and "Screen Height" values should never be changed when debugging Pocket PC applications, as Pocket PC devices always have a screen resolution of 240x320.

System Change the available memory for the emulator.

The memory value must be between 32mb and 256mb. This value should normally be set to the minimum memory configuration the application is expected to support.

Hardware Map the desktop computer's serial and parallel ports to the emulator.

These options make the associated desktop hardware appear to be directly connected to the emulator, which is useful for debugging applications that need to communicate with external hardware such as a printer or global positioning system.

Changes made to the emulator configuration may not immediately take affect. By default, the emulator restores the state from when it was last run. For the emulator to apply the configuration changes, it must have been shut off without saving state. This is done by choosing "Shut Down…" from the emulator's "Emulator" menu; then choosing "Turn off Emulator" on the "Shut Down" dialog. The new configuration settings are applied the next time the emulator is started.

Caution   Use the "Turn off Emulator" feature carefully. The emulator will lose all data including files and programs.

Leave the emulator open between debugging sessions

The debugger starts much more quickly if the emulator is already running. If the emulator is not running, the debugger must pause during emulator initialization, resulting in a sometimes-notable delay. Leaving the emulator open has no impact on the rest of the development process and reduces debugger startup time.

The emulator startup delay on some slower machines will occasionally cause VS .NET to time out, resulting in an error. If the error should occur, re-starting the debugger after the emulator is opened will normally correct the problem.

To avoid the problem altogether, manually start the emulator prior to launching the debugger. To manually start the emulator:

  • Insure that the project's target deployment device is set to the emulator.
  • Choose "Connect to Device…" from the VS .NET "Tools" menu.

Avoid using the emulator from a Terminal Services client

The emulator supports only a single running instance per computer. This is true even when accessed through Terminal Services. As a result, multiple clients attempting to use the emulator through Terminal Services will all be attempting to use the same emulator instance, and will receive unpredictable results.

For best results, run Visual Studio .NET and the emulator directly on the local desktop.

Device Debugging

When debugging applications running on a Pocket PC or Windows CE device, the most important consideration is connectivity.

Use the fastest connectivity available

Visual Studio .NET supports several different device connectivity options, including serial port, USB and network. The communications speed of each is substantially different, with serial port being the slowest and network being the fastest. Always connect the device with the fastest connectivity available, as the communications speed of the connection has a direct impact on the responsiveness of the Visual Studio .NET debugger.

Insure that ActiveSync is connected before launching the debugger

Visual Studio .NET communicates with the device through ActiveSync. If there are any problems with ActiveSync, the debugger will not function correctly. When using a serial port or USB, the ActiveSync connection is established automatically. Network connections require additional setup.

Note   It is not necessary to create an ActiveSync partnership when connecting the device.

When using a network, the connection must be manually established. ActiveSync normally disconnects manually-established connections once the synchronization process is complete, so this feature needs to be disabled to allow the connection to remain through the entire debugging process.

To disable "disconnect when complete":

  • On the device, open ActiveSync.
  • Choose "Options" from the "Tools" menu.
  • Select the "Schedule" tab.
  • Uncheck the box labeled "When manually synchronizing, disconnect when complete".
  • Tap "OK".

Once this is disabled, a network connection can be established by starting ActiveSync on the device and tapping "Sync". The connection will remain until "Stop" is tapped.


The .NET Compact Framework's integration into Visual Studio .NET brings the power of desktop debugging to smart devices. Although smart devices require considerations not faced by other application types, following these few simple suggestions will help you avoid many common mistakes and get the most out of the debugging experience.