How to launch the default app for a file (HTML)

Article
08/31/2015

Learn how to launch the default app for a file. Many apps need to work with files that they can't handle themselves. For example, e-mail apps receive a variety of file types and need a way to launch these files in their default handlers.

These steps show how to use the Windows.System.Launcher API to launch the default handler for a file that your app can't handle itself.

Instructions

Step 1: Get the file

First, get a Windows.Storage.StorageFile object for the file.

If the file is included in the package for your app, you can use the Package.installedLocation property to get a Windows.Storage.StorageFolder object and the Windows.Storage.StorageFolder.getFileAsync method to get the StorageFile object.

If the file is in a known folder, you can use the properties of the Windows.Storage.KnownFolders class to get a StorageFolder and the getFileAsync method to get the StorageFile object.

Step 2: Launch the file

Windows provides several different options for launching the default handler for a file. These are described in the following chart and in the sections below.

Option	Method	Description
Default launch	LaunchFileAsync(IStorageFile)	Launch the specified file with the default handler.
Open With launch	LaunchFileAsync(IStorageFile, LauncherOptions)	Launch the specified file letting the user pick the handler through the Open With dialog.
Launch with a recommended app fallback	LaunchFileAsync(IStorageFile, LauncherOptions)	Launch the specified file with the default handler. If no handler is installed on the system, recommend an app in the store to the user.
Launch with a desired remaining view	LaunchFileAsync(IStorageFile, LauncherOptions) (Windows-only)	Launch the specified file with the default handler. Specify a preference to stay on screen after the launch and request a specific window size. Windows 8.1: LauncherOptions.DesiredRemainingView isn't supported until Windows 8.1 and Windows Server 2012 R2. Windows Phone: LauncherOptions.DesiredRemainingView isn't supported for Windows Phone.

Default launch

Call the Windows.System.Launcher.launchFileAsync(IStorageFile) method to launch the default app. This example uses the Windows.Storage.StorageFolder.getFileAsync method to launch an image file, test.png, that is included in the app package.


// Path to the file in the app package to launch
var imageFile = "images\\test.png";

// Get the image file from the package's image directory
Windows.ApplicationModel.Package.current.installedLocation.getFileAsync(imageFile).then(
  function (file) {
    // Launch the retrieved file using the default app
    Windows.System.Launcher.launchFileAsync(file).then(
      function (success) {
        if (success) {
            // File launched
        } else {
            // File launch failed
        }
      });
  });

Open with launch

Call the Windows.System.Launcher.launchFileAsync(IStorageFile, LauncherOptions) method with LauncherOptions.displayApplicationPicker set to true to launch the app that the user selects from the Open With dialog box.

We recommend that you use the Open With dialog box when the user may want to select an app other than the default for a particular file. For example, if your app allows the user to launch an image file, the default handler will likely be a viewer app. In some cases, the user may want to edit the image instead of viewing it. Use the Open With option along with an alternative command in the AppBar or in a context menu to let the user bring up the Open With dialog and select the editor app in these types of scenarios.

The Open With dialog for a .png file launch. The dialog contains a checkbox which specifies if the user’s choice should be used for all .png files or just this one .png file. The dialog contains four app options for launching the file and a ‘More options’ link.


// Path to the file in the app package to launch
var imageFile = "images\\test.png";

// Get the image file from the package's image directory
Windows.ApplicationModel.Package.current.installedLocation.getFileAsync(imageFile).then(
  function (file) {
    // Set the show picker option
    var options = new Windows.System.LauncherOptions();
    options.displayApplicationPicker = true;

    // Launch the retrieved file using the selected app
    Windows.System.Launcher.launchFileAsync(file, options).then(
      function (success) {
        if (success) {
            // File launched
        } else {
            // File launch failed
        }
      });
  });

Launch with a recommended app fallback

In some cases, the user might not have an app installed to handle the file that you are launching. By default, the operating system handles these cases by providing the user with a link to search for an appropriate app on the store. If you want to give the user a specific recommendation for which app to acquire in this scenario, you can do so by passing that recommendation along with the file that you are launching. To do this, call the Windows.System.Launcher.launchFileAsync(IStorageFile, LauncherOptions) method with LauncherOptions.preferredApplicationPackageFamilyName set to the package family name of the app in the store that you want to recommend. Then, set the LauncherOptions.preferredApplicationDisplayName to the name of that app. The operating system uses this info to replace the general option to search for an app in the store with a specific option to acquire the recommended app from the store.

Note You must set both of these options to recommend an app. Setting one without the other will result in a failure.

The Open With dialog for a .contoso file launch. Since .contoso does not have a handler installed on the machine the dialog contains an option with the Store icon and text which points the user to the correct handler on the Store. The dialog also contains a ‘More options’ link'.


// Path to the file in the app package to launch
var imageFile = "images\\test.contoso";

// Get the image file from the package's image directory
Windows.ApplicationModel.Package.current.installedLocation.getFileAsync(imageFile).then(
  function (file) {
    // Set the recommended app
    var options = new Windows.System.LauncherOptions();
    options.preferredApplicationPackageFamilyName = "Contoso.FileApp_8wknc82po1e";
    options.preferredApplicationDisplayName = "Contoso File App";


    // Launch the retrieved file pass in the recommended app 
    // in case the user has no apps installed to handle the file
    Windows.System.Launcher.launchFileAsync(file, options).then(
      function (success) {
        if (success) {
            // File launched
        } else {
            // File launch failed
        }
      });
  });

Launch with a Desired Remaining View (Windows-only)

Source apps that call LaunchFileAsync can request that they remain on screen after a file launch. By default, Windows attempts to share all available space equally between the source app and the target app that handles the file. Source apps can use the DesiredRemainingView property to indicate to the operating system that they prefer their app window to take up more or less of the available space. DesiredRemainingView can also be used to indicate that the source app doesn't need to remain on screen after the file launch and can be completely replaced by the target app. This property only specifies the preferred window size of the calling app. It doesn't specify the behavior of other apps that may happen to also be on screen at the same time.

Note Windows takes into account multiple different factors when it determines the source app's final window size, for example, the preference of the source app, the number of apps on screen, the screen orientation, and so on. By setting DesiredRemainingView, you aren't guaranteed a specific windowing behavior for the source app.

Windows 8.1: LauncherOptions.DesiredRemainingView isn't supported until Windows 8.1 and Windows Server 2012 R2.

Windows Phone: LauncherOptions.DesiredRemainingView isn't supported for Windows Phone.

// Path to the file in the app package to launch
var imageFile = "images\\test.png";

// Get the image file from the package's image directory
Windows.ApplicationModel.Package.current.installedLocation.getFileAsync(imageFile).done(
  function (file) {
    // Set the desired remaining view
    var options = new Windows.System.LauncherOptions();
    options.desiredRemainingView = Windows.UI.ViewManagement.ViewSizePreference.useLess;

    // Launch the retrieved file using the selected app
    Windows.System.Launcher.launchFileAsync(file, options).done(
      function (success) {
        if (success) {
            // File launched
        } else {
            // File launch failed
        }
      });
  });

Remarks

Your app can't select the app that is launched. The user determines which app is launched. The user can select either a Windows Store app or a desktop app.

When launching a file, your app must be the foreground app, that is, it must be visible to the user. This requirement helps ensure that the user remains in control. To meet this requirement, make sure that you tie all file launches directly to the UI of your app. Most likely, the user must always take some action to initiate a file launch. If you try to launch a file and your app isn't in the foreground, the launch will fail, and your error callback will be invoked.

You can't launch file types that contain code or script if they are executed automatically by the operating system, such as, .exe, .msi, and .js files. This restriction protects users from potentially malicious files that could modify the operating system. You can use this method to launch file types that can contain script if they are executed by an app that isolates the script, such as, .docx files. Apps like Microsoft Word keep the script in .docx files from modifying the operating system.

If you try to launch a restricted file type, the launch will fail and your error callback will be invoked. If your app handles many different types of files and you expect that you will hit this error, we recommend that you provide a fallback experience to your user. For example, you could give the user an option to save the file to the desktop, and they could open it there.