UWP with Desktop Extension – Part 1

desktop_purple

Adding a desktop extension component to your UWP app package is a great way to make your universal app even better on PC by lighting up PC-specific capabilities. Recently on Stackoverflow I have seen a number of questions coming up around this topic, so I decided to write up a quick tutorial to help de-mystify various aspects around this useful feature:

Part 1 – Getting started, hello world (this post)
Part 2 – Launching multiple processes, passing in parameters
Part 3 – Communicating between components
Part 4 – Submitting the package to the Microsoft Store

TL;RD;

Including a desktop extension (‘windows.fullTrustProcess’) in your UWP app package lets your UWP app light up PC-specific capabilities when run on the Windows 10 desktop SKU (including Windows 10 S mode). The extension code runs at the full privileges of the user and has access to all public APIs on the machine. Your app will still be able to run on all SKUs of Windows 10 (e.g. Hololens) – it just won’t light up the desktop extension on those devices. This feature has been introduced with the Windows 10 Anniversary Update 1607 (build 14393, aka Redstone 1).

Show me the code for “Hello World” on github
https://github.com/StefanWickDev/UWP-FullTrust/tree/master/UWP_FullTrust_1

Let me try your “Hello World” app from the Microsoft Store
https://www.microsoft.com/store/apps/9ND9W9HWSWNS

Project Setup

With Visual Studio 2017 Update 5 (and later), creating a UWP solution with desktop extension is fairly straight forward now. Here is a step-by-step guide to create your first UWP app that lights up powerful desktop code:

Add extension and packaging projects

In your UWP VS solution, add a “Windows Classic Desktop” project to implement your extension. This could be any type of Win32 or .NET project in any language. For “Hello World” I am adding a C# Console project. Next you need to add a “Windows Application Packaging Project” (look for it in the “Windows Universal” category).

So your solution setup looks like in the screenshot below. In order to package both the UWP and the desktop code in one app package, add both as Application references to the Packaging project:

AddAppRefs

Making the code work together

Now to connect the two projects we need to declare the extension in the package manifest. For this open the Package.appxmanifest file in the Packaging project (“Package”) in XML editing mode and add the following section within the <Application> node:

<Extensions>
 <desktop:Extension
   xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
   Category="windows.fullTrustProcess"
   Executable="DesktopExtension\DesktopExtension.exe" />
</Extensions>

Note that the Packaging project by default adds the ‘runFullTrust’ capability to your manifest, which needs to be declared for this extension. Note that this is a restricted capability and will require an additional on-boarding review for the public Microsoft Store – more details on this in part 4 of this series.

To invoke the extension, we are using the FullTrustProcessLauncher API from the UWP Desktop Extension SDK (which is part of the Windows SDK and should already be on your machine). So let’s add a reference to this SDK from our UWP project (“Hello World”):

AddSDKref

Now in your UWP app code, add a line of code to invoke the desktop extension component. It is very important to wrap this into an if-statement as shown, to make sure the app is still universal and can run on all current and future SKUs of Windows 10. We want to launch the extension only on devices that support this contract, in this case on Desktop devices.

if (ApiInformation.IsApiContractPresent("Windows.ApplicationModel.FullTrustAppContract", 1, 0))
{
  await FullTrustProcessLauncher.LaunchFullTrustProcessForCurrentAppAsync();
}

In our desktop extension code (in Program.cs), we just add a quick piece of code for testing/demo purposes:

class Program
{
 static void Main(string[] args)
 {
  Console.Title = "Hello World";
  Console.WriteLine("This process has access to the entire public desktop API surface");
  Console.WriteLine("Press any key to exit ...");
  Console.ReadLine();
 }
}

Run, test and debug

First, double check the configuration properties for solution and make sure it looks like this picture for all configurations you care about (architecture & debug/release). Specifically, you want to uncheck the “Deploy” action for the UWP, since deploy will done from the Packaging Project.

screenshot10

Now make sure you have set the “Package” project as the solution’s start up project in VS, and “Hello World” is its application entry point. Now hit F5 and test out your project. Debugging the UWP code continues to work as before. In order to debug the desktop code, launch without debugging and manually attach to the desktop process in VS. The latter should become more seamless in an upcoming update to VS (I believe the work is scheduled for Update 8), which will let you debug across the UWP/Desktop boundary seamlessly.

screenshot5

This is it for my first post in this tutorial series. Now that you have seen “Hello World” I hope you can imagine some of the possibilities this enables. Keep in mind the desktop extension can be any type of project, e.g. a C++ background process, a VB Winforms app, a C# WPF app, etc. – or any combination of those and it has access to the full public API surface on the machine. More on this in the next post.

Also see my earlier blog posts that use the same pattern to implement some concrete desktop scenarios – UWP with Systray Extension & Office Interop with UWP.

Next up: Part 2 – Launching multiple processes, passing in parameters

 

Advertisements

25 thoughts on “UWP with Desktop Extension – Part 1

  1. Is there any easy way to add DLL dependencies for Win32 applications to the package project? The .exe is copying fine, but do I still need to use xcopy to get it’s DLL dependencies?

    Like

  2. I tried both console as well as WinForm dekstop apps embed in UWP and run as desktop extension. But both scenarios I get some UI in the output.

    But my requirement is just to get some details which is not possible in UWP and possible in desktop code but I don’t need any UI for that, neither a form nor a console window.

    Can I call some API only as part of dll instead of executable desktop code? Or any other way without UI to run desktop code?

    Like

    1. Yes, it’s possible to run the desktop code without UI. Take a look at part 2 of this series, in the paragraph titled “Background Processes” – and the corresponding sample. The way you do it is you create a Console application and in the project properties you set OutputType=WindowsApplication (I know that’s not very intuitive …)

      Like

  3. In my w10 rs5 17774.1003 + vs17 15.8.2 environment under vs17 | file | new project | visual c# | windows universal I don’t see any “Windows Application Packaging Project” choice closest thing to that is “Optional Code Package (Windows Universal)”. Any thoughts on what I need to do to get the “Windows Application Packaging Project” to show up?

    Liked by 1 person

    1. You need to add a reference to the windows.winmd in \Program Files (x86)\Windows Kits\10\UnionMetadata\10.0.17134.0\ (replace the version with whatever Windows SDK you are currently targeting).

      Like

      1. Thank you so much! Decidedly non-intuitive since winmd files aren’t a type in the file browser when adding references.

        Like

    1. I believe you should be able to to use the DeviceIOControl API from your UWP directly. Also, from a full trust process extension you should be able to reuse your existing Win32 code for talking to the driver as is. Have you tried this?

      Like

      1. /ZW compiler option shouldn’t be required, but you will need to use the /APPCONTAINER linker option if you want to call your library from the UWP process directly. However, if you are using a desktop extension process you should be able to call your existing library as-is.

        Like

      2. I’ll try this. Basically I want to Convert my existing DLL code which interact with Kernel mode driver(WDM driver). For IOCTL i’m using DeviceIoControl APIs.
        For porting my app to UWP i’m using this link : https://docs.microsoft.com/en-us/cpp/porting/how-to-use-existing-cpp-code-in-a-universal-windows-platform-app?view=vs-2017 .

        After applying changes in project properties as mentioned in link, i’m getting error as DeviceIoControl identifier not found. That’s issue i’m facing. Please let me know if is there any sample app/API available instead of DeviceIoControl?

        Thanks for Help

        Like

      3. Not sure why it’s failing. Unfortunately this API is outside of my area of expertise. I’d suggest you post your question on Stackoverflow tagged with ‘UWP’. Microsoft support folks as well as community members are watching that tag and should be able to provide more help.

        Like

  4. Hi Stefan,
    When I ran your sample code, I got an exception error on the line of

    await FullTrustProcessLauncher.LaunchFullTrustProcessForCurrentAppAsync();

    The HRESULT is E_ACCESSDENIED.
    I tried to set up the Hello demo step by step, same problem. Am I missing something ?
    Thanks

    Like

      1. I got the code from Github and run without any changes. Here is the exception data:
        ” at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n at System.Runtime.CompilerServices.TaskAwaiter.GetResult()\r\n at UWP.MainPage.d__1.MoveNext()”

        What is the MoveNext() ?

        I am running Win10 1803, with SDK 17134.

        Appreciate it.

        Like

      2. It works for me. Here are my exact steps:
        1. download and extract the .zip from here: https://github.com/StefanWickDev/UWP-FullTrust
        2. open UWP_FullTrust_1.sln in VS2017 (15.8.8) with SDK 17134
        3. set the “Package” project as startup project
        4. set architecture to x64 (or x86)
        4. deploy the solution
        3. Hit F5

        Now the project runs as expected. Let me know if your problem persists when following these steps.

        Like

  5. Hi,

    I tried the exact steps as you mentioned. After I hit F5, the splash image shows up but then VS hangs with a line in status bar saying : “Loading symbols for combase.dll”, then after a few minutes, I got a message box saying :”Unable to activate Windows Store app … UWP.exe process started, but the activation request failed with error”. I got this error for both Debug and Release mode.

    However, after deploying the release version, I can start it from the the Start menu. I tried all the three samples and they all seem work fine this way. So the problem might be in VS, when launching from inside. Any idea ?

    Thanks for the help

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s