Using the Surface Dial as a Debug Tool

here’s a small video of the extension in action:

the surface dial is a nifty little device, it feels great and can add some nice capabilities to your apps. however, the very best thing about it is that is has an api. i had a go with it and decided to try and turn the dial into a debugging device.

the goal

the dial has a few gestures. it’s a button that you can press, and it rotates clockwise and counter-clockwise. my goal was to start a debugging session by clicking the dial, step-over (f10) by rotating clockwise and step-into (f11) by rotating counter-clockwise.

pre-requisites

we’ll need some stuff to get going:

setting up a visual studio extension

to start creating a visual studio extension, launch visual studio 2015 and start a new project. if the sdk is installed correctly there should be an extensibility option with a vsix project template.

the project it creates is basically an empty box, just some boilerplate code to have a vsix installer and have it install your extension in vs. to start adding some functionality to the extension we need to add an extra item, in this case, it will be a package, these are added as a new item into the project.

almost ready, all we need to add next is when our extension should load. we’re going to choose for load on solution load in this sample. this is done by adding an attribute on the package class.

[provideautoload(uicontextguids80.solutionexists)]

thrown together, we get:

[packageregistration(usemanagedresourcesonly = true)]
[installedproductregistration("#110", "#112", "1.0", iconresourceid = 400)] // info on this package for help/about
[guid(dialdebugpackage.packageguidstring)]
[suppressmessage("stylecop.csharp.documentationrules", "sa1650:elementdocumentationmustbespelledcorrectly", justification = "pkgdef, vs and vsixmanifest are valid vs terms")]
[provideautoload(uicontextguids80.solutionexists)]
[providemenuresource("menus.ctmenu", 1)]
public sealed class dialdebugpackage : package
{
…

if you press f5 now, an experimental instance of visual studio should launch, with the extension installed.

connecting to the dial

this was the hardest part of the project, the dial api is done in uwp. this is how we can grab the dial instance in uwp (currently only one dial is supported per system)

var controller = radialcontroller.createforcurrentview();

the problem here is not the fact that it’s a uwp api, we can use those from win32 . the problem is that the createforcurrentview() method requires a handle to the current window, a uwp window, which we obviously don’t have. i found the solution for this in one of the official microsoft samples. they have a sample in the windows-classic-samples repository that shows how to access the dial from a winforms application .

i took the radialcontrollerinterop class from that sample and added it to the extension. however, as it turned out, it was only part of the solution.

[system.runtime.interopservices.guid("1b0535c9-57ad-45c1-9d79-ad5c34360513")]
[system.runtime.interopservices.interfacetype(system.runtime.interopservices.cominterfacetype.interfaceisiinspectable)]
public interface iradialcontrollerinterop
{     radialcontroller createforwindow(     intptr hwnd,     [system.runtime.interopservices.in]ref guid riid);
}
 
[system.runtime.interopservices.guid("787cdaac-3186-476d-87e4-b9374a7b9970")]
[system.runtime.interopservices.interfacetype(system.runtime.interopservices.cominterfacetype.interfaceisiinspectable)]
public interface iradialcontrollerconfigurationinterop
{     radialcontrollerconfiguration getforwindow(     intptr hwnd,     [system.runtime.interopservices.in]ref guid riid);
}

the interop interfaces actually reference the radialcontroller class that lives in windows.ui.input, a uwp namespace that we currently have no reference to. that’s where the uwpdesktop nuget package comes in. this package makes it easy to reference uwp classes from win32 style applications. once added through nuget we can add the windows.ui.input namespace to the interop class.

using system;
using windows.ui.input;

namespace dialdebug
{
    [system.runtime.interopservices.guid("1b0535c9-57ad-45c1-9d79-ad5c34360513")]
    [system.runtime.interopservices.interfacetype(system.runtime.interopservices.cominterfacetype.interfaceisiinspectable)]
    public interface iradialcontrollerinterop
    {
        radialcontroller createforwindow(
        intptr hwnd,
        [system.runtime.interopservices.in]ref guid riid);
    }

    [system.runtime.interopservices.guid("787cdaac-3186-476d-87e4-b9374a7b9970")]
    [system.runtime.interopservices.interfacetype(system.runtime.interopservices.cominterfacetype.interfaceisiinspectable)]
    public interface iradialcontrollerconfigurationinterop
    {
        radialcontrollerconfiguration getforwindow(
        intptr hwnd,
        [system.runtime.interopservices.in]ref guid riid);
    }
}

we’ve got everything in place to connect to the dial from visual studio.

gluing it together

back to the package class, there should be an initialize method, overridden from the base class. this is where we’ll hook everything up.

protected override void initialize()
{
    base.initialize();

    _dte = getservice(typeof(dte)) as dte;

    if (_dte == null)
    {
        throw new nullreferenceexception("dte is null");
    }

    createcontroller();
    createmenuitem();
    hookupevents();
}

the first thing we’ll do is grab hold of the current visual studio instance, which is a dte object. we keep a reference to this object in a field because we’ll need it later.

next up is connecting to the dial

private void createcontroller()
{
    iradialcontrollerinterop interop = (iradialcontrollerinterop)system.runtime.interopservices.windowsruntime.windowsruntimemarshal.getactivationfactory(typeof(radialcontroller));
    guid guid = typeof(radialcontroller).getinterface("iradialcontroller").guid;

    _radialcontroller = interop.createforwindow(new intptr(_dte.activewindow.hwnd), ref guid);
}

in this method we’re using interop to get access to the uwp radialcontroller class via the interface we took from the classic windows samples. as a handle for the windows we pass in the handle for our current visual studio instance which we can get to from the dte object. at this point we got a reference to the dial that is connected to our system.

the dial has a radial menu that we can hook into and add or remove items from it. we’ll add a debug item to it.

private void createmenuitem()
{
    _menuitems = new list<radialcontrollermenuitem>
    {
        radialcontrollermenuitem.createfromknownicon("debug", radialcontrollermenuknownicon.inkcolor),
    };

    foreach (var item in _menuitems)
    {
        _radialcontroller.menu.items.add(item);
    }
}

i’m doing this through a list just in case i ever want to add more items, but at the moment i’m only adding one. a radialcontrollermenuitem is created via the createfromknownicon method. first parameter is the text that will be displayed in the menu, the second one is an enum value from an enum that contains some known menu icons. a radialcontroller has a menu property that has a collection of items, all we need to do is add our items to that collection and it will show up in the radial menu.

final step is adding the event handlers and calling the debugger methods to let the dial step through the code.

private void hookupevents()
{
    _radialcontroller.rotationchanged += onrotationchanged;
    _radialcontroller.buttonclicked += onbuttonclicked;

    _dte.events.solutionevents.afterclosing += () =>
    {
        _radialcontroller.menu.items.clear();
    };
}

as you can see, the events coming from the dial are very straightforward, there is a buttonclicked and a rotationchanged event.

here’s what we need to do to start debugging on button click:

private void onbuttonclicked(radialcontroller sender, radialcontrollerbuttonclickedeventargs args)
{
    if (_dte.application.debugger.currentmode == dbgdebugmode.dbgrunmode)
    {
        _dte.application.debugger.stop();
    }
    else
    {
        _dte.application.debugger.go();
    }
}

the visual studio sdk provides an easy to use api surface. we can use the dte.application.debugger class to control the debugger. the go() method launches a debug session, the stop() method, well, stops a debugging session.

next, we’ll handle the rotation events

private void onrotationchanged(radialcontroller sender, radialcontrollerrotationchangedeventargs args)
{
    if (args.rotationdeltaindegrees > 0)
    {
        _dte.application.debugger.stepover();
    }
    else
    {
        _dte.application.debugger.stepinto();
    }
}

from the args we get the rotation delta, one step on the rotator is a delta of 10, +10 clockwise and –10 counter-clockwise.

and that’s it, build it in release mode and the bin/release folder will contain a .vsix installer file. close vs, install the extension, reopen vs, open a solution, select debug from the radial menu and debug away!

the source code is on github . here’s a link to the compiled vsix file.

disclaimer: the code is provided as-is. i do not plan to publish this on the gallery or maintain the project. do feel free to pick this up and create an open-source project from it (would be nice to include a reference to this post in the description )

happy coding!