Universal Windows App Model

Create Secondary Tiles from your Desktop Application

Vladimir Postel — Thu, 25 May 2017 07:41:07 GMT

Starting from the Insider Preview Build 16199 you can create SecondaryTiles directly from your desktop application by leveraging the Desktop Bridge. A secondary tile provides a consistent, efficient way for users to directly access specific areas within a packaged app from the Start screen. Although a user chooses whether or not to "pin" a secondary tile to the Start screen, the pinnable areas in an app are determined by the developer. Adding a Secondary tile from your WPF or Winforms is very similar to a pure UWP application, however there are few things to remember; If you have a Win32 desktop application or a desktop application you need to specify your main window handle (HWND) in the API. The SecondaryTile displays a modal dialog to the user to get a confirmation from the user. If a desktop application does not configure the SecondaryTile object to specify the owner window for modal dialogs, this object will return inaccurate data or errors. To configure a SecondaryTile object in a desktop application that uses the Desktop Bridge, follow these steps; 1. Do one of the following to enable your app to access the IInitializeWithWindow interface: o If your application is written in a managed language such as C# or Visual Basic, declare the IInitializeWithWindow interface in your app's code with the ComImport attribute as shown in the following C# example. This example assumes that your code file has a using statement for the System.Runtime.InteropServices namespace.

[ComImport]
[Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IInitializeWithWindow
{
  void Initialize(IntPtr hwnd);
}

o If your application is written in C++, add a reference to the shobjidl.h header file in your code. This header file contains the declaration of the IInitializeWithWindow interface. 2. Create the secondary tile (it is the same code you will write in UWP);

Uri square150x150Logo = new Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
SecondaryTile tile = new SecondaryTile("SecondaryTileId" + PhotoListBox.SelectedIndex,
                                                            displayName,
                                                            tileActivationArguments,
                                                            square150x150Logo,
                                                            TileSize.Default);

3. Cast the object to an IInitializeWithWindow object. Then, call the IInitializeWithWindow.Initialize method, and pass the handle of the window that you want to be the owner for the modal dialog. The following C# example shows how to pass the handle of your app's main window to the method.

IInitializeWithWindow initWindow = (IInitializeWithWindow)(object)tile;
initWindow.Initialize(System.Diagnostics.Process.GetCurrentProcess().MainWindowHandle);
tile.RequestCreateAsync();

The full sample is available on GitHub, here. To learn more about Secondary tiles and the Desktop Bridge, check out the resources below;

Resources

Any questions? Leave them in the comments! Enjoy! Vladimir Postel, Program Manager – Windows Developer Platform

Desktop Bridge: Creators Update

Arian Ghotbi — Wed, 15 Mar 2017 08:14:01 GMT

Overview

The creators update is packed with new features for app developers and end users. These features are designed to delight the developers who are in turn enabled to delight their end users as well as to provide a rich experience.

User Transition & Data Migration

Users will be encouraged to download the store version of their desktop apps. If the user already has the previous desktop version of the app, the transition experience should be as seamless as possible. As a result, the Creators Update will provide the ability to provide this smooth transition along with some best practices for app developers to follow. For a detailed blog post on this topic with code samples, please see this blog post.

User Transition: Taskbar Pins & Start Tiles

User Transition: File type associations & protocol handlers

The user may choose their favorite app to be the default app for a given file type or protocol. With the Creators Update, the developers can also transition the user's choice to use the store version of the same app.

Data Migration

User Transition: Uninstall previous desktop app

As best practice, it is recommended for developers to offer uninstallation of the previous desktop app upon first launch of the store version of the app. This will help in avoiding user confusion and potential user data corruption. Keep in mind that the user can refuse the uninstallation of the previous desktop app, so the previous and store version of the app may end up running side-by-side. It is up to the app developer to decide whether or not to block the launch of the store version of the app, until the previous desktop app is uninstalled.

Windows Explorer delight: previews, thumbnails, detailed properties, and grouping by kind

Another focus of the Creators Update release was on user delight. Store version of desktop apps can now take advantage of Windows Explorer delighters to attract users to engage with their apps more.

Preview Handler

Preview handlers are called when an item is selected to show a lightweight, rich, read-only preview of the file's contents in the view's reading pane. This is done without launching the file's associated application. XML sample:

Thumbnail Handler

In Windows Explorer, thumbnails can provide a read-only view inside the file, when the viewing is set to medium icons or higher. XML sample:

Property Handler

Microsoft Windows Search uses property handlers to extract the values of properties from items and uses the property system schema to determine how a specific property should be indexed. In addition, property handlers can be used to provide more details about a certain file in the properties dialog or in the details pane. XML sample:

Grouping files by their 'kind'

Developers can specify what 'kind' their file types are, which will enable the end users to group their files by their kind in Windows Explorer. XML sample:

Support for custom fonts installation by apps

Microsoft Windows Store apps can share their custom fonts with other Windows applications. This is done by making a few simple edits to the application manifest. XML sample:

Public out-of-process COM server support, aka Packaged COM

Developers can now add support for out-of-process COM and OLE extensions support for store version of desktop apps. This technology is referred to as Packaged COM. Historically, desktop apps would create COM extensions that other applications could use. However, in the Windows 10 Anniversary Update release of the Desktop Bridge, an application cannot expose its COM extension points as all registry entries are in its private hive and not exposed publicly to the system. Packaged COM provides a mechanism for COM & OLE entries to be declared in the manifest while the underlying subsystem handles the activation of the objects while still providing no-impact install behavior. This is a large extension and will be the focus of a future blog post.

Firewall Rules

When apps need the users to add the app as an exception to the firewall, it translates into user confusion, additional user clicks, and/or denial of exception by mistake. The Windows Security Alert does a good job of trying to educate the user, but it's still one more decision the user must make before they can use their app. In addition, subsequent app updates will result in the same dialog to pop up and take the user through the same flow. With the Creators Update, the developers can register for firewall rules ahead of time, so the users don't have to make a firewall choice prior to launching their apps (including after subsequent app updates). XML sample: *Please note that this extension needs to be declared at the package level (not at the application level).

...

Other noteworthy features

Apps can be pre-installed
Messaging Application Programming Interface (MAPI) support
Windows App Certification Kit now includes test cases for desktop bridge apps
UseURL flag enables apps to directly open files from a URL instead of downloading a local cached version of the file

Desktop Bridge: Smooth User Transition & Data Migration

Arian Ghotbi — Wed, 01 Mar 2017 08:27:41 GMT

Overview

Users will be encouraged to download the store version of their desktop apps. If the user already has the previous desktop version of the app, the transition experience should be as seamless as possible. The Creators Update will provide the ability to provide this smooth experience along with some best practices for app developers to follow. This feature is available in the Creators Update. You can use the following GitHub sample: https://github.com/Microsoft/DesktopBridgeToUWP-Samples/tree/master/Samples/DesktopAppTransition

User Transition: Taskbar Pins & Start Tiles

Many users typically pin their favorite or most used apps to the taskbar pin or the start menu. This enables them to access the app much faster. With the Creators Update, app developers can re-route the taskbar pins and the start tile shortcuts to point to the store version of the desktop app. Here’s a sample AppXManifest.xml snippet which shows the declaration for this transition. You must use the following namespace:

xmlns:rescap3="https://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities/3"

This extension must be under the element.

If you know your app’s Application User Model ID, then it’s recommended that you use it for the transition. Otherwise, you can use the path to your app’s shortcut (.lnk) file. If you don’t know where your app installs the shortcut, the easiest way to find it is to right-click on the app’s name from the start menu and select ‘Open file location’. You have to make sure the path you use in the AppXManifest.xml uses the environment variables (one of %USERPROFILE%, %APPDATA%, or %PROGRAMDATA%). Most likely, the shortcut is under %PROGRAMDATA%.

User Transition: File type associations & protocol handlers

The user may choose their favorite app to be the default app for a given file type or protocol. With the Creators Update, the developers can also transition the user’s choice to use the store version of the same app. Here’s the AppXManifest.xml snippet that shows how the Filetype Association is transitioned. The Protocol Handlers are transition in the same way. You must use the following namespace:

xmlns:uap3=”https://schemas.microsoft.com/appx/manifest/uap/windows10/3”

As part of this transition, you need to provide the Programmatic Identifier.



   
      Foo.Bar.1
  
 …

Data Migration

As best practice, it is recommended for developers to attempt to migrate previous user data from the desktop app, upon first launch of the store version of the same app. This will delight the users, so they can ‘pick up where they left off’. Please refer to the code sample below to learn about the best practices around how to do this on first launch, while recognizing which version of your desktop app you are running (store version vs previous desktop version).

User Transition: Uninstall previous desktop app

//Please refer to the following blogpost to learn how you can use this method:
//https://blogs.msdn.microsoft.com/appconsult/2016/11/03/desktop-bridge-identify-the-applications-context/
if (IsRunningAsUwp())
{
   //Detect if there is previous user data
   //In this example, the previous user data was in the ApplicationData You should change this based on where the previous data was

   String sourceDir = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData) + "\\AppName";
   if(Directory.Exists(sourceDir))
   {
      String migrateMessage = "Would you like to migrate your data from the previous version of this app?";
      MessageBoxResult migrateResult = MessageBox.Show(migrateMessage, "Data Migration", MessageBoxButton.YesNo);

      if (migrateResult.Equals(MessageBoxResult.Yes))
      {
         //Migrate user data
         String destinationDir = Windows.Storage.ApplicationData.Current.LocalFolder.Path + "\\AppName";

         //If you are moving data from one of the redirected folders, you need to use robocopy.exe to bypass redirection. This is the only time you should bypass redirection
         //Redirected folders: https://docs.microsoft.com/en-us/windows/uwp/porting/desktop-to-uwp-behind-the-scenes
         //Robocopy.exe: https://technet.microsoft.com/en-us/library/cc733145(v=ws.11
        //Otherwise, you should move files using System.IO

         if (runProcess("robocopy.exe", sourceDir + " " + destinationDir + " /move") > 1 )
         {
            //Migration was unsuccessful -- App Developer can choose to block/retry/other action
         }
      }
   }


   //Detect if the previous version of the Desktop App is installed
   //Typically your uninstall string lives under this

   String uninstallString = (String)Microsoft.Win32.Registry.GetValue(@"HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\{7AD02FB8-B85E-44BC-8998-F4803BA5A0E3}\", "UninstallString", null);

   if (uninstallString != null)
   {
      String uninstallMessage = "It is recommended that you uninstall the old version of this application in order to have a better experience. Would you like to uninstall the previous version of your app now?";
      MessageBoxResult uninstallResult = MessageBox.Show(uninstallMessage, "Uninstall the previous version", MessageBoxButton.YesNo);

      if (uninstallResult.Equals(MessageBoxResult.Yes))
      {
         //Run the uninstaller by using Process (see private method below)
         string[] uninstallArgs = uninstallString.Split(' ');
         if (runProcess(uninstallArgs[0], uninstallArgs[1]) != 0)
         {
            //Uninstallation was unsuccessful - App Developer can choose to block the app here
         }
      }
   }
}


private int runProcess(string appName, string arguments)
{
   Process process = new Process();
   process.StartInfo.FileName = appName;
   process.StartInfo.Arguments = arguments;
   process.StartInfo.CreateNoWindow = true;
   process.Start();
   process.WaitForExit();
   return process.ExitCode;
}

CompactOverlay mode - aka Picture-in-Picture

rkarman — Sat, 11 Feb 2017 01:19:12 GMT

Note: The new feature(s) covered in this post are available to Windows Insiders running build 15021 or newer. New in Creators Update: In the most recent Windows 10 Creators Update we introduce a new compact overlay mode for UWA app windows. When an app window enters compact overlay mode it’ll be shown above other windows so it won’t get blocked. This allows users to continue to keep an eye on your app's content even when they are working with something else. The canonical example of an app taking advantage of this feature is a media player or a video chat app.

Quick Summary

The ViewMode APIs that powers the CompactOverlay mode described in this blogpost have three parts:

the ability to check if CompactOverlay mode is available to the app at all
the ability to transition an existing view in and out of CompactOverlay mode
the ability to show a standalone view in CompactOverlay mode.

If you're not familiar with multiple views, just skip that part of this blogpost for now or go explore the MultipleViews github sample then come back for that part.

The basics

For a single view app, which most UWP apps are, adding a compact overlay option to the app is easy and straight forward. First you put in some kind of UX affordance that lets the user switch modes (since this is a sample we go with a button), check if the view mode we want to enable is available (if so, make the button visible) and then change the view mode when the user taps on the UX affordance.

Is CompactOverlay supported?

Since the intent of the Compact Overlay view mode is a very specific type of user experience, it is not necessarily supported across all Windows devices and interaction modes. Best practice for the app developer is therefore to check whether it is supported before enabling the UX affordance in the app that lets users access this functionality.

if (ApplicationView.GetForCurrentView().IsViewModeSupported(ApplicationViewMode.CompactOverlay))
{
    compactOverlayButton.Visibility = Visibility.Visible;
}

Switching the view into CompactOverlay mode

At its core the CompactOverlay API is really about this one function call:

private async void compactOverlayButton_Click(object sender, RoutedEventArgs e)
{
    bool modeSwitched = await ApplicationView.GetForCurrentView().TryEnterViewModeAsync(ApplicationViewMode.CompactOverlay);
}

This API operates on the current ApplicationView of the app, transitioning it from one view mode into another, which in this case is from the default view mode into CompactOverlay mode. When this happens you will note some attributes changing for the window:

it will most likely become smaller than your app window was prior to the call
it will be moved to the top-right corner area of the screen
if you move focus away from the CompactOverlay window the title bar will disappear

To get back to your normal app layout window just call the same API again, but this time with a ApplicationViewMode.Default:

private async void standardModeButton_Click(object sender, RoutedEventArgs e)
{
    bool modeSwitched = await ApplicationView.GetForCurrentView().TryEnterViewModeAsync(ApplicationViewMode.Default);
}

This will restore your application view to the size and position it had before going into CompactOverlay mode and you can navigate the user back to the app's main layout again.

Providing options for the view

When going into CompactOverlay you probably have a very specific experience in mind for the user, such as providing a mini-view of a video chat, or a certain scaled down version of a video where you want to make sure it can maintains its aspect ratio in the new view configuration. To enable this we give you the ability to provide a ViewModePreferences object when calling the API. At the time of this post the only preference you can set that will be considered by the system when displaying your view is the CustomSize property which allows you to set the size of the view as it switches into the new mode. ViewModePreference works a little different then other preference objects that you may have worked with in the windowing space before in that you have to create a default version of it for the mode you want and then then modify the object you get back, instead of just calling 'new' and setting all the preferences to the correct values. The reason for this is that we want to make sure that future additions to the object gets set properly for the mode you are modifying and that vital preferences are not missed as the bells'n'whistles of this API are extended. If we wanted to set the window size to 320x200 when switching into CompactOverlay the code looks like this:

private async void compactOverlayButton_Click(object sender, RoutedEventArgs e)
{
    ViewModePreferences compactOptions = ViewModePreferences.CreateDefault(ApplicationViewMode.CompactOverlay);
    compactOptions.CustomSize = new Windows.Foundation.Size(320, 200);
    bool modeSwitched = await ApplicationView.GetForCurrentView().TryEnterViewModeAsync(ApplicationViewMode.Default, compactOptions);
}

Working with a separate view for CompactOverlay

As mentioned in the introduction you can also have new views show up as CompactOverlay views while your main app view remains untouched. The principle for this is the same as with multiview apps but we have added a new switcher API for transitioning the view directly into the specified mode as it is shown so that you avoid the flicker that would be the result of first showing the view as standalone (using TryShowAsStandaloneAsync) and then calling TryEnterViewMode on it. The switcher API follows the same pattern as the API that acts on the current view, where you provide the mode you want to switch into and, if needed, the preferences for the view. In its most simple form the call would look like this:

private async void ShowCompactView()
{
    await CoreApplication.CreateNewView().Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        var frame = new Frame();
        compactViewId = ApplicationView.GetForCurrentView().Id;
        frame.Navigate(typeof(SecondaryCompactViewPage));
        Window.Current.Content = frame;
        Window.Current.Activate();
        ApplicationView.GetForCurrentView().Title = "CompactOverlay Window";
    });
    bool viewShown = await ApplicationViewSwitcher.TryShowAsViewModeAsync(compactViewId, ApplicationViewMode.CompactOverlay);
}

You can of course also set the preferred size of your pop-out window just as you did with the TryEnterViewMode, just add the ViewModePreferences to the TryShowAsViewModeAsync call and you're done! For more details on how to work with CreateNewView, view switching APIs in general, and best practices for view lifetime control - please refer to the MultipleViews github sample.

How to ensure your toast notifications continue to work when converting your win32 app into a Windows Store app using project Centennial

Arian Ghotbi — Tue, 31 Jan 2017 03:27:48 GMT

[Originally posted by Lei Xu] As you may already know, developer can now bring their existing apps and games to the Windows Store with the Desktop Bridge, known as project Centennial. For developers who has been integrating with toast notification features in Windows 8 and Windows 10, when you turn your app into a Windows Store app using project Centennial, you may realize that your toast notification does not work as desired – an incorrect/unresolved string will show up in Action Center at where the application title is supposed to be shown. This post summarizes on why it happens and how to fix it with a simple change to your code.

Why does it break?

In Windows 8/8.1, we enabled support for desktop Win32 apps to send local toast notifications – by enabling win32 apps to do 2 things:

be able to register with the notification platform and;
call WinRT APIs to send toast.

What did we do to enable those respectively?

A registration with notification platform requires an app identity, but win32 apps don’t really have modern app identities. This problem is solved by by allowing win32 apps to provide us with a “fake” app identity – through creating a desktop shortcut.
The app will then need to call the method overload that takes this manually created application id to indicate which identity is trying to send this notification, as shown:

?

ToastNotificationManager.CreateToastNotifier(appId).Show(toast);

Windows Store apps converted through project Centennial on the other side, already come with proper app identities just like any regular UWP app, so if the win32 app is converted without changing any of its previous code, then it will create a conflict as below:

The shortcut creation will be skipped for the converted Store app during app deployment because the deployment path is different, however;
The app will still call the same overload mentioned above to pass in the fake app id that the OS can no longer resolve, since the shortcut is not there, thus results in unresolved string.

How to fix it?

Any app in this situation will need to simply change a line of their code to call

ToastNotificationManager.CreateToastNotifier().Show(toast);

without passing in the manually created appId and just let the app identity get resolved by the OS like any other modern apps do.

Why didn’t we fix this for you?

The same method overload can also be used by Windows Store apps to send toast notifications on behalf of other apps in the same package. Once a win32 app is converted to Windows Store app through project Centennial, Windows just see it as a regular Store app without knowing its true intention behind calling CreateToastNotifier(appId). To prevent us from getting your real intention wrong and further break some other unexpected scenarios, we ask the developers to make the change here during your conversion process.

“UWPDesktop” NuGet Package Version 14393

Vladimir Postel — Wed, 14 Dec 2016 03:01:00 GMT

The UWPDesktop NuGet package is here to improve the developer experience with Visual Studio when walking along the Desktop Bridge. The Desktop Bridge allows you to call UWP APIs directly from your WinForms, WPF or VB application. You can use APIs such as Live tiles, Notifications, App Services and many more! Previously, calling UWP APIs from a converted app was a confusing process. You had to find and reference the right .dll or .winmd, and it often wasn’t obvious which one to choose. For example, to use "await" on WinRT types, you had to reference the System.Runtime.WindowsRuntime.dll (c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETCore\v4.5\System.Runtime.WindowsRuntime.dll), which was actually from Windows 8.1 and therefore only worked in conjunction with "facade\windows.winmd" (c:\Program Files (x86)\Windows Kits\10\UnionMetadata\Facade\Windows.WinMD)


AppServiceConnectionStatus status = await connection.OpenAsync();

Confusing, right? The new way is much simpler – just include the latest UWPDesktop NuGet package to your project, and you’re ready to call any supported UWP API without needing additional references. You have two options for installing the package:

In Visual Studio, right click on your project, select “Manage NuGet Packages”, and search for and install the UWPDesktop package (as shown in the screen shot below):
Use the Package Manager Console


Install-Package UwpDesktop

Warnings for unsupported WinRT APIs

Not all modern APIs can be called directly from your desktop application; for example, you still can’t use XAML or SecondaryTile in your WinForms app. The UWPDesktop NuGet package makes your life easier by raising a warning if you try and call an unsupported API.

Resources

Any questions? Leave them in the comments! Enjoy! Vladimir Postel, Program Manager – Windows Developer Platform