Tuesday, September 8, 2015

WinRT ABI Debugging Workflow

VS can debug a WinRT app's code, but how do you debug the actual ABI?  Here are some handy tricks to deploying and testing the ABI.

Setting Up the Test Box

For my systems programming, I like to have a development machine, and a separate test machine.  This should be obvious, but yes, you can hose your development machine by replacing system binaries with modified ones.  At this point, many of my coworkers simply use VMs.  These days, you can grab a VHD directly off of the build share, so you don't even have to install the OS anymore.  Maybe I am old fashioned, but I actually like to have a physical PC to test on.  Generally it is faster and more reliable.  Furthermore, I have less distractions, so I can debug faster.

What you need to install & configure:
  1. Install a correct build of the OS.
  2. Install WinDBG.  I guess it is part of the WDK?
  3. Copy over the symbols locally.  I think you can also get these from the WDK?  You can also try to rely on the symbol server.
  4. Set you PC to "Developer mode"
    Settings->Update & Security->For developers->Developer mode
  5. Install Remote Tools For VS 2015 : http://www.microsoft.com/en-us/download/details.aspx?id=48155
  6. Run the remote debugging configuration:
    Start -> All Apps -> Visual Studio 2015 -> Remote Debugging Configuration -> Remote debugger

    Click "Configure remote debugging"

  7. Then you will see something like this:

    This means your test box is ready.

Setting Up the Dev Box

To use the fancy new remote app testing feature, you just need to:
  1. Install VS2015.
  2. Install the Windows SDK from the same build installed on your test machine.


  1. Dev Box: Write a test app to test the ABI functionality of the ABI.
  2. Dev Box: Build the app in VS2015 for the architecture of the test machine.
  3. Test Box: Run the "Remote debugger" desktop app
  4. Dev Box: Hit the down arrow for start debugging, and select "Remote machine."  If it is the first time you have done this, it will have a dialog to select your test machine.  Select it and hit play.  If you don't see your test machine, see #3.

  5. Test: Validate that your test app is running and working.
  6. Dev: Hit the stop button.

    Why did we bother to start the app to just stop it without any debugging?  It is mainly to just get the app deployed to the test machine.
  7. Test: find the name of the app package for your test app.

    plmdebug /query

    The output should look something like this:
    Package full name: 02985851.Mint.comPersonalFinance_1.2.0.2529_x86__xm34sne40gbwr
    Package state: Unknown
    Package full name: 1ED5AEA5.AngryBirdsSpace_1.6.1.0_x86__p2gbknwb5d8r2
    Package state: Unknown

    In case you were wondering PLM stands for the Process Lifetime Manager.
  8. Test: Then you run:

    plmdebug /enabledebug [package full name here]  "c:\debuggers\windbg.exe"

    This will set the correct image execution options so that windbg will attach to the app container before the app starts running.  Whenever your app starts, you will get windbg window to pop.  This works for everything: foreground apps, background tasks, app activation contracts, etc.
  9. Test: Once, windbg launches, set your break points in your code as you would with a normal Win32 code, and let the debugger go.  
  10. Test: Run through your test app that executes the code you are interested in.