Debugging Windows Presentation Foundation applications
Windows Presentation Foundation (WPF) apps, like other managed code applications, can be built on the command line as well as within an IDE like Visual Studio. The Visual Studio IDE environment with "Orcas" tools provides for sophisticated debugging features. Since there are some nuances to debugging, I figured it merited a post. I will try to keep this live, as things change.
The F5 debugging
People familiar with managed code debugging will see that the process of debugging WPF apps, whether standalone or browser-hosted, is pretty much the same. Within VS, you hit F5 to start the app in debug mode.
WPF browser-hosted apps (XBAPs), unlike their standalone counterparts, do not have a main method in the application executable. They are therefore launched by PresentationHost.exe, an out-of-process document object host, which is the registered Shell and MIME handler for .xbap files. The XBAP project file lists PresentationHost.exe as the program that needs to be launched when you debug XBAPs (via
StartProgram project property). The StartArguments property lists the command line parameters passed on to PresentationHost.exe. The notable item here is the -debug argument that tells PresentationHost.exe, "You are running in debug mode. Here's the XBAP you need to launch. Be a darling and don't induct it into the ClickOnce store".
There are some notable differences you need to understand:
- When you debug an XBAP, your app is not ClickOnce-deployed; meaning, the app is not inducted into the ClickOnce app store. This allows you to rev your application without revving the version numbers.
- Because of the above, the app will not return
- The app is launched from your project's
bin\Debugfolder) and that location is treated as the "site of origin" for the app. Any remote resources need to be manually placed at that location.
Debugging by attaching to a running process
This is like attaching to any other running program in Visual Studio, except that you attach to PresentationHost.exe, not the XBAP or its executable. Assuming you've set breakpoints in the source files, the actual debugging steps are:
- From a command window run:
- Within Visual Studio, click project Properties -> Debug
- Check Enable unmanaged code debugging. Save your changes.
- Click Debug -> Attach to Process
- Select PresentationHost.exe from the available processes list
- In the Attach To section, hit Select and check Managed Code and Native Code
- Click Attach
- Double click on the XBAP from your project's
The app will launch in your default browser. All your break points should get hit.
If you have multiple XBAPs running, make sure you attach to the right PresentationHost instance. It is easier if the XBAP being debugged is the only XBAP running. Also, the next time you want to debug the same XBAP, make sure you've cleared the ClickOnce app store (using
mage -cc) or incremented the app's version.
Files at site of origin
If your app needs to access files or web services residing at it's site of origin, you can still use the F5 debugging method. Only, you need to tell Visual Studio to debug the app as if it were deployed from that location. Say, you have an app that is intended to be deployed from http://www.yoursite.com/apps/. Now, that location is deemed the application's site of origin. Suppose you have several data files and a web service running at that location, that your WPF app needs to access. You need to:
- Navigate to project Properties -> Security tab -> Advanced button
- Make sure the "Grant the application access to its site of origin" option is checked
- Type in the location from where you want VS to believe the app is deployed. In our case, it will be http://www.yoursite.com/apps/
- Click OK
- Hit Ctrl+Shift+S to save all files
- Close the solution (File -> Close solution)
- Re-open solution
- Hit F5 to debug
Steps 6 and 7 are required because currently these properties are applied only on project load. These actions modify the project's
StartArguments property. Please do not edit its value separately.
Debugging XBAPs to be run within Media Center
Assuming you have the Media Center SDK and by extension the XBAP templates for Media Center installed on your development machine, here's how you debug an XBAP meant to run in MCE:
- From a command window run:
- From within Visual Studio, hit F5 to debug your XBAP
A .MCL file is created and the MCE Shell (
ehshell.exe) is launched with this file name as parameter. You will see your XBAP load and all your breakpoints should trigger.
There are one issue you need to be cognizant about: While running or debugging your XBAP (created with the MCE template), you will notice that changes you made to the app are not reflected when the app is run. This is because the app run outside of VS was somehow cached in the ClickOnce app store (unlike with conventional XBAPs). You can work around this issue by incrementing the version number of your application, or by using
mage -cc to clear your ClickOnce app store. Make sure the MCE shell is closed when you do this. Mage.exe ships with the .NET SDK or Windows SDK.
Tags: WinFX, NetFX3, Orcas, WPF, Avalon, MediaCenter, Debugging