Export (0) Print
Expand All

Step by Step: Tips, Tricks, and Techniques for Debugging .NET Compact Framework Applications

.NET Compact Framework 1.0
 

Microsoft Corporation

June 2006

Applies to:
   Microsoft .NET Compact Framework version 2.0
   Microsoft Visual Studio 2005
   Windows Mobile 5.0 software

Summary: Use Microsoft Visual Studio 2005 to debug Microsoft .NET Compact Framework version 2.0 applications that run on Windows Mobile 5.0 Pocket PC and Smartphone emulators. This HOL will take one hour to complete. (43 printed pages)


Download MEDC06_HOL306.msi from the Microsoft Download Center.

Contents

Introduction
Lab 1: Using Thread-Specific Breakpoints
Summary
Lab 2: Debugging a Platform Invoke Call
Summary
Lab 3: Using the .NET Compact Framework Interop Log to Diagnose a Platform Invoke Call Issue
Summary
Appendix A. Terminating an Application That Is Running on a Device or Emulator
Appendix B: Setting Up Your Computer

The following applications are required to run this HOL:

Introduction

In this self-paced HOL you will use Visual Studio 2005 to debug .NET Compact Framework version 2.0 applications that run on Windows Mobile 5.0 Pocket PC and Smartphone emulators. Topics include multithreaded debugging, debugging a platform invoke call, and using the .NET Compact Framework diagnostic logs. You will also be introduced to the Remote Registry Editor, a utility for examining and modifying a mobile device's registry.

Lab 1: Using Thread-Specific Breakpoints

The objective of this lab is to provide hands-on experience debugging multithreaded applications by using thread-specific breakpoints in the Visual Studio 2005 debugger.

In this HOL, you will perform the following exercises:

  • Using a thread-specific breakpoint set by a thread's identifier
  • Naming an application thread by using the debugger
  • Using a thread-specific breakpoint set by a thread's name

Exercise 1: Using a Thread-Specific Breakpoint Set by a Thread's Identifier

It is often desirable to stop in the debugger only when a specific thread executes a line of code. This can be accomplished by creating a thread-specific breakpoint.

In this exercise, you will use the Visual Studio 2005 debugger to locate an application's worker thread and to set a breakpoint that is specific to this thread.

To open the ManyThreads project

  1. On the desktop computer, click Start | All Programs | Microsoft Visual Studio 2005 | Microsoft Visual Studio 2005.
  2. Click File | Open | Project/Solution.
  3. In the Open Project dialog box, browse to C:\Program Files\Windows Mobile Developer Samples\HOLs\MEDC06_HOL306\ManyThreads\.
  4. Select ManyThreads.sln, and then click Open.

To debug the ManyThreads application

  1. In Visual Studio 2005, click Debug | Start Debugging.
  2. In the Deploy ManyThreads dialog box, select Windows Mobile 5.0 Pocket PC Emulator, and then click Deploy.
  3. In the Windows Mobile 5.0 Pocket PC Emulator, click the left soft key (under the Go menu), as shown in Figure 1.

    Figure 1. The ManyThreads application in the Windows Mobile 5.0 Pocket PC Emulator

  4. In Visual Studio 2005, click Debug | Break All.

To locate the worker thread

  1. In Visual Studio 2005, click Debug | Windows | Threads.
  2. In the Threads pane, double-click a thread to view the current statement, as shown in Figure 2.
    Note   Because the main application thread is identified by name, there is no need to examine the "Main (UI) Thread".

    Figure 2. Selecting a thread in the Threads pane

  3. Switch to the Call Stack pane, and then examine the thread's stack to determine if it is the worker thread, as shown in Figure 3.

    You can identify the worker thread by scrolling to the last item in the call stack for a given thread and finding the thread whose Name starts with ManyThreads.exe!MEDC2006.Demo.ManyThreads.MainForm.WorkerThread().

    Note   By default, the Call Stack pane is located in the lower right corner of the Visual Studio 2005 application.

    Figure 3. The Call Stack pane

    Note   You may need to repeat Steps 2 and 3 until you identify the worker thread.
  4. Note the worker thread's identifier (ID), as shown in Figure 4.

    Figure 4. Identifying the worker thread's ID

    Note   The thread ID that you see will likely differ from the one in Figure 4.

To set a breakpoint specific to a thread by its ID

  1. In Code view in Visual Studio, right-click the first line of code in the UpdateStatus function, and click Breakpoint | Insert Breakpoint. A breakpoint is created in the code, as shown in Figure 5.

    Figure 5. Breakpoint set in the UpdateStatus method

  2. In Code view in Visual Studio, right-click the red highlighted text that indicates the new breakpoint, and then click Breakpoint | Filter.
  3. In the Breakpoint Filter dialog box, type ThreadId = the worker thread's ID, and then click OK, as shown in Figure 6.

    Click here for larger image

    Figure 6. Filtering the breakpoint by a thread's ID. Click the thumbnail for a larger image.

    Note   Because a thread's ID is volatile, each time an application is run, they are likely to change. After restarting an application, you need to update the filter conditions of your breakpoints.

To debug the thread-specific breakpoint

  1. In Visual Studio, click Debug | Continue.

    As the application runs, multiple updates appear in the Application status window without the breakpoint being encountered. When the worker thread calls UpdateStatus, Visual Studio 2005 enters debugging mode.

    The Call Stack pane displays the details for the worker thread, as shown in Figure 7.

    Figure 7. The worker thread's call stack

  2. Debug the application.

To stop debugging

  • Click Debug | Stop Debugging.

To remove all breakpoints

  1. Click Debug | Delete All Breakpoints.
  2. When prompted, "Do you want to delete all breakpoints?", click Yes.

Exercise 2: Naming an Application Thread by Using the Debugger

Names are much easier than numbers to recognize and remember. Exercise 1 used a thread's ID (number) when setting a thread-specific breakpoint. In this exercise, you will name a thread to make it easier to locate while debugging.

To restart the ManyThreads application

  1. In Visual Studio, click Debug | Start Debugging.
  2. In the Deploy ManyThreads dialog box, select Windows Mobile 5.0 Pocket PC Emulator, and then click Deploy.

To debug the ManyThreads application

  1. In the Windows Mobile 5.0 Pocket PC Emulator window, click the left soft key (under the Go menu).
  2. On the Debug menu, select Break All.

To name the application worker thread

  1. In the Threads pane, double-click a thread to view the current statement.
  2. Open the Call Stack pane, and then examine the thread's stack to determine if it is the worker thread. (For more information, see "To locate the worker thread" in Exercise 1.)
  3. In the Immediate Window pane, type Thread.CurrentThread.Name = "Worker", and then press ENTER, as shown in Figure 8.
    Note   By default, the Immediate Window pane is located in the lower right corner of the Visual Studio 2005 application.

    Figure 8. Setting the current thread's name in the Immediate Window pane

    Note   If you receive an "Unable to evaluate expression because the code is optimized or a native frame is on top of the call stack" message when you attempt to set the name of a thread, you need to step through the code until the topmost entry shown in the Call Stack is within your application's code.
    Note   A thread's name can be set only once. Any attempt to change a thread's name after it is set will encounter a System.InvalidOperationException.

Exercise 3: Using a Thread-Specific Breakpoint Set by a Thread's Name

In Exercise 2, you set the name of the worker thread. Next, you will create a breakpoint that will be encountered only when the named thread calls the method that contains the breakpoint.

To set a breakpoint specific to a named thread

  1. In Code view in Visual Studio, right-click the first line of code in the UpdateStatus method, and then click Breakpoint | Insert Breakpoint, as shown in Figure 9.

    Figure 9. Breakpoint set in the UpdateStatus method

  2. In Code view, right-click the red highlighted text that indicates the new breakpoint, and click Breakpoint | Filter.
  3. In the Breakpoint Filter dialog box, type ThreadName = "Worker", and then click OK, as shown in Figure 10.

    Click here for larger image

    Figure 10. Filtering the breakpoint by thread name. Click the thumbnail for a larger image.

To debug the thread-specific breakpoint

  1. In Visual Studio, click Debug | Continue.

    As the application runs, multiple updates appear in the Application status window without the breakpoint being encountered. When the worker thread calls UpdateStatus, Visual Studio 2005 enters debugging mode.

    The Call Stack pane displays the details for the worker thread, as shown in Figure 11.

    Figure 11. The worker thread's call stack

  2. Debug the application.

To modify the breakpoint to stop when the method is called by the main application thread

  1. In Code view in Visual Studio, right-click the breakpoint in the UpdateStatus method, and click Breakpoint | Filter.
  2. In the Breakpoint Filter dialog box, replace ThreadName = "Worker" with ThreadName = "Main (UI) Thread", and then click OK, as shown in Figure 12.

    Click here for larger image

    Figure 12. Setting the breakpoint to stop on the Main (UI) Thread. Click the thumbnail for a larger image.

    Note   In Exercise 1, it was mentioned that a thread's ID is volatile. Using thread names that are created during debugging also creates a volatile breakpoint. To allow creation of stable thread-specific breakpoints, name your application's threads in the source code, as you did for the main thread in this procedure, as shown in Figure 13.

    Figure 13. Naming the main thread in the source code

To debug the thread-specific breakpoint

  1. In Visual Studio, click Debug | Continue.

    As the application runs, it will now stop in the debugger each time the main thread calls UpdateStatus. The breakpoint is encountered more frequently because the main thread also calls UpdateStatus when it queues a thread pool work item.

    The Call Stack pane displays the details for the main thread, as shown in Figure 14.

    Click here for larger image

    Figure 14. The main thread's call stack. Click the thumbnail for a larger image.

  2. Debug the application.

To stop debugging

  • On the Debug menu, select Stop Debugging.

To remove all breakpoints

  1. In Visual Studio, click Debug | Delete All Breakpoints.
  2. When prompted, "Do you want to delete all breakpoints?", click Yes.

To close the solution

  • On the File menu, click Close Solution.

Summary

In this lab, you performed the following exercises:

  • Using a thread-specific breakpoint set by a thread's identifier
  • Naming an application thread by using the debugger
  • Using a thread-specific breakpoint set by thread's name

Using thread-specific breakpoints can be an effective way to improve debugging efficiency by limiting a breakpoint to occur in the scenario that is being debugged.

Using thread names (set in code or while debugging) can also improve debugging efficiency by making the target threads easier to locate in the Threads pane.

Lab 2: Debugging a Platform Invoke Call

The objective of this lab is to provide hands-on experience debugging a platform invoke call in a .NET Compact Framework application.

In this lab, you will perform the following exercises:

  • Enabling support for attaching the managed debugger to an application
  • Debugging the ManagedToNative application
  • Debugging the BatteryStatus.dll function
  • Resuming to debug the ManagedToNative application
  • Making the Attach to Process support unavailable

Exercise 1: Enabling Support for Attaching the Managed Debugger to an Application

By default, support for attaching the managed debugger to a .NET Compact Framework application is not available in the .NET Compact Framework 2.0. This support is not available to optimize the runtime performance of the application on the device.

When Attach to Process support is enabled, the Just-In-Time compiler generates code that you can debug. Code that you can debug is larger (to accommodate breakpoints, but some optimizations will not be available) and, as a consequence, runs slower.

To start the Remote Registry Editor

  1. On the desktop computer, click Start | All Programs.
  2. Expand the Microsoft Visual Studio 2005 menu.
  3. Expand the Visual Studio Remote Tools menu.
  4. Select Remote Registry Editor.

To connect to the registry on the Windows Mobile 5.0 Smartphone Emulator

  1. In the Select a Windows CE Device dialog box, expand the Windows Mobile 5.0 Smartphone SDK node, as shown in Figure 15.

    Figure 15. The Select a Windows CE Device dialog box

  2. Select Windows Mobile 5.0 Smartphone Emulator, and then click OK, as shown in Figure 16.

    Figure 16. Selecting the Windows Mobile 5.0 Smartphone Emulator

To enable Attach to Process support

  1. In the Windows CE Remote Registry Editor, expand the Windows Mobile 5.0 Smartphone Emulator node, as shown in Figure 17.

    Figure 17. The Windows Mobile 5.0 Smartphone Emulator device in the Remote Registry Editor

  2. Expand the HKEY_LOCAL_MACHINE node under Windows Mobile 5.0 Smartphone Emulator, as shown in Figure 18.

    Figure 18. The HKEY_LOCAL_MACHINE node in the Remote Registry Editor

  3. Expand the SOFTWARE node under HKEY_LOCAL_MACHINE, as shown in Figure 19.

    Figure 19. The SOFTWARE node in the Remote Registry Editor

  4. Expand the Microsoft node under SOFTWARE, as shown in Figure 20.

    Figure 20. The Microsoft node in the Remote Registry Editor

  5. Expand the .NETCompactFramework node under Microsoft, as shown in Figure 21.

    Figure 21. The .NETCompactFramework node in the Remote Registry Editor

  6. Right-click the .NETCompactFramework node, and then click New | Key, as shown in Figure 22.

    Figure 22. Creating a new key in the .NETCompactFramework node

  7. In the New Key dialog box, type Managed Debugger, and then click OK, as shown in Figure 23.

    Figure 23. Creating the Managed Debugger key

  8. Right-click the Managed Debugger node, and then click New | DWORD Value, as shown in Figure 24.

    Figure 24. Creating a new DWORD value in the Managed Debugger node

  9. In the New DWord Value dialog box, type AttachEnabled in the Name box. Type 1 in the Value box, and then click OK, as shown in Figure 25.

    Figure 25. Creating the AttachEnabled value

  10. Leave the Remote Registry Editor open because you will be using it again in Exercise 5.

Exercise 2: Debugging the ManagedToNative Application

When calling a platform invoke method, applications typically perform some tasks to prepare for the call. This preparation often takes place immediately before calling the platform invoke method.

When working with Smart Device projects, only one debugger (managed or native) can be attached to the application at any one time. To switch between debuggers, you must detach the current debugger (for example, managed) and attach the desired debugger (for example, native) manually.

Note   When detaching a debugger, the application resumes execution.

To avoid missing the opportunity to debug the code, the application's execution must be suspended while detaching and attaching the debuggers. In this exercise, you will suspend the application by inserting calls to the Debug.Assert method (from the "System.Diagnostics" namespace) around the call to the platform invoke method.

To load the ManagedToNative project

  1. Open Visual Studio 2005.
  2. On the File menu, click Open | Project/Solution.
  3. In the Open Project dialog box, browse to C:\Program Files\Windows Mobile Developer Samples\HOLs\MEDC06_HOL306\ManagedToNative\.
  4. Select ManagedToNative.sln, and then click Open.

To pause the application before and after the platform invoke call

  1. In Solution Explorer, right-click MainForm.vb, and then select View Code.
  2. In the menuGo_Click method, add a call to Debug.Assert prior to the call to GetBatteryInfo by adding the following code.
    System.Diagnostics.Debug.Assert(False, _
                                    "Attach NATIVE debugger now?")
    
    
  3. In the menuGo_Click method, add a call to Debug.Assert immediately following the call to GetBatteryInfo by adding the following code.
    System.Diagnostics.Debug.Assert(False, _
                                    "Attach MANAGED debugger now?")
    
    

To debug the menuGo_Click method

  1. In Code view, right-click the first line of code in the menuGo_Click method, and then click Run to Cursor, as shown in Figure 26.

    Figure 26. Run to the cursor's current position

  2. In the Deploy ManagedToNative dialog box, select Windows Mobile 5.0 Smartphone Emulator, and then click Deploy.
  3. In the Windows Mobile 5.0 Smartphone Emulator, click the left soft key (under the Go menu), as shown in Figure 27.

    Figure 27. The ManagedToNative application

    When you click the left soft key, Visual Studio enters Debugging mode and identifies the current source code statement, as shown in Figure 28.

    Figure 28. Stopped at the first statement in the menuGo_Click method

  4. Step through the menuGo_Click method until the first Debug.Assert statement is reached, as shown in Figure 29.

    Figure 29. The first Debug.Assert statement in the menuGo_Click method

To detach the managed debugger

  • In Visual Studio, click Debug | Detach All.

    Detaching the debugger causes the application that is being debugged to resume running. When the ManagedToNative application resumes, it executes the call to Debug.Assert and displays a message in the Windows Mobile 5.0 Smartphone Emulator, as shown in Figure 30.

    Click here for larger image

    Figure 30. Assert message in the Windows Mobile 5.0 Smartphone Emulator. Click the thumbnail for a larger image.

    Note   If you do not see this assert message, it is possible that the emulator switched from the ManagedToNative application to the Today screen. To return to the ManagedToNative application, click the Back button on the emulator (the left-pointing arrow above the red phone button).

Exercise 3: Debugging the BatteryStatus.dll Function

In this exercise, you will attach the native debugger to the ManagedToNative application, and then debug the BatteryStatus.dll.

To attach the native debugger engine

  1. In Visual Studio, click Tools | Attach to Process.
  2. In the Attach to Process dialog box, set the Transport to Smart Device, as shown in Figure 31.

    Click here for larger image

    Figure 31. Setting the Transport in the Attach to Process dialog box. Click the thumbnail for a larger image.

  3. In the Qualifier box, select Windows Mobile 5.0 Smartphone Emulator, as shown in Figure 32.

    Click here for larger image

    Figure 32. Setting the Qualifier in the Attach to Process dialog box. Click the thumbnail for a larger image.

  4. In the Available Processes list, select ManagedToNative.exe, as shown in Figure 33.

    Click here for larger image

    Figure 33. Selecting the application to debug. Click the thumbnail for a larger image.

  5. Click the Select button, as shown in Figure 34.

    Click here for larger image

    Figure 34. Selecting the debugger in the Attach to Process dialog box. Click the thumbnail for a larger image.

  6. In the Select Code Type dialog box, select Debug these code types, and then select Native (Smart Device), as shown in Figure 35. Click OK.

    Figure 35. Selecting the Native (Smart Device) debugger

  7. In the Attach to Process dialog box, click Attach, as shown in Figure 36.

    Click here for larger image

    Figure 36. Attaching the Native (Smart Device) debugger to the ManagedToNative application. Click the thumbnail for a larger image.

To debug the native library called by the ManagedToNative application, the Visual Studio 2005 debugger must be made aware of the location of the library's symbol (.pdb) file.

To specify the location of the BatteryStatus.dll symbols

  1. In Visual Studio, click Debug | Window | Modules.
  2. In the Modules pane, right-click anywhere, and then select Symbol Settings, as shown in Figure 37.

    Figure 37. Setting the Symbol Settings in the Modules pane

  3. In the Options dialog box, click the folder icon, as shown in Figure 38.

    Click here for larger image

    Figure 38. Adding a folder to the symbol file locations in the Options dialog box. Click the thumbnail for a larger image.

  4. In the Options dialog box, type the path to the BatteryStatus.pdb file, and then click OK, as shown in Figure 39.

    For this lab, use the following path: C:\Program Files\Windows Mobile Developer Samples\HOLs\MEDC06_HOL306\ManagedToNative\BatteryStatus\Windows Mobile 5.0 Smartphone SDK (ARMV4I)\Debug.

    Click here for larger image

    Figure 39. Setting the symbol location in the Options dialog box. Click the thumbnail for a larger image.

To set a breakpoint in the GetBatteryInfo function

  1. If Solution Explorer is not visible, on the View menu, click Solution Explorer.
  2. In Solution Explorer, expand Battery Status | Source Files, and then double-click BatteryStatus.cpp.
  3. In Code view, right-click the first line of code in the GetBatteryInfo function, and then click Breakpoint | Insert Breakpoint, as shown in Figure 40.

    Figure 40. Setting a breakpoint in the GetBatteryInfo function

    Note   Because the ManagedToNative application will not have loaded BatteryStatus.dll at the time the breakpoint is set, the breakpoint warning icon appears. When the application is resumed, in the next procedure, the breakpoint activates.

To resume the paused application

  • In the Windows Mobile 5.0 Smartphone Emulator, click the right soft key (under Menu), and then click the 3 button on the keypad, as shown in Figure 41.

    Click here for larger image

    Figure 41. Continuing past the Assert message in the Windows Mobile 5.0 Smartphone Emulator. Click the thumbnail for a larger image.

    This step resumes the ManagedToNative application and causes the Visual Studio 2005 debugger to stop at the breakpoint in the GetBatteryInfo function, as shown in Figure 42.

    Figure 42. Stopped at the breakpoint in GetBatteryInfo

To debug the GetBatteryInfo function

  • Step through the GetBatteryInfo function.

To detach the native debugger engine

  • In Visual Studio, click Debug | Detach All.

    As with detaching the managed debugger, when the native debugger is detached, the ManagedToNative application resumes running and executes the second Debug.Assert statement, as shown in Figure 43.

    Click here for larger image

    Figure 43. Assert message in the Windows Mobile 5.0 Smartphone Emulator. Click the thumbnail for a larger image.

Exercise 4: Resuming to Debug the ManagedToNative Application

In this exercise, you will reattach the managed debugger to the ManagedToNative application after the call to GetBatteryInfo completes.

To attach the managed debugger engine

  1. In Visual Studio, click Tools | Attach to Process.
  2. In the Attach to Process dialog box, set the Transport to Smart Device.
  3. In the Qualifier box, select Windows Mobile 5.0 Smartphone Emulator.
  4. In the Available Processes list, select ManagedToNative.exe.
  5. Click the Select button.
  6. In the Select Code Type dialog box, select Automatically determine the type of code to debug, and then click OK, as shown in Figure 44.

    Figure 44. Automatically determine the appropriate debugger

  7. In the Attach to Process dialog box, click Attach.

To resume debugging the menuGo_Click method

  1. In the Windows Mobile 5.0 Smartphone Emulator, click the right soft key (under Menu), and then click 2 on the keypad, as shown in Figure 45.

    Click here for larger image

    Figure 45. Debugging the Assert message in the Windows Mobile 5.0 Smartphone Emulator. Click the thumbnail for a larger image.

    Note   It is important to select Debug from the Assert message's Menu menu. This selection causes Visual Studio 2005 to reenter Debugging mode and resume debugging in the menuGo_Click method of the ManagedToNative application.

    When the managed debugger is attached, the ManagedToNative application is executing code that resides inside the .NET Compact Framework's Base Class Library. Because no source code is available for the Base Class Library, the following message will be displayed:

    There is no source code available for the current location.

  2. Close the warning message by clicking OK.
  3. In Visual Studio 2005, click Debug | Step Over.

    The debugger highlights Debug.Assert as the currently executing statement, as shown in Figure 46.

    Figure 46. Stopped at the Debug.Assert statement in the Visual Studio 2005 debugger

  4. On the Debug menu, select Step Over. The debugger continues, as shown in Figure 47.

    Figure 47. Continuing to debug the ManagedToNative application

  5. Continue debugging the menuGo_Click method.

To stop debugging and close the application

  • In Visual Studio, click Debug | Terminate All.

Exercise 5: Making the Attach to Process Support Unavailable

It is important to remember that Attach to Process support is a device global setting. When enabled, every application that runs on the .NET Compact Framework 2.0 will be run in debug mode.

When a .NET Compact Framework application runs in debug mode, there is an impact on the application's performance because the Just-In-Time compiler generates code to facilitate debugging.

In this exercise, you will use the Remote Registry Editor to make the Attach to Process support unavailable on the Windows Mobile 5.0 Smartphone Emulator.

To make the Attach to Process support unavailable

  1. In the Windows CE Remote Registry Editor, expand the Windows Mobile 5.0 Smartphone Emulator node.
  2. Expand the HKEY_LOCAL_MACHINE node under Windows Mobile 5.0 Smartphone Emulator.
  3. Expand the SOFTWARE node under HKEY_LOCAL_MACHINE.
  4. Expand the Microsoft node under SOFTWARE.
  5. Expand the .NETCompactFramework node under Microsoft.
  6. Right-click the Managed Debugger node under .NETCompactFramework, and then select Delete, as shown in Figure 48.

    Figure 48. Deleting the Managed Debugger node in the Remote Registry Editor

    Note   Attach to Process support can also be made unavailable by setting the AttachEnabled value in the Managed Debugger key to 0.
  7. Click Yes when the Delete Key confirmation dialog box appears.
  8. Click the Windows Mobile 5.0 Smartphone Emulator node, and on the Target menu, select Disconnect.
  9. Leave the Remote Registry Editor open because you will be using it again in Lab 3.

Summary

In this lab, you performed the following exercises:

  • Enabling support for attaching the managed debugger to an application
  • Debugging the ManagedToNative application
  • Debugging the BatteryStatus.dll function
  • Resuming to debug the ManagedToNative application
  • Making the Attach to Process support unavailable

In this lab, you configured the Windows Mobile 5.0 Smartphone Emulator to run .NET Compact Framework applications with Attach to Process support enabled. You then debugged a managed application's use of a custom native library by switching between the managed and native debuggers.

Lab 3: Using the .NET Compact Framework Interop Log to Diagnose a Platform Invoke Call Issue

Diagnostic logging can be an invaluable resource in diagnosing application issues. The .NET Compact Framework 2.0 has new logs, such as the Interop, Loader, and Network logs. This lab only uses the Interop log, which collects detailed information about how a managed application uses unmanaged functions and COM objects.

Diagnostic logging is especially useful when it is not feasible to run the application in the Visual Studio 2005 debugger. The objective of this lab is to use the .NET Compact Framework Interop log to diagnose a platform invoke call issue.

In this lab, you will perform the following exercises:

  • Enabling the .NET Compact Framework Interop log
  • Running an application that receives an incorrect result from a platform invoke call
  • Using the Interop log to diagnose the platform invoke call issue
  • Disabling the .NET Compact Framework Interop log

Exercise 1: Enabling the .NET Compact Framework Interop Log

In this exercise, you will use the Remote Registry Editor to enable the Interop log feature in the .NET Compact Framework on the Windows Mobile 5.0 Pocket PC Emulator.

To connect to the registry on the Windows Mobile 5.0 Pocket PC Emulator

  1. In the Remote Registry Editor, click Target | Connect.
  2. In the Select a Windows CE Device dialog box, expand the Windows Mobile 5.0 Pocket PC SDK node.
  3. Select Windows Mobile 5.0 Pocket PC Emulator, and then click OK.

To enable .NET Compact Framework diagnostic logging

  1. In the Windows CE Remote Registry Editor, expand the Windows Mobile 5.0 Pocket PC Emulator node.
  2. Expand the HKEY_LOCAL_MACHINE node under Windows Mobile 5.0 Pocket PC Emulator.
  3. Expand the SOFTWARE node under HKEY_LOCAL_MACHINE.
  4. Expand the Microsoft node under SOFTWARE.
  5. Expand the .NETCompactFramework node under Microsoft.
  6. Right-click the .NETCompactFramework node, and then click New | Key.
  7. In the New Key dialog box, type Diagnostics, and then click OK, as shown in Figure 49.

    Figure 49. Creating the Diagnostics key

  8. Right-click the Diagnostics node, and click New | Key.
  9. In the New Key dialog box, type Logging, and then click OK.
  10. Right-click the Logging node, and then click New | DWORD Value.
  11. In the New DWord Value dialog box, type Enabled in the Name box, and then type 1 in the Value box, as shown in Figure 50. Click OK.

    This step enables the .NET Compact Framework diagnostic logging feature.

    Figure 50. Enabling diagnostic logging

To enable Interop logging

  1. Right-click the Logging node, and then click New | Key.
  2. In the New Key dialog box, type Interop, and then click OK.
  3. Right-click the Interop node, and then click New | DWORD Value.
  4. In the New DWord Value dialog box, type Enabled in the Name box, and then type 1 in the Value box. Click OK.

    This step enables the Interop logging feature in the .NET Compact Framework.

  5. Leave the Remote Registry Editor open because you will be using it again in Exercise 4.

Exercise 2: Running an Application That Receives an Incorrect Result from a Platform Invoke Call

In this exercise, you will deploy an application by using Visual Studio 2005 and run it from the Windows Mobile 5.0 Pocket PC Emulator without being connected to the debugger.

To load the IncorrectPInvokeResult project

  1. Open Visual Studio 2005.
  2. On the File menu, click Open | Project/Solution.
  3. In the Open Project dialog box, browse to C:\Program Files\Windows Mobile Developer Samples\HOLs\MEDC06_HOL306\IncorrectPInvokeResult\.
  4. Select IncorrectPInvokeResult.sln, and then click Open.

To deploy the IncorrectPInvokeResult application to the Windows Mobile 5.0 Pocket PC Emulator

  1. In Visual Studio, click Build | Deploy Solution.
  2. In the Deploy IncorrectPInvokeResult dialog box, select Windows Mobile 5.0 Pocket PC Emulator, and then click Deploy.

To run the IncorrectPInvokeResult application

  1. On the Windows Mobile 5.0 Pocket PC Emulator, click Start | Programs | File Explorer.
  2. In the File Explorer drop down list, browse to My Device, and then click Program Files | IncorrectPInvokeResult.
  3. In File Explorer, click IncorrectPInvokeResult to start the application.

To call the platform invoke method

  1. After the application appears on the Windows Mobile 5.0 Pocket PC Emulator, enter 98052, and then press the left soft key, as shown in Figure 51.

    Click here for larger image

    Figure 51. The IncorrectPInvoke Result application. Click the thumbnail for a larger image.

    Here, the platform invoke call appears to succeed. The ReturnParameterValue function from InteropExample.dll returned the value that was expected.

  2. In the Windows Mobile 5.0 Pocket PC Emulator, type 4294967296, and the click the left soft key, as shown in Figure 52.

    Click here for larger image

    Figure 52. An unexpected result is returned. Click the thumbnail for a larger image.

    This time, the platform invoke call returned a value (0) that was unexpected.

  3. In the Windows Mobile 5.0 Pocket PC Emulator, click Exit.

    A file called netcf_Interop.log is now listed in the IncorrectPInvokeResult folder in the File Explorer of the emulator.

Exercise 3: Using the Interop Log to Diagnose the Platform Invoke Call Issue

In this exercise, you will copy the log file, which you created earlier, from the Windows Mobile 5.0 Pocket PC Emulator to a folder on the desktop computer. After you copy this file, you will examine the log file to identify the cause of the unexpected result that you saw in Exercise 2.

To copy the netcf_Interop.log file from the Windows Mobile 5.0 Pocket PC Emulator

  1. In the emulator, click File | Configure.
  2. In the Emulator Properties dialog box, set Shared folder to C:\Program Files\Windows Mobile Developer Samples\HOLs\MEDC06_HOL306\IncorrectPInvokeResult, and then click OK, as shown in Figure 53.

    Click here for larger image

    Figure 53. Configuring the emulator's shared folder. Click the thumbnail for a larger image.

  3. In the File Explorer, click and hold the netcf_Interop entry, and then click Copy.
  4. In the File Explorer drop down list, browse to Storage Card.
  5. In the File Explorer, click and hold Storage Card, and then click Paste.

    This step copies the netcf_Interop.log file to the C:\Program Files\Windows Mobile Developer Samples\HOLs\MEDC06_HOL306\IncorrectPInvokeResult folder.

To identify the cause of the incorrect result from the platform invoke call

  1. On the desktop computer, open Notepad.
  2. On the File menu, click Open.
  3. In the Open dialog box, type C:\Program Files\Windows Mobile Developer Samples\HOLs\MEDC06_HOL306\IncorrectPInvokeResult\netcf_Interop.log, and then click Open.
  4. Locate the entry for the call to ReturnParameterValue in the netcf_Interop.log file, as shown in the following code example.
    Note   In Exercise 2, you called the ReturnParameterValue twice, so there are two identical entries in the Interop log file.
    [pinvokeimpl][preservesig]
    int  MEDC2006.Demo.IncorrectPInvokeResult.MainForm::ReturnParameterValue(long );
    int (I4_VAL) ReturnParameterValue(INT64 (I8_VAL) );
    
    
  5. Identify the cause of the incorrect result.

    The entry shown in Step 4 lists the managed and native call signatures as understood by the .NET Compact Framework runtime.

    By examining the following native call signature, int (I4_VAL) ReturnParameterValue(INT64 (I8_VAL) ); you can see that the .NET Compact Framework called the ReturnParameterValue function, passing an 8-byte value to the function and expected to receive 4 bytes in return.

    Because in the Microsoft Win32 API, the size of the long data type is 4 bytes (32 bits) and in the .NET Compact Framework, the same data type is defined as being 8 bytes (64 bits) in size—this is the cause of the incorrect result.

Exercise 4: Making the .NET Compact Framework Interop Log Unavailable

It is important to remember that diagnostic logging support is a device-global setting. When enabled, every application that runs the .NET Compact Framework 2.0 writes out log files. It is recommended that you make diagnostic logging support unavailable when you are finished investigating your application issue.

In this exercise, you will use the Remote Registry Editor to make the diagnostic logging support unavailable on the Windows Mobile 5.0 Pocket PC Emulator.

To make the .NET Compact Framework runtime logging support unavailable

  1. In the Windows CE Remote Registry Editor, expand the Windows Mobile 5.0 Pocket PC Emulator node.
  2. Expand the HKEY_LOCAL_MACHINE node under Windows Mobile 5.0 Pocket PC Emulator.
  3. Expand the SOFTWARE node under HKEY_LOCAL_MACHINE.
  4. Expand the Microsoft node under SOFTWARE.
  5. Expand the .NETCompactFramework node under Microsoft.
  6. Right-click the Diagnostics node under .NETCompactFramework, and then select Delete.
  7. Click Yes when the Delete Key confirmation dialog box appears.
    Note   Diagnostic logging support can also be made globally unavailable by setting the Enabled value in the Logging key to 0. To make only the interop log unavailable, set the Enabled value to 0 in the Interop key.
  8. Close the Remote Registry Editor.

Summary

In this lab, you performed the following exercises:

  • Enabling the .NET Compact Framework Interop log
  • Running an application that receives an incorrect result from a platform invoke call
  • Using the Interop log to diagnose the platform invoke call issue
  • Making the .NET Compact Framework Interop log unavailable

In this lab, you used the .NET Compact Framework's Interop log to identify the cause of an unexpected result that was being returned from a platform invoke call.

Appendix A. Terminating an Application That Is Running on a Device or Emulator

This appendix describes how to terminate an application that is running on a device or emulator. This is useful for cases where an application has been started without having the debugger attached and the application needs to be terminated so a new copy of the application can be deployed. You will terminate the application by using the Remote Process Viewer remote tool in Visual Studio.

Before you can terminate a process, you need to know the name of the executable file. In most cases, this is the same name as the Visual Studio project. If you are uncertain about the name of the executable file, you can find it in the project's properties.

To terminate an application that is running on a device or emulator by using the Remote Process Viewer remote tool

  1. In Visual Studio, click Project | xxx Properties, where xxx represents the name of the current project.
  2. In the Project Properties dialog box, note the value in the Assembly Name box. This is the name that the executable file will be running on the device or emulator.
  3. Close the Properties dialog box.

    Now, you can terminate the process.

  4. On the desktop computer, click Start | Microsoft Visual Studio 2005 | Visual Studio Remote Tools | Remote Process Viewer.
  5. When prompted by the Select a Windows CE Device dialog box, select the emulator or device where the application is running, as shown in Figure 54, and then click OK.

    Figure 54. Select a Windows CE Device dialog box

  6. After the connection to the emulator or device completes, select the application that you want to terminate in the top pane of the Remote Process Viewer, as shown in Figure 55.

    Click here for larger image

    Figure 55. Selecting the application to terminate. Click the thumbnail for a larger image.

    You may need to widen the Process column (the leftmost column) to fully view the process names.

  7. In Windows CE Remote Process Viewer, click File | Terminate Process to terminate the process.
    Note   Be certain that the correct process is selected before you click Terminate Process. Terminating the incorrect process may render the device or emulator unusable, requiring it to be reset before you can use it again.
  8. Verify that the process is terminated by selecting Target | Refresh. Scroll to the top pane of Windows CE Remote Process Viewer again. If the application name still appears, the process was not terminated, and you need to repeat these steps.
    Note   Most processes terminate in one try; however, depending on the state of the application, terminating a process occasionally takes two attempts.

Appendix B: Setting Up Your Computer

The following lab files are required to set up your computer to run this HOL:

  • Pre-existing Visual Studio 2005 project, code, and data files.

To install these files to the correct path, download and run the following installation program: MEDC06_HOL306.msi.

Note   If you used an emulator in a previous HOL, you should do a hard reset on the emulator before starting this HOL. (On the emulator, click File | Reset | Hard.)
Note   If you receive an error during deployment that indicates that the process or file is in use, this means that the program is still running on the emulator and must be closed before a new copy can be deployed and run. This error may appear anytime in the lab that you deploy the emulator. See Appendix A in this HOL for instructions about exiting a running application.
Show:
© 2014 Microsoft