How to launch the default app for a file (Windows Store apps using JavaScript and HTML)

Learn how to launch the default app for a file. Many apps need to work with files that they cannot 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.

The following steps will show you how to use the Windows.System.Launcher API to launch the default handler for a file that your app cannot 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.

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.

You should 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.

// 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 may not have an app installed to handle the file that you are launching. By default, Windows will handle these cases by providing the user with a link to search for an appropriate app on the store. If you would like to give the user a specific recommendation for which app to acquire in this scenario, you may 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. Windows will use this information 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.

// 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
        }
      });
  });

Remarks

Your app cannot 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. The user should always have to take some action to initiate a file launch. . If you attempt to launch a file and your app is not in the foreground the launch will fail and your error callback will be invoked.

You cannot launch file types that contain code or script if they are executed automatically by the system, such as .exe, .msi, and .js files. This restriction protects users from potentially malicious files that could modify the system. You can use this method to launch file types that can contain script if they are executed by an application that isolates the script, such as .docx files. Applications like Word keep the script in .docx files from modifying the system. If you attempt 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 you should 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.

If you attempt 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 you should 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.

Complete example

See Association launching sample.

Related topics

Tasks

How to handle file activation

How to launch the default app for a URI

Guidelines

Guidelines and checklist for file types and URIs

Reference

Windows.Storage.StorageFile

Windows.System.Launcher.launchFileAsync

Build date: 10/26/2012