January 25, 2017 3:54 pm

Calling Windows 10 APIs From a Desktop Application

In today’s post, we’re covering how PC software can leverage the rich functionality of Windows 10. This is valuable background for the post, “Adding UWP Features to your Existing PC Software,” which goes into even more detail on the topic.

So here’s a question that generates a lot of confusion. Can PC software written in WPF, WinForms or MFC access the Windows 10 APIs used by the Universal Windows Platform (UWP)?

The answer is yes. There are some exceptions to this rule (and we’ll go over how to find them), but in general you can access the Windows 10 APIs. Or put a different way, there are no secret APIs being kept away from Windows developers.

How to access the Windows 10 APIs from WPF

You can access the Windows 10 APIs from a pre-existing WPF project. To do so, go to your Solution Explorer window and …

  1. Right click on References. Select “Add Reference…” from the context menu. On the left of the Reference Manager, choose Browse and find the following file: C:\Program Files (x86)\Windows Kits\10\UnionMetadata\winmd. Add it to your project as a reference. Note: You will need to change the filter to “All Files”.
  1. Right click on References. Select “Add Reference…” from the context menu. On the left of the Reference Manager, go to Browse and find the directory “C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETCore\v4.5”. Add System.WindowsRuntime.dll to your project.

Let’s say I want to make my WPF application location aware by calling on the Geolocator class in the Windows 10 Windows.Devices.Geolocation API. I can now do this and even use the asynchronous pattern common in UWP. Classes and methods I commonly think of as UWP code are now interweaved with classes and methods from WPF. In the example show below, I take my latitude and longitude from Geolocator and display it in a WPF MessageBox.


private async void Button_Click(object sender, RoutedEventArgs e)
{
    var locator = new Windows.Devices.Geolocation.Geolocator();
    var location = await locator.GetGeopositionAsync();
    var position = location.Coordinate.Point.Position;
    var latlong = string.Format("lat:{0}, long:{1}", position.Latitude, position.Longitude);
    var result = MessageBox.Show(latlong);
}

How do I know which APIs are available?

As mentioned above, there are exceptions to the rule that Windows 10 APIs are accessible from PC software. The first big exception concerns XAML UI APIs. The XAML framework in UWP is different from the one in WPF and you really don’t want to be mixing them up, anyways.

The second set of APIs that you can’t use are ones that depend on an app’s package identity. UWP apps have package identities while PC software does not. Package identity information can be found in the app manifest file.

How do you determine which Windows 10 APIs require a package identity and which do not? The easiest way is to refer to this MSDN topic.

Unlocking even more APIs

There’s actually a way to provide PC software with a package identity. The Desktop Bridge lets you package PC software for deployment in the Windows Store. As part of this process, you create an app manifest file for it, effectively giving it a package identity.


<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10" 
         xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"     
    <Identity Name="YOUR-APP-GUID-90cd-a7cdf2e0a180" 
              Publisher="CN=YOUR COMPANY" 
              Version="1.x.x.x" />
</Package>

If you package your PC software for the Windows Store using Desktop Bridge, then most of the APIs you couldn’t previously use, because they require a package identity, will be available to you. APIs that depend on CoreWindow will still be a problem. However, once you have a desktop bridge package, you can add a UWP component (that runs in a separate app container process), and call literally any UWP API from there.

A quicker way to get at those Windows 10 APIs

But say you don’t want to deploy to the Windows Store at the moment and just want to use some of those Windows 10 APIs. How do you get to them from your app?

There’s a NuGet package for that. It’s called UwpDesktop and is written by Vladimir Postel and Lucian Wischik. If you want to examine the source code, it is maintained on GitHub.

For demonstration purposes, let’s build a console app based on a 2012 article by Scott Hanselman on using WinRT APIs (partly to show how much easier it is to do today). After creating a new desktop console application, insert the original code from 2012 into the Main method in Program.cs.


    static void Main(string[] args)
        {
            LightSensor light = LightSensor.GetDefault();
            if (light != null)
            {
                uint minReportInterval = light.MinimumReportInterval;
                uint reportInterval = minReportInterval > 16 ? minReportInterval : 16;
                light.ReportInterval = reportInterval;

                light.ReadingChanged += (s, a) =>
                {
                    Console.WriteLine(String.Format("There was light! {0}", a.Reading.IlluminanceInLux));
                };
            }

            while (Console.ReadLine() != "q") { }

        }

This code sadly will not compile because .NET 4.5 doesn’t know what the LightSensor class is, as shown below.

Here’s how we fix that. Install the UWPDesktop package to your project using the NuGet Package Manager.

Back in Program.cs, add the following using directive to the top of the file:


using Windows.Devices.Sensors;

Next … well, actually that’s all it took. The app works now (assuming you have a light sensor attached to your computer).

And that’s the quick way to go about using Windows 10 APIs in a managed app.

How to access the Windows 10 APIs from C++

Calling Window 10 APIs isn’t just for managed code. You’ve also always been able to call them from C++ native apps.

Start by creating a new C++ Win32 application project. Alternatively, open a pre-existing C++ windows application project. Right click on your project and select Properties to bring up the configuration window. There are just four steps required to configure your application to make Windows 10 API calls.

  • Select the Configuration Properties > C/C++ > General node in the left pane. Set the Consume Windows Runtime Extension property to Yes.

  • In the same window, edit the Additional #using Directories property, adding the following entries:
    • C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcpackages;
    • C:\Program Files (x86)\Windows Kits\10\UnionMetadata;
    • C:\Program Files (x86)\Windows Kits\10\References\Windows.Foundation.UniversalApiContract\1.0.0.0;
    • C:\Program Files (x86)\Windows Kits\10\References\Windows.Foundation.FoundationContract\1.0.0.0;

  • Select the Configuration Properties > C/C++ > Code Generation node in the left pane. Set the Enable Minimal Rebuild property to No.

  • Last of all, select the Configuration Properties > General node and pick your Target Windows 10 version. Click OK to save your configuration settings.

Now you can start calling Windows APIs. Let’s finish off this app with something easy – calling the Launcher API from the C++ menubar.

Add the following using directives to the top of your project’s main CPP file:


using namespace std;
using namespace Platform;
using namespace Windows::Foundation;
using namespace Windows::System;
Include the header ROApi.h in your stdafx.h file.
// C RunTime Header Files
#include <stdlib.h>
#include <malloc.h>
#include <memory.h>
#include <tchar.h>

// TODO: reference additional headers your program requires here
#include "ROApi.h"
Initialize Windows::Foundation in your program’s entry point.
int APIENTRY wWinMain(_In_ HINSTANCE hInstance,
                     _In_opt_ HINSTANCE hPrevInstance,
                     _In_ LPWSTR    lpCmdLine,
                     _In_ int       nCmdShow)
{
    UNREFERENCED_PARAMETER(hPrevInstance);
    UNREFERENCED_PARAMETER(lpCmdLine);

    // TODO: Place code here.
    Windows::Foundation::Initialize();
}

Initialize Windows::Foundation in your program’s entry point.


int APIENTRY wWinMain(_In_ HINSTANCE hInstance,
                     _In_opt_ HINSTANCE hPrevInstance,
                     _In_ LPWSTR    lpCmdLine,
                     _In_ int       nCmdShow)
{
    UNREFERENCED_PARAMETER(hPrevInstance);
    UNREFERENCED_PARAMETER(lpCmdLine);

    // TODO: Place code here.
    Windows::Foundation::Initialize();
}

By default the Help menu only has one entry for About, so you will need to add a new button. Define the button in your Resource.h file:

#define IDM_SETTINGS  106

Then edit the *.rc file to add a new button for settings, in order to launch the Windows 10 Settings app.


IDC_HELLOWORLDWIN32TOUWP MENU
BEGIN
    POPUP "&File"
    BEGIN
        MENUITEM "E&xit",           IDM_EXIT
    END
    POPUP "&Help"
    BEGIN
        // add settings item to help menu around Line 47
        MENUITEM "&Settings ...",   IDM_SETTINGS
        MENUITEM "&About ...",      IDM_ABOUT

    END
END

Finally, override the callbacks for the menubar buttons to make them call the Windows 10 Launcher instead of whatever they are supposed to do.


LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)
    {
    case WM_COMMAND:
    {
        int wmId = LOWORD(wParam);
        // Parse the menu selections:
        switch (wmId)
        {
        case IDM_SETTINGS:
            Launcher::LaunchUriAsync(ref new Uri(L"ms-settings://"));
            break;
        case IDM_ABOUT:
            Launcher::LaunchUriAsync(ref new Uri(L"https://blogs.windows.com/buildingapps//"));
            break;
        case IDM_EXIT:
            DestroyWindow(hWnd);
            break;
        default:
            return DefWindowProc(hWnd, message, wParam, lParam);
        }
    }
    break;
    }
}

Clicking on Help > Settings will bring up the Windows 10 Settings app, while clicking on Help > About will bring you to this blog (one of my favorite places)!

Let’s go one level deeper. There are many C++ applications and games out there that use alternative build tools and alternative build processes. Many of them continue to target older versions of Windows because this is what their customers are using. How can these application developers gradually move over to the Windows 10 APIs without abandoning their Windows 7 clients?

Reusing the same steps above for building a Windows executable, one could build a DLL to encapsulate any Windows 10 calls one might need, isolating them from the rest of the application. Let’s call this new DLL UWPFeatures.dll.


void Game::UpdateTile(int score, int hiScore)
{
    HINSTANCE hinstLib;
    UPDATETILE UpdateTileProc;
    BOOL fFreeResult;

    hinstLib = LoadLibrary(TEXT("UWPFeatures.dll"));
    if (NULL != hinstLib)
    {
        UpdateTileProc = (UPDATETILE)GetProcAddress(hinstLib, "UpdateTile");
        if (NULL != UpdateTileProc)
        {
            (UpdateTileProc)(score, hiScore);
        }
        fFreeResult = FreeLibrary(hinstLib);
    }
}

Then in the original application, method calls should check to see if the UWPFeatures.dll is packaged with the application (which will be true for Windows 10 installs). If it is present, it can be loaded dynamically and called. If it isn’t present, then the original call is made instead. This provides a quick pattern for not only accessing the Windows 10 APIs from pre-existing C++ games and applications, but also for doing it in a way that doesn’t require heavy reworking of the current base code.

Wrapping up

It has sometimes been claimed that Windows 10 has secret APIs that are only accessible through UWP apps. In this post, we demonstrated that this is not the case and also went over some of the ins and outs of using Windows 10 APIs in both managed and native desktop apps. You will find links below to even more reference materials on the subject.

Did you find this post helpful? Please let us know in the comments below—and also let us know if there’s anything else you’d like us to dig into for you about this topic.

Want to go a step further? Be sure to come back next week for our next blog, where we go into more detail about adding a UWP feature to your existing PC software with the Desktop Bridge.

Updated February 2, 2017 11:52 am

Join the conversation

  1. Very nice article, thanks for sharing.
    Do you know if there is a way (not using network) for a uwp app to share informations (objects) with a desktop app?

    • I have a couple of questions off the top of my head. Are both of the apps installed on the same local machine. Is submitting to the store a requirement?

      It may be easier to take this one offline. (@mbcrump)

  2. Its System.Runtime.WindowsRuntime.dll at
    C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.netcore\v4.5 to reference.
    Looking forward for complete usage of UWP APIs in desktop apps with C#.

  3. Thanks for the article. I have two questions:
    1) If I have WPF app that should run on Win10 and for some users on Win7+ – is it possible somehow conditionally use Win10 features at runtime (meaning having the same exe deployed using ClickOnce full trust).
    2) Say I want to use ToastNotificationManager (it has DualApiPartition attribute) and I assume this API requires package identity. Is it possible to use it by just adding app manifest file without publishing to Windows Store?

    Thanks in advance for answers

    Meir

  4. One thing that I think is important, how easy is it to write third party UWP components that can be called from desktop applications too?
    Is using the DualApiPartition attribute enough? Is there anything else you need to do?

    • There is more to it than adding the DualApiPartition. I’m planning on writing more about this topic and I’ll look at including this. Thanks for dropping a note.

      • Hi, I would really appreciate, if you would tell, what else does it need than DualApiPartition. I’ve been struggling to get a simple example to work.

        I have c++ project for Windows Runtime component (Universal Windows) and a console client (c# classic desktop) for testing. Client sees the runtime component class and project compiles, but when running it, it throws TypeLoadException: Could not find Windows Runtime type ‘{name of the class}’ I’ve tried DualApiPartition-attribute with no success.

  5. actually i want to make a note about DualApiPartition attribute, that it is not presented in the attribute section of FaceDetector class. As described at https://msdn.microsoft.com/en-us/library/windows/desktop/mt695951(v=vs.85).aspx, we should conclude that this class isn’t available for classic desktop apps (wpf), but i found the next link as an example in the blog which uses the FaceDector class. So, we should think that the UWP APIs documentation yet not modified completely….?

    • It’s possible that it was missed. Please send us this by leaving feedback at the bottom of the page.