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

 

60 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

  6. Hi Stefan,
    This project works on my PC.But when I tried to start debugging on my raspberryPI with win10 iot 17763,I get this error:
    “Error : DEP6953 : Failed to launch remote debugger with the following error: ‘Command failed:0x80270254”.
    As I could debug normal uwp apps on the raspberryPi, dose this mean windows iot can’t run such project? Or is there anything that I should do to save this…?
    Appreciate it.

    Like

  7. Perfect tutorial, thank you very much for your time Stefan.
    Quick question : I’m beginning to convert my wpf app to uwp, hopefully making it to the store.
    Part of it leverages C++/CLI. Some pure C++ code makes heavy use of the Windows API.
    Is it allowed?
    If not, are there alternatives?
    Thanks again
    Eric

    Liked by 1 person

  8. I’ll be a good citizen and suggest the edits I had to make to have this project work:

    1-In the current code from GitHub, the console app is named FullTrust, so you must edit the manifest of the package project with:

    2-As mentionned in another comment, you will have to add a reference to windows.winmd from the UWP app (not the console app).
    More, the file located in
    \Program Files (x86)\Windows Kits\10\UnionMetadata\{SDK_version}\Windows.winmd
    doesn’t work, I had to take the one located at:
    \Program Files (x86)\Windows Kits\10\UnionMetadata\{SDK_version}\FACADE\Windows.winmd

    Like

    1. for some reason, in the first step of my comment above the manifest edit didn’t make it to the page. I’ll try again:

      add this to the manifest of your package project:

      Like

    2. The UWP should have a reference to Windows.winmd by default. I am surprised you had to add it manually. For the console app you will need to add it manually, if you are using WinRT APIs from the console.

      Like

  9. Yes, Indeed…sorry for my second suggestion, Don’t know how I got it messed up.
    Please discard/delete it.
    Regarding windows.winmd, many people on the web seem to have to add it manually.

    Maybe it would be nice to include it in the original post, because it takes quite a bit of browsing to figure it out, and a previous comment mentions a location that (at least for me) was not successful.

    Anyway, thanks again for your time

    Like

  10. Hi Stefan,

    It not 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 17763
    3. set the “Package” project as startup project
    4. set architecture to x64 (or x86)
    4. deploy the solution
    3. Hit F5 (While the setting of Run is Release > x86

    What could I setup wrpngly? The order of app References in Package?
    Thanks.

    Like

    1. Ok. My Step actually is:
      1. Follow Tutorial as close as possible
      2. Setup with newest SDK 17763
      3. set the “Package” project as startup project
      4. set architecture to x64 (or x86)
      5. deploy the solution
      6. Hit F5 (While the setting of Run is Release > x86
      Found out the Package.wapproj have EntryPointProjectUniqueName refer FullTrust instead of UWP….
      ..\UWP\UWP.csproj
      Could be when i references two app from package, you must references the UWP first or so…..
      Really fond of other language that really convenient restore package than Visual Studio project, even you doing package restore well, Visual studio has a mess that make the app unbuildable.

      Like

      1. In the Package project under “Applications” make sure the UWP is set as entry point. If that doesn’t help, please post the error you are getting when trying to build/run this project.

        Like

    1. Can you be more specific? What error do you get? What steps did you follow? I just tried it and it works for me, I can add both UWP and WPF projects to my Packaging project.

      Like

    1. Unfortunately VS doesn’t support this as nicely as you would expect … To debug your console app, you can start the UWP without debugging and then attach VS to the console EXE once it has been launched. You may have to add a Console.ReadLine or Thread.Sleep at the beginning if you want to debug the console app from its first instruction.

      Like

  11. Hi Stefan,
    I have downloaded this code from git.
    I have followed all the steps as mentioned here.
    When i am trying to build the solution (Where–>Package as startup project).
    I am getting this error.

    The OutputPath property is not set for project ‘Sketch-a-Window.csproj’.
    Please check to make sure that you have specified a valid combination of Configuration and Platform for this project. Configuration=’Debug’ Platform=’AnyCPU’.
    This error may also appear if some other project is trying to follow a project-to-project reference to this project, this project has been unloaded or is not included in the solution, and the referencing project does not build using the same or an equivalent Configuration or Platform.

    Like

  12. Hello everyone,
    What about release builds?
    I tried this app again, and while it works fine on Debug builds, here’s the problem I encounter when building in release :

    Error message:
    Could not find a recipe file for the referenced UWP application at
    ‘C:\Users\eric_\Source\Repos\UWP-FullTrust\UWP_FullTrust_1\UWP\bin\x64\Release\Upload\UWP.build.appxrecipe’.
    Please build the project.
    In the location above, the ‘upload’ folder is not created. I don’t have an equivalent path for Debug builds either, but it doesn’t cause any issue.

    The error occurs in the file:
    Package C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\DesktopBridge\Microsoft.DesktopBridge.targets 413

    The exact same error appears in both X86 and X64.
    The reason why I am trying to have it work, is that I have a great app ready to be submitted to the Microsoft Store, but can’t have a Release build.

    Although I have different issues, I think I might learn Something by having Stefan’app work in Release too.

    Thanks if anyone has some info’s.

    Like

      1. Hello,
        Thank you for your answer.

        My VS is 2019 ver.16.1.6.
        Everything is properly set up, because debug builds run fine.

        If you excuse me, I’d like to tell you about the issue I’m facing in my app, maybe you’ve seen this problem before? (The desktop extension part is +/- copy paste from your app)

        In release build, when hitting the call to AppServiceConnection.OpenAsync, it breaks because of :

        System.IO.FileNotFoundException’ occurred in mscorlib.dll
        Additional information: Could not load file or assembly ‘System.Runtime, Version=4.1.2.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a’ or one of its dependencies. The system cannot find the file specified.

        Would you happen to know why i’d have such a problem, only in Release?
        I’ve checked the configuration manager and the project properties many times, deleted the bin folders, removed/re-Added the references to different dependencies (Windows.winmd, runtime, etc…), and it is like I was blind, at this point…

        Thank you for your time,
        Have a nice day

        Like

    1. Ok, I got it!

      I’ll briefly post my findings here in case a reader, you, or a colleague has to go trough this mess:
      Many problems can arise if you reference a .NET standard Library from a .NET Framework assembly. Typical scenario, actually, since your .NET standard Library can be seen by both your UWP and your .NET Framework fulltrust process.
      Many users facing the error mentionned above got through it with very different (sometimes contradictory) fixes.
      The one that worked for me:

      In the app.config file of your fulltrust process, add :

      I initially tried it with a binding redirect, that didn’t do no good. It worked when I removed it.
      I just built a package, and the app certification toolkit told me it was ok.

      Ready to send to the store, hooray!

      Thank you for your blog, Stefan, it helped tremendously.
      Have a nice day

      Like

  13. Oops, once again, the code to add didn’t make it…
    In short, in you must add a dependent assembly on System.Runtime with token b03f5f7f11d50a3a in the app.config of your fulltrust process

    Like

    1. Thanks Eric for follow-up and sharing!

      Unfortunately, the comments on WordPress don’t support code very well. A good way to share a piece of code is to create a gist on GitHub and then paste the link into the comments. Just fyi.

      Like

  14. Stefan, you helped me a lot with the utility I was writing with a UWP service & a Win32 tray app. But now I have a simple/not simple question to ask – Is there a place where I can ask dumb UWP UI questions? I’m a WInForms guy jumping in hard. I finally wrapped my head around the whole XAML/code behind thing but I’ve got some questions that are probably manifestly obvious to someone that knows what they’re doing.

    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